Share Attributes with peer

There are many situations in which an Identity wants to share an IdentityAttribute or a RelationshipAttribute with another Identity, for example:

A university wants to give a student the street address of its student administration so that they can send it documents by post.
An organization wants to share its email address with its members in order to be able to receive emails from them.
A company wants to share the customer number of one of its customers with another company.

In this guide, we explain how a Connector, hereinafter referred to as the Sender, can share an Attribute with another Connector, the so-called Recipient. Since understanding this sharing process requires knowledge about Requests and how to use them in general, you should take a look at our Request and Response introduction before continuing reading this guide.

Please note that the general procedure is the same if the Connector wants to share an Attribute with an App user instead of another Connector. For reasons of clarity, this guide focuses on the sharing process with two Connectors.

The Sender wants to share an Attribute with the Recipient. To do this, the Sender must first create a suitable Request, which it can then send to the Recipient. In the following subsections, we describe the general appearance of a Request for sharing Attributes.

Role of ShareAttributeRequestItem

For sharing a single Attribute, the Sender needs to insert a single RequestItem of type ShareAttributeRequestItem into the items property of the Request. The Sender can only share an Attribute that already exists as a LocalAttribute and, in the case of IdentityAttributes, is owned by it. The latter means that the Address of the Sender is contained in the content.owner property of the corresponding LocalAttribute. The id of the LocalAttribute must be inserted into the sourceAttributeId property and the content of the LocalAttribute into the attribute property of the ShareAttributeRequestItem.

To get a list of all LocalAttributes that are owned by the Sender, proceed as described in the Query Attributes use case documentation and use content.owner=<Address of Sender> as query parameter. Please note that the <...> notation is used as a placeholder for the actual data as usual. If the id of a LocalAttribute is known, the underlying IdentityAttribute or RelationshipAttribute within its content property can be displayed by consulting the Get Attribute use case description and specifying the id of the LocalAttribute.

Combinations and usage scenarios of ShareAttributeRequestItem

The following table provides an overview of the possible kinds of Attributes that the Sender can share with the Recipient using the ShareAttributeRequestItem. It must be taken into account whether the Attribute is an IdentityAttribute or a RelationshipAttribute and which Identity is its owner. If the Sender wants to share a RelationshipAttribute with the Recipient, a distinction must be made between which Identities the Relationship in question exists.

Attribute Type	Attribute Owner	Possible?	Automation	Examples/Reason
Identity	Sender	✓	`AUTO ACCEPT`	Company sends new customer the address of the company.
Identity	Recipient	✗	`N/A`	It makes no sense to share the Attribute with the Recipient, because he already owns it.
Identity	Third Party	✗	`N/A`	You cannot share an Attribute of which you are not the owner.
Identity	`<empty>`	✓	`AUTO ACCEPT`	An empty owner defaults to an Attribute with `owner=<Sender>`.
Relationship	Sender	✓	`USER DECISION` / `NOT ALLOWED` (depending on confidentiality)	A user can share RelationshipAttributes of any Relationship with any other Relationship (if the confidentiality of the RelationshipAttribute is protected or public). Example: Share customer ID from company A with company B (User is owner of RelationshipAttribute).
Relationship	Recipient	✗	`N/A`	It makes no sense to share the Attribute with the Recipient, because he already owns it.
Relationship	Third Party	✓	`USER DECISION` / `NOT ALLOWED` (depending on confidentiality)	A user can share RelationshipAttributes of any Relationship with any other Relationship (if the confidentiality of the RelationshipAttribute is protected or public). Example: Share customer ID from company A with company B (Company A is owner of RelationshipAttribute), e.g. Payback number.
Relationship	`<empty>`	✓	`AUTO ACCEPT`	An empty owner defaults to an Attribute with `owner=<Sender>`.

We assume that the Integrator of the Sender has created an IdentityAttribute of type BirthDate for the Sender by following the instructions of our Create Attributes for yourself scenario documentation. This IdentityAttribute is stored locally within the content property of a corresponding LocalAttribute of the Sender.

{
  "@type": "LocalAttribute",
  "id": "<ID of LocalAttribute>",
  "createdAt": "<creation date of LocalAttribute>",
  "content": {
    "@type": "IdentityAttribute",
    "owner": "<Address of Sender>",
    "value": {
      "@type": "BirthDate",
      "day": <day of birth date>,
      "month": <month of birth date>,
      "year": <year of birth date>
    }
  }
}

In our example, the Sender wants to share the IdentityAttribute with the Recipient. To do so, it needs to insert the id of the corresponding LocalAttribute into the sourceAttributeId property and the IdentityAttribute itself into the attribute property of the ShareAttributeRequestItem contained within the items property of the Request for sharing Attributes. The value of the mustBeAccepted property of the ShareAttributeRequestItem is set to true in this example.

{
  "@type": "Request",
  "items": [
    {
      "@type": "ShareAttributeRequestItem",
      "mustBeAccepted": true,
      "attribute": {
        "@type": "IdentityAttribute",
        "owner": "<Address of Sender>",
        "value": {
          "@type": "BirthDate",
          "day": <day of birth date>,
          "month": <month of birth date>,
          "year": <year of birth date>
        }
      },
      "sourceAttributeId": "<ID of LocalAttribute>"
    }
  ]
}

