Skip to main content

Custom Settings

The custom settings API allows you to store arbitrary setting values for a particular user. The intended use case for this API is integration tasks.

note

Custom settings do not overlap with iCL settings. They are stored separately. Therefore, you cannot modify existing user settings using the custom settings API.

Usecase: Integration tasks​

In an integration scenario, you might want to store some information for your service user that can be picked up the every time the integration process runs.

For example, you may want to synchronize order in your legacy system with iCL Portal, where you store orders as order content type. In this scenario, you store the latest order number that was processed by your integration. That way, every time the integration process runs, it can pick up where it left off and does not have to re-process all orders in the system over and over again. The following diagram illustrates this scenario:

  1. You query the settings api to check if there is any last_processed_ordernumber setting available.
  2. Then, use the last_processed_ordernumber to fetch any new order from your legacy system, thereby also getting the new value for last_processed_ordernumber...
  3. ...and import the orders into iCL Portal.
  4. Finally, save the new last_processed_ordernumber
service account authentication

To authenticate your service account, use the OAuth 2.0 client credentials flow as described here

1. Creating/Updating a custom setting​

To create or update a custom setting, use the following endpoint:


POST https://dev.iclportal.com/api/settings/customusersetting HTTP/1.1
Authorization: Bearer ..the auth_token...

{
  "name": "last_processed_ordernumber",
  "value": { 
     "ordernumber":122
   }
}

2. Retrieving a custom setting​

To retrieve a custom setting, use the following endpoint:

GET https://dev.iclportal.com/api/settings/customusersetting/last_processed_ordernumber HTTP/1.1
Authorization: Bearer ..the auth_token...

returns 

{
  "value": {
    "ordernumber": 122
  }
}

In case no setting exists, the API will return null as value:

GET https://dev.iclportal.com/api/settings/customusersetting/this_does_not_exist HTTP/1.1
Authorization: Bearer ..the auth_token...

returns 

{
  "value": null
}