One of the great strengths of the Identity Cloud entity types is the fact that entity types (and their underlying schemas) are fully extensible. When you first sign up for the Identity Cloud, you get a default entity type and entity type schema (user) that includes a number of predefined user attributes. As noted in the article Create a schema, however, you aren’t restricted to that default schema: you can create any number of custom schemas that help you fulfill your needs. Furthermore, even the default schema is not etched in stone. For example, suppose you need to track something that isn’t tracked by one of the default attributes (for example, you need to know whether or not a user has subscribed to your monthly newsletter). What do you do in that situation? Probably the best course of action is to add a new attribute (e.g., newsletterSubscriber) to the user entity type schema. Problem solved!

In this articled we’ll explore two different to add an attribute to an entity type schema:

• By importing a JSON file that specifies the properties and property values of the new attribute.

• By using the Console UI to construct the new attribute.

Adding an attribute by using JSON

To create a new attribute by using JSON, from the Manage Schemas page click the Create button and then click Create Attribute:

When the “How do you want to create this attribute?” dialog appears, click Import JSON:

At this point you have three options for importing your JSON:

1. Click Upload a file and then select a file containing the JSON for the attribute (or attributes) being added:

   

2. Drag and drop your JSON file onto the Import dialog box:

   

3. Click Paste in your own JSON and then paste your JSON into the dialog:

   

Pick whichever method works best for you.

Regardless of the method you use, there are a few things to keep in mind when it comes to JSON files. First, the Console checks your syntax to verify that the JSON has been properly formatted. In the following example, we accidentally left the comma off the of the first line of our JSON markup:

When the Console parses the JSON, it notes the error and does two things: 1) displays a red exclamation mark indicating that there’s a problem with the JSON; and, 2) grays-out the Save button. Because the Save button is unavailable, you can’t continue (and can’t create the attribute) until the problem with the JSON has been corrected. If we add a comma to the end of the first line, then we can proceed:

Note, however that – at this point in the process – the Console is only verifying that the JSON has been properly formatted: it doesn’t verify that the JSON properties and property values are correct. For example, here we’re creating a date property, but we’re also setting the length (the number of characters that can be entered in the field) to 100:

That’s a problem: you can’t configure the length of a date attribute. However, because the formatting is correct, no error message appears at this time. Instead, you won’t see an error message until you click Save and try to create the improperly-configured attribute:

Here’s anther thing to keep in mind. As long as you’ve formatted the JSON properly, it looks as though you can enter multiple attributes in a single dialog:

Again, that seems to work just fine (which, again is because the JSON is properly formatted). But here’s what happens when you click Save:

Right now you can only create one attribute at a time.

If you decide to create an attribute by using JSON you can write that JSON from scratch: just open up a text editor and start typing. Alternatively, you might want to use the /config/{app}/{entityTypes}/{type}/attributes/{attribute_name} endpoint to return the properties and property values of a similar attribute. For example, suppose you want to create a new date attribute. Because birthday is a date attribute, you can use a Curl command similar to this to return the property values of the birthday attribute:

curl -X GET  \
  'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/entityTypes/user/attributes/birthday' \
  -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='

That returns a JSON representation of the attribute:

{
    "\_self": "/config/79y4mqf2rt3bxs378kw5479xdu/entityTypes/user/attributes/birthday",
    "name": "birthday",
    "case-sensitive": null,
    "default": null,
    "description": null,
    "ignore-update": false,
    "length": null,
    "locally-unique": false,
    "primary-key": false,
    "type": "date",
    "query": true,
    "reverse-query": false,
    "required": false,
    "unique": false
}

If you copy and paste the API response into the Console’s JSON editor, you can then make any needed changes (for example, in this case we’ve changed the attribute name to dateJoined):

As soon as you have your JSON just the way you want it, click Save. If everything goes according to plan, your new attribute will be added to the schema:

To verify that, click Manage Schemas, click the name of the entity type where the attribute was added, and verify that the attribute really was added:

"Building" an attribute

If the prospect of using JSON to create an attribute leaves you less-than excited, here’s a thought: use the Console UI to “build” an attribute instead. To build an attribute, click the Create button and then click Create Attribute, just like you do to create an attribute by using JSON:

This time, however, click Build rather than Import JSON:

Clicking Build takes you to the Create Attribute page. On that page, enter a unique name for your attribute and, optionally, a description of what that attribute is used for. After that,, click the Data Type dropdown list and select the data type for your attribute:

After you select a data type, the page displays the validations and transformations appropriate for the selected type. For example, if you choose boolean, the Validations and Transformations section looks like this:

And, just for comparison's sake, here’s what you’ll see if you select the string datatype:

After the screen refreshes, select the desired validations and transformations. For the attribute we’re building in this example, we’ve selected the Required validation, meaning that users need to specifically answer true or false before they can submit a form that contains the attribute:

Once that’s done, click the Save New Attribute button to add the new attribute to the entity type:

If everything goes as planned, you’ll see a confirmation message in the lower right-hand corner of your screen:

More importantly, if you return to the schema home page you’ll see your new creation included among your schema attributes: