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 an OwnIdentityAttribute.

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 an OwnIdentityAttribute

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

{
  "content": {
    "value": {
      // IdentityAttribute value
      ...
    },
    "tags": ["<tag of IdentityAttribute to be created>", ...]
  }
}

You need to replace the placeholders marked with <...> appropriately. Note that the property tags is optional, so you can omit it. It is necessary that you insert one of the available IdentityAttributeValues into the value property. If there is already an existing OwnIdentityAttribute with an undefined succeededBy property and which therefore represents the latest version, whose content.value exactly matches the specified value in the payload for creating a new OwnIdentityAttribute, an error with error code error.runtime.attributes.cannotCreateDuplicateOwnIdentityAttribute is thrown. This is to prevent several latest OwnIdentityAttributes with the same content.value from existing in parallel.

Process of creating an OwnIdentityAttribute

As you can see from the diagram below, after you have entered the input for creating an OwnIdentityAttribute, 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, an OwnIdentityAttribute is created that contains the IdentityAttribute in its content property. Regardless of whether it is a simple IdentityAttribute or a complex IdentityAttribute, a success response is sent directly. Note that the successful creation of a LocalAttribute, and therefore in particular the creation of an OwnIdentityAttribute, 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 an OwnIdentityAttribute 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 an OwnIdentityAttribute.

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 OwnIdentityAttribute 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

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. In terms of nomenclature, this pair of LocalAttributes consists of one OwnRelationshipAttribute and one PeerRelationshipAttribute.

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