Integrate enmeshed

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

  • A university wants to send a graduate their degree certificate.
  • A company wants to provide an employee with their business email address at the start of their employment.

We will now explain how a Connector, hereinafter referred to as the Sender, can create an Attribute for another Connector, the so-called Recipient. Since understanding this creation 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 create an Attribute for an App user instead of another Connector. For reasons of clarity, this guide focuses on the creation process with two Connectors.

The Sender has several options for requesting an Attribute creation. This guide covers how it can request the creation of an Attribute for the Recipient so that the Attribute value is only set by the Sender itself and cannot be modified by the Recipient when accepting the Request.

If the Recipient should be able to adjust the Attribute offered for creation, the Propose Attributes to peer guide must be consulted instead. Also, it is possible for the Sender to ask the Recipient for an Attribute of a specific Attribute value type without offering an Attribute by following the Read Attributes from peer guide. If the Recipient complies with this Request by using the newAttribute parameter of the AcceptReadAttributeRequestItemParameters, this leads to the creation of an Attribute for the Recipient whose Attribute value was chosen completely freely by it.

Request for creating Attributes

The Sender wants to create an Attribute for 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 creating Attributes.

Role of CreateAttributeRequestItem

For requesting the creation of a single Attribute for the Recipient, a single RequestItem of type CreateAttributeRequestItem must be inserted into the items property of the Request. It is possible to request the creation of an IdentityAttribute or a RelationshipAttribute, which must be inserted into the attribute property of the CreateAttributeRequestItem. Depending on whether an IdentityAttribute or a RelationshipAttribute is to be created for the Recipient, the Sender has a different number of input options when defining the prospective owner of the Attribute. In the case of IdentityAttributes, the Recipient must be the prospective owner. In contrast, the Sender is also permitted as the owner of RelationshipAttributes. More details on the various input options when creating a Request for creating Attributes and the corresponding application scenarios can be found in the table of the Combinations and usage scenarios of the CreateAttributeRequestItem.

Combinations and usage scenarios of CreateAttributeRequestItem

The following table provides an overview of the possible kinds of Attributes that the Sender can create for the Recipient using the CreateAttributeRequestItem. It must be taken into account whether the Attribute is an IdentityAttribute or a RelationshipAttribute and which Identity is its owner. Note that you can only explicitly specify the Recipient as the owner of the Attribute for Requests that are sent via a Message. This is because when a Request is sent via a Message, the Identity that receives the Request is always known in advance. For Requests that are sent via a RelationshipTemplate, an empty string must be specified as the owner instead, as you do not know the Identity that will load your RelationshipTemplate beforehand. Specifying an empty string for the owner of the Attribute is equivalent to requesting the creation of an Attribute with the Recipient as its owner. Requesting the creation of a RelationshipAttribute using a CreateAttributeRequestItem is only possible if it should exist in the context of the Relationship between the Sender and the Recipient.

Type and context Owner Possible? Automation Remarks, reasons and examples
IdentityAttribute Sender ✗ N/A Use the ShareAttributeRequestItem instead. For more details, refer to the documentation of the Share Attributes with peer scenario.
IdentityAttribute Recipient ✓ USER_DECISION Example: A university sends a student their certificate.
RelationshipAttribute that exists in the context of the Relationship between the Sender and the Recipient Sender ✓ AUTO_ACCEPT Example: A company sends a new customer their customer number.
RelationshipAttribute that exists in the context of the Relationship between the Sender and the Recipient Recipient ✓ USER_DECISION With this combination, the Sender asks the Recipient for the one-time permission to create a RelationshipAttribute that is owned by the Recipient, with the Sender defining its value. The Recipient can either accept and save this value or reject it. Thus, the Recipient cannot change the value itself.

Example of creating an IdentityAttribute

We assume that the Integrator of the Sender wants to create an IdentityAttribute of type EMailAddress for the Recipient. To request the creation of this IdentityAttribute, the Sender needs to insert it into the attribute property of the CreateAttributeRequestItem contained within the items property of the Request for creating Attributes. As the IdentityAttribute should be owned by the Recipient, an empty string is specified for its owner property. If the Sender sends the corresponding Request via a Message, the Address of the Recipient could alternatively be specified explicitly. In our example, we have chosen to set the value of the mustBeAccepted property of the CreateAttributeRequestItem to true. Please note that the <...> notation is used as a placeholder for the actual data as usual.

{
  "@type": "Request",
  "items": [
    {
      "@type": "CreateAttributeRequestItem",
      "mustBeAccepted": true,
      "attribute": {
        "@type": "IdentityAttribute",
        "owner": "",
        "value": {
          "@type": "EMailAddress",
          "value": "<email address that the Sender wants to create for the Recipient>"
        }
      }
    }
  ]
}

Example of creating a RelationshipAttribute

We now consider the case in which the Sender has an active Relationship with the Recipient and wants to create a RelationshipAttribute of type ProprietaryString for this Relationship that is owned by itself. The Sender can request the creation of this RelationshipAttribute by inserting it into the attribute property of the CreateAttributeRequestItem included in the items property of the Request for creating Attributes. In our example, we have chosen to set the value of the mustBeAccepted property of the CreateAttributeRequestItem to true and the value of the confidentiality property of the RelationshipAttribute to "public".

{
  "@type": "Request",
  "items": [
    {
      "@type": "CreateAttributeRequestItem",
      "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>"
        }
      }
    }
  ]
}