We now consider the case in which the Sender has an active Relationship with a third party and owns a RelationshipAttribute, which has already been created by using an appropriate Request, of type ProprietaryString of this Relationship. The Sender can request to share this RelationshipAttribute with the Recipient if its confidentiality is "protected" or "public". In our example, we assume that the confidentiality of the RelationshipAttribute is "public" and that it is stored locally within the content property of a corresponding LocalAttribute with a LocalAttributeShareInfo of the Sender.

{
  "@type": "LocalAttribute",
  "id": "<ID of LocalAttribute>",
  "createdAt": "<creation date of LocalAttribute>",
  "content": {
    "@type": "RelationshipAttribute",
    "owner": "<Address of Sender>",
    "key": "<key of RelationshipAttribute>",
    "confidentiality": "public",
    "value": {
      "@type": "ProprietaryString",
      "title": "<title of RelationshipAttribute>",
      "value": "<actual value of RelationshipAttribute>"
    }
  },
  "shareInfo": {
    "peer": "<Address of third party>",
    "requestReference": "<ID of Request used for creating RelationshipAttribute>"
  }
}

To share the RelationshipAttribute with the Recipient, the Sender needs to insert the id of the corresponding LocalAttribute into the sourceAttributeId property and the RelationshipAttribute itself into the attribute property of the ShareAttributeRequestItem contained within the items property of the Request for sharing Attributes. The value of the mustBeAccepted property of the ShareAttributeRequestItem is set to true in this example.

{
  "@type": "Request",
  "items": [
    {
      "@type": "ShareAttributeRequestItem",
      "mustBeAccepted": true,
      "attribute": {
        "@type": "RelationshipAttribute",
        "owner": "<Address of Sender>",
        "key": "<key of RelationshipAttribute>",
        "confidentiality": "public",
        "value": {
          "@type": "ProprietaryString",
          "title": "<title of RelationshipAttribute>",
          "value": "<actual value of RelationshipAttribute>"
        }
      },
      "sourceAttributeId": "<ID of LocalAttribute>"
    }
  ]
}

The table of the Combinations and usage scenarios of the ShareAttributeRequestItem contains further information on sharing RelationshipAttributes in different application scenarios.

Sharing is not limited to just a single Attribute, but it is possible to request the sharing of multiple Attributes at the same time. For this purpose, several ShareAttributeRequestItems or suitable RequestItemGroups can be inserted into the items property of the Request for sharing Attributes. If you want to use a RequestItemGroup in order to share multiple Attributes with the Recipient at the same time, you must insert corresponding ShareAttributeRequestItems into the items property of it.

Send and receive the Request

The Sender that wants to share an Attribute with the Recipient may or may not already have a Relationship with the Recipient. Depending on which is the case, a different method can be used to send the Request for sharing Attributes. There are two ways to send the Request for sharing Attributes created by the Sender to the Recipient.

Request via RelationshipTemplate

If there is currently no Relationship between the Sender and the Recipient, this approach must be used. However, it is also possible for the Sender to use a RelationshipTemplate to send a Request to the Recipient if there is already an active Relationship between them. All details on how to send and receive a Request via a RelationshipTemplate in general can be found in the Requests via RelationshipTemplates guide.

Request via Message

The Sender only has the option of sending a Request to the Recipient via a Message if there is already an active Relationship between them. All information on how to send and receive a Request via a Message can be found in the Requests via Messages guide.

Accept the Request and get the Attributes

After the Recipient has received the Request for sharing Attributes, it can accept it to get all or some of the Sender’s shared Attributes. To do this, proceed as described in the Accept incoming Request use case documentation and specify the id of the received Request. Also, you need to decide and specify for each ShareAttributeRequestItem and RequestItemGroup contained in the Request for sharing Attributes whether you want to accept or reject it.

If the Recipient does not want to get any of the Sender’s shared Attributes and, therefore, does not want to accept the Request for sharing Attributes of the Sender, it can reject it as a whole too. For that, follow the instructions of the Reject incoming Request use case.

Accept a ShareAttributeRequestItem

If the Recipient agrees to get one of the Sender’s shared Attributes, it can accept the associated ShareAttributeRequestItem contained in the Request for sharing Attributes. The AcceptRequestItemParameters must be used for this. The acceptance of a ShareAttributeRequestItem leads to the creation of a corresponding LocalAttribute with a LocalAttributeShareInfo contained within its shareInfo property. The content of the LocalAttribute is the underlying attribute of the ShareAttributeRequestItem. Based on this, an appropriate AcceptResponseItem of type ShareAttributeAcceptResponseItem is generated, which incorporates the id of the created LocalAttribute with the LocalAttributeShareInfo in its attributeId property. This will be contained within the items property of the Response to the Request for sharing Attributes that will be transferred to the Sender.

Reject a ShareAttributeRequestItem

