Create Attributes for yourself

This guide explains the end-to-end flow of creating an Attribute for your own Connector as its Integrator. As there are two types of Attributes, IdentityAttributes and RelationshipAttributes, a distinction must be made between them when creating an Attribute for yourself.

Create an IdentityAttribute for yourself

This section is about how to create an IdentityAttribute for your own Connector that is not initially shared with any other Identity. From a technical point of view, this corresponds to the creation of a LocalAttribute whose content is given by the IdentityAttribute that is intended to be created and whose shareInfo is undefined. Such a LocalAttribute is referred to as a RepositoryAttribute.

Since knowledge about IdentityAttributes is required in the following, you should take a look at our IdentityAttribute introduction before you continue reading this guide. In particular, a description of the two kinds of IdentityAttributes, the simple IdentityAttributes and the complex IdentityAttributes, can be found there.

Input for creating a RepositoryAttribute

To create a RepositoryAttribute, proceed as described in the Create a RepositoryAttribute use case documentation. As input for the creation of a RepositoryAttribute, the following content must be used:

{
  "content": {
    "validFrom": "<start of IdentityAttribute's validity>",
    "validTo": "<end of IdentityAttribute's validity>",
    "value": {
      // IdentityAttributeValue
      ...
    },
    "tags": ["<additional information 1>", ..., "<additional information n>"]
  }
}

You need to replace the placeholders marked with <...> appropriately. Also, it is necessary that you insert one of the available IdentityAttributeValues into the value property. Note that the properties validFrom, validTo and tags are optional, so you can omit them.

Process of creating a RepositoryAttribute

As you can see from the diagram below, after you have entered the input for creating a RepositoryAttribute, a check is performed whether the input values for the properties of the specified IdentityAttributeValue meet the validation criteria documented on the Attribute Values page. If the validation is not successful, an error message is sent in response. Otherwise, a RepositoryAttribute is created that contains the IdentityAttribute in its content property. If it is a simple IdentityAttribute, a success response is sent directly. In the case of a complex IdentityAttribute, on the other hand, another RepositoryAttribute is created beforehand for each of its appropriate properties. These RepositoryAttributes for the properties are also referred to as children of the RepositoryAttribute belonging to the complex IdentityAttribute. The id of their parent is contained within their parentId property. Note that the successful creation of a LocalAttribute, and therefore in particular the creation of a RepositoryAttribute, triggers the consumption.attributeCreated Connector event.

Example of creating a simple IdentityAttribute

An example of a simple IdentityAttribute is one of type DisplayName. To create one for your own Connector without specifying optional parameters, the following content must be used:

{
  "content": {
    "value": {
      "@type": "DisplayName",
      "value": "<display name of your own Connector>"
    }
  }
}

Assuming that the input value for the Connector’s display name specified in the value.value property meets the validation criterion, which means that the entered name does not have more than 100 characters, the IdentityAttribute is saved as a RepositoryAttribute and a success response is sent.

Example of creating a complex IdentityAttribute

An example of a complex IdentityAttribute is one of type BirthDate. To create one for your own Connector without specifying optional parameters, the following content must be used:

{
  "content": {
    "value": {
      "@type": "BirthDate",
      "day": <day of birth date>,
      "month": <month of birth date>,
      "year": <year of birth date>
    }
  }
}

Assuming that the input values for the properties value.day, value.month and value.year meet the validation criteria, which means, for example, that the input value for value.month is an integer between 1 and 12, the IdentityAttribute is saved as a RepositoryAttribute. The properties value.day, value.month and value.year can each be understood as an additional simple IdentityAttribute of type BirthDay, BirthMonth and BirthYear, respectively. For this reason, another RepositoryAttribute is created internally for each of these properties before a success response is sent. So for the RepositoryAttribute, which belongs to the complex IdentityAttribute of type BirthDate, a total of three children are created.

What’s next?

When you have successfully created an IdentityAttribute for your own Connector, you will receive a success response. From the result, you can get the id of the corresponding RepositoryAttribute belonging to the IdentityAttribute. You will need this id, for example, if you want to share the underlying IdentityAttribute with other Identities later, as in the Share Attributes with peer scenario.

Create a RelationshipAttribute for yourself

If you want to create a RelationshipAttribute, you must proceed differently than when creating an IdentityAttribute for yourself. This is because a RelationshipAttribute can only exist in the context of a Relationship with a peer, which means that they must also agree to the creation of it. This is achieved by sending a Request whose items property contains an appropriate RequestItem, which must be accepted by the peer. Depending on whether you or your peer should set the RelationshipAttributeValue and depending on other factors, a CreateAttributeRequestItem, ReadAttributeRequestItem, ProposeAttributeRequestItem or ShareAttributeRequestItem should be used for this.

From a technical point of view, the creation of a RelationshipAttribute corresponds to the creation of one LocalAttribute for yourself and one LocalAttribute for your peer, whereby their content is given by the RelationshipAttribute that is intended to be created and the shareInfo of both LocalAttributes contains a correspondingly suitable LocalAttributeShareInfo.

Utilization of a CreateAttributeRequestItem

You can use a CreateAttributeRequestItem to create a RelationshipAttribute in the context of a Relationship between you and your peer if you want the RelationshipAttributeValue to be set by yourself. Your peer can only accept or reject the creation of the RelationshipAttribute, but cannot modify the RelationshipAttributeValue. A RelationshipAttribute that you want to create using a CreateAttributeRequestItem can be owned by yourself or by your peer. For full details on how to create a RelationshipAttribute using a CreateAttributeRequestItem, please refer to the Create Attributes for peer guide.

Utilization of a ReadAttributeRequestItem

You can use a ReadAttributeRequestItem to create a RelationshipAttribute in the context of a Relationship between you and your peer if you want the RelationshipAttributeValue to be set by your peer. Even if it seems misleading to use a ReadAttributeRequestItem to create a RelationshipAttribute, this terminology makes sense insofar as the RelationshipAttributeValue should be read from the peer in order to be able to create the RelationshipAttribute. A RelationshipAttribute that you want to create using a ReadAttributeRequestItem can be owned by yourself, your peer or even a third party. For full details on how to create a RelationshipAttribute using a ReadAttributeRequestItem, please refer to the Read Attributes from peer guide.

Utilization of a ProposeAttributeRequestItem

You can use a ProposeAttributeRequestItem to create a RelationshipAttribute in the context of a Relationship between you and your peer if you want to propose a potentially suitable RelationshipAttributeValue to your peer, but your peer has the option to modify it before the RelationshipAttribute is created. A RelationshipAttribute that you want to create using a ProposeAttributeRequestItem must be owned by your peer. All details on how to create a RelationshipAttribute using a ProposeAttributeRequestItem can be found in the Propose Attributes to peer guide.

Utilization of a ShareAttributeRequestItem

You can use a ShareAttributeRequestItem to create a RelationshipAttribute in the context of a Relationship between you and your peer if you want to use an existing RelationshipAttribute between you and a third party as the source for creating the new RelationshipAttribute. Your peer can only accept or reject the creation of it, but cannot modify it. A RelationshipAttribute that you want to create using a ShareAttributeRequestItem can be owned by yourself or the third party, but not by your peer. All details on how to create a RelationshipAttribute using a ShareAttributeRequestItem can be found in the Share Attributes with peer guide.

Integrate enmeshed