It would also be possible to specify an empty string as the value for the owner property if the RelationshipAttribute should be owned by the Recipient instead of the Sender.

Create multiple Attributes

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

Send and receive the Request

The Sender that wants to create an Attribute for 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 creating Attributes. There are two ways to send the Request for creating 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 create the Attributes

After the Recipient has received the Request for creating Attributes, it can accept it to create all or some of the Attributes that were offered for creation by the Sender. 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 CreateAttributeRequestItem contained in the Request for creating Attributes whether you want to accept or reject it.

If the Recipient does not want to create any of the Attributes offered by the Sender and, therefore, does not want to accept the Request for creating Attributes of the Sender, it can reject it as a whole as well. For that, follow the instructions of the Reject incoming Request use case.

Accept a CreateAttributeRequestItem

If the Recipient agrees to the creation of one of the Attributes offered by the Sender, it can accept the associated CreateAttributeRequestItem contained in the Request for creating Attributes. The AcceptRequestItemParameters must be used for that. The acceptance of a CreateAttributeRequestItem 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 CreateAttributeRequestItem. Based on this, an appropriate AcceptResponseItem of type CreateAttributeAcceptResponseItem is generated, which incorporates the id of the LocalAttribute with the LocalAttributeShareInfo in its attributeId property. This will be contained within the items property of the Response to the Request for creating Attributes that will be transferred to the Sender. If the underlying attribute of the accepted CreateAttributeRequestItem is an IdentityAttribute, a corresponding LocalAttribute without a LocalAttributeShareInfo is additionally created for the Recipient beforehand.

Reject a CreateAttributeRequestItem

Even if the Recipient accepts the Request for creating Attributes as a whole, it may decide not to accept all of the Attributes offered by the Sender. To be more precise, the Recipient has the option of rejecting CreateAttributeRequestItems that have the value false specified in their mustBeAccepted property. To reject a CreateAttributeRequestItem, use the RejectRequestItemParameters. The rejection of a CreateAttributeRequestItem 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 creating Attributes.

Example of accepting a RequestItemGroup

Let’s look at an example where the Sender wants to create an EMailAddress, a BirthDate and a BirthPlace for the Recipient. For this purpose, the Sender creates a Request for creating Attributes, which contains a CreateAttributeRequestItem belonging to the EMailAddress and a RequestItemGroup belonging to the birth information in its items property. The RequestItemGroup itself includes two CreateAttributeRequestItems in its items property, namely one for the BirthDate and one for the BirthPlace.

{
  "@type": "Request",
  "items": [
    {
      "@type": "CreateAttributeRequestItem",
      "mustBeAccepted": true,
      "attribute": {
        "@type": "IdentityAttribute",
        "owner": "",
        "value": {
          "@type": "EMailAddress",
          "value": "<email address that the Sender wants to create for the Recipient>"
        }
      }
    },
    {
      "@type": "RequestItemGroup",
      "items": [
        {
          "@type": "CreateAttributeRequestItem",
          "mustBeAccepted": true,
          "attribute": {
            "@type": "IdentityAttribute",
            "owner": "",
            "value": {
              "@type": "BirthDate",
              "day": <day of birth date that the Sender wants to create for the Recipient>,
              "month": <month of birth date that the Sender wants to create for the Recipient>,
              "year": <year of birth date that the Sender wants to create for the Recipient>
            }
          }
        },
        {
          "@type": "CreateAttributeRequestItem",
          "mustBeAccepted": false,
          "attribute": {
            "@type": "IdentityAttribute",
            "owner": "",
            "value": {
              "@type": "BirthPlace",
              "city": "<city of birth place that the Sender wants to create for the Recipient>",
              "country": "<country of birth place that the Sender wants to create for the Recipient>"
            }
          }
        }
      ]
    }
  ]
}

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

If the Recipient wants to accept the Request for creating Attributes, it must accept all CreateAttributeRequestItems for which the mustBeAccepted property is set to true. It is therefore not permitted for the Recipient to refuse to accept the EMailAddress or the BirthDate offered by the Sender.

The Recipient accepts the EMailAddress of the Sender and accepts at least one CreateAttributeRequestItem of the RequestItemGroup. Also, the Recipient accepts the BirthDate and rejects the BirthPlace of the Sender. It therefore responds to the Request for creating Attributes as follows:

{
  "items": [
    {
      // Accept EMailAddress
      "accept": true
    },
    {
      "items": [
        {
          // Accept BirthDate
          "accept": true
        },
        {
          // Reject BirthPlace
          "accept": false
        }
      ]
    }
  ]
}

Note that it is important to respond to RequestItems, some of which may be contained in a RequestItemGroup, 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 creating 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:

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 CreateAttributeAcceptResponseItem for each accepted CreateAttributeRequestItem and a RejectResponseItem for each rejected CreateAttributeRequestItem included. Note that each accepted CreateAttributeRequestItem 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 CreateAttributeRequestItem.

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

What’s next?

As already mentioned, this guide covers how an Identity can request the creation of an Attribute for a peer so that the Attribute value is only set by the Identity itself and cannot be modified by the peer when accepting the Request. For a typical example of an application of this procedure, refer to the documentation of the Request persistent consent of peer scenario. In many cases, however, it makes more sense if the peer can adjust the Attribute that was offered for creation. For that, take a look at the Propose Attributes to peer guide.