Skip to main content

Custom Fields (User and Group)

Custom Fields are an answer to the requirement of having to store simple application specific pieces of information together with the User object, or a Group object, when there isn’t an existing field which suits that data.

Example problem​

For an example, suppose you need to store the following data about an user:

  • First and last name

  • Date of birth

  • Software license level they have purchased, and the date of license expiration

The name and date of birth are easy, since the User object has fields for those. But the license data is tough. There is no ready made field for that. And even if there was, other applications might already be using it. Or they could modify it.

The solution is using Custom Fields, which allow your application to add arbitrary application specific data to User objects. The fields are meant to hold simple, small JSON based data, not anything very large. A couple of text fields are perfect.

Data model​

Custom Fields are stored inside a JSON object as fields or properties.

The fields have to have a name, which must be unique within the User object. Two fields cannot have the same name, otherwise one’s value will overwrite the earlier one. There are some limitations for the names:

  • Names cannot contain periods (.)

  • Names cannot start with the dollar sign ($)

It is recommended that you use a name prefix which separates your fields from others.

The field value can be any JSON compatible node: text, number, boolean, object, or an array of nodes.

By using object and array values, it is possible to create a deep tree hierarchy of values, but this can introduce problems when it comes time to update the values. Using fields with direct values, or a 1-level object as a value is usually a good choice.

Management API​

The User and Group APIs provide similar endpoints for managing Custom Fields:

  • Get all Custom Fields as a JSON object

  • Replace some Custom Fields

  • Delete all Custom Fields

  • Patch Custom Fields using JSON Patch

You can find details about the required permissions and scopes in the API documentation.

Get all Custom Fields​

This API returns a JSON object which contains all Custom Fields of the target User or Group which you have access to.

Replace some Custom Fields​

This API allows you to add, replace, or delete whole fields.

Delete all Custom Fields​

This API allows you to delete all custom fields. If some fields are write-protected and you don’t have write access, this request will not succeed.

Patch Custom Fields​

This API allows you to modify custom fields using an array of JSON Patch operations. These operations can be useful if you need to modify a sub-field of an object or array value.

Note that move and copy operations are not currently supported in these APIs.

Searching Users using Custom Fields and the Filter parameter​

Data in Custom Fields can be referenced in the filter parameter when you use the Search User or Search Group APIs.

Custom Fields are usually not indexed. Searches from a very large User base using only unindexed fields can be slow and cause service issues for others.

If you experience slowdowns, consider if searching by unindexed fields is necessary, and discuss with the service provider about adding index support.

For example, if some User objects have these Custom Fields:

You can search for Users who have full license level and some tokens by using the filter:

customFields.myappLicense.level eq "full" AND customFields.myappTokensLeft gt 0

Because the myappLicense.expires value is a text value, it cannot be filtered using gt comparison operator. If the expiration date was stored as a number value, for example as the number 20261231 you might then use a filter

customFields.myappLicense.level eq "full"
  AND customFields.myappLicense.expires gt {currentDateAsNumber}
  AND customFields.myappTokensLeft gt 0

Management UI tools​

In the Accounts view, select a row and use the Info / Show custom fields menu to open a read-only view to that User’s custom fields. Again, only accessible fields are displayed.

In the Groups view, edit a Group and go to the “Miscellaneous” tab. The Group editor supports both read and write operations in the editor.

Protecting access to Custom Fields​

In the Management UI, open the Custom fields view. In this view you can manage Namespace-specific definitions of Custom Fields. These are not necessary to create and use Custom Fields, but they can be used to limit access to the fields.

You can also set the data type, which will protect against setting a value of wrong type.

Image

OIDC Claim​

User’s Custom Fields can be read through the OpenID Connect claim system. The Custom Field names need to be pre-registered in the OIDC Client’s configuration. After that, all matching fields are returned in the https://oneportal.trivore.com/claims/custom_fields claim value. See the “Scopes and Claims” tool in the Management UI for details.

Image