Even if the Recipient accepts the Request for sharing Attributes as a whole, it may decide not to accept all of the Sender’s shared Attributes. To be more precise, the Recipient has the option of rejecting ShareAttributeRequestItems that have the value false specified in their mustBeAccepted property. To reject a ShareAttributeRequestItem, use the RejectRequestItemParameters. The rejection of a ShareAttributeRequestItem leads to the creation of a corresponding ResponseItem of type RejectResponseItem. This will be contained within the items property of the Response to the Request for sharing Attributes.

Example of accepting a RequestItemGroup

Let’s look at an example where the Sender wants to share its DisplayName and contact information in the form of an EMailAddress or a PhoneNumber with the Recipient. For this purpose, the Sender creates a Request for sharing Attributes, which contains a ShareAttributeRequestItem belonging to the DisplayName and a RequestItemGroup belonging to the contact information in its items property. The RequestItemGroup itself includes two ShareAttributeRequestItems in its items property, namely one for the EMailAddress and one for the PhoneNumber.

{
  "@type": "Request",
  "items": [
    {
      "@type": "ShareAttributeRequestItem",
      "mustBeAccepted": true,
      "attribute": {
        "@type": "IdentityAttribute",
        "owner": "<Address of Sender>",
        "value": {
          "@type": "DisplayName",
          "value": "<display name that the Sender wants to share>"
        }
      },
      "sourceAttributeId": "<ID of LocalAttribute which is the source of the DisplayName>"
    },
    {
      "@type": "RequestItemGroup",
      "mustBeAccepted": true,
      "items": [
        {
          "@type": "ShareAttributeRequestItem",
          "mustBeAccepted": true,
          "attribute": {
            "@type": "IdentityAttribute",
            "owner": "<Address of Sender>",
            "value": {
              "@type": "EMailAddress",
              "value": "<email address that the Sender wants to share>"
            }
          },
          "sourceAttributeId": "<ID of LocalAttribute which is the source of the EMailAddress>"
        },
        {
          "@type": "ShareAttributeRequestItem",
          "mustBeAccepted": false,
          "attribute": {
            "@type": "IdentityAttribute",
            "owner": "<Address of Sender>",
            "value": {
              "@type": "PhoneNumber",
              "value": "<phone number that the Sender wants to share>"
            }
          },
          "sourceAttributeId": "<ID of LocalAttribute which is the source of the PhoneNumber>"
        }
      ]
    }
  ]
}

In our example, the Sender only requires the Recipient to accept the DisplayName and the EMailAddress, which is why the individual ShareAttributeRequestItems and the RequestItemGroup within the Request have specified corresponding values in their mustBeAccepted property. We assume that the Recipient wants to accept the Request and all its ShareAttributeRequestItems with the exception of the PhoneNumber.

If the Recipient wants to accept the Request for sharing Attributes, it must accept all ShareAttributeRequestItems for which the mustBeAccepted property is set to true. It is therefore not permitted for the Recipient to refuse to accept the DisplayName or the EMailAddress shared by the Sender.

The Recipient accepts the DisplayName of the Sender and accepts at least one ShareAttributeRequestItem of the RequestItemGroup. Also, the Recipient accepts the EMailAddress and rejects the PhoneNumber of the Sender. It therefore responds to the Request for sharing Attributes as follows:

{
  "items": [
    {
      // Accept DisplayName
      "accept": true
    },
    {
      // Accept RequestItemGroup
      "accept": true,
      "items": [
        {
          // Accept EMailAddress
          "accept": true
        },
        {
          // Reject PhoneNumber
          "accept": false
        }
      ]
    }
  ]
}

Note that it is important to respond to RequestItems and RequestItemGroups in the same order in which they were received.

Receive the Response to the Request

We now assume that the Recipient has accepted the Request for sharing Attributes of the Sender. In order for the Sender to receive the Response of the Recipient, it needs to synchronize the updates of the Backbone. Please note that this synchronization can also be automated by using the Sync Module.

To view the Response to the Request, search for it in the synchronization result or proceed as described in the Query outgoing Requests use case documentation and use the following query parameter:

If the Request was sent via a Template: Specify <ID of RelationshipTemplate> as the value for the source.reference query parameter.
If the Request was sent via a Message: Specify <ID of Request> as the value for the id query parameter.

The Integrator of the Sender can now get the Response of the Recipient from the response.content property of the result. In the items property of the Response is a ShareAttributeAcceptResponseItem for each accepted ShareAttributeRequestItem and a RejectResponseItem for each rejected ShareAttributeRequestItem included. Note that each accepted ShareAttributeRequestItem leads to the creation of an appropriate LocalAttribute with a LocalAttributeShareInfo of the Sender. The content of the LocalAttribute is the underlying attribute of the ShareAttributeRequestItem.

In case of an error, ErrorResponseItems can also be included in the Response. If the Request for sharing Attributes contains a RequestItemGroup in its items property, the Response to this Request contains a corresponding ResponseItemGroup in its items property.

What’s next?

Take a look at our Integration example if you want to see how an Identity shares an Attribute with a peer in the context of a larger process. Also note that it is not only possible to share an Attribute with a peer, but you can also request to read an Attribute from a peer. Consult the Read Attributes from peer guide for this.

Integrate enmeshed

Request for sharing Attributes