Resource: Setting

About this resource

Represents a single setting in ADAM.

Because settings can contain sensitive information, an additional security measure is present in the REST API preventing access to settings unless explicitly allowed by the ADAM administrator. In order to access (read/write) any of the settings in ADAM, the administrator first needs to configure a whitelist of all the settings allowed to be accessed through the REST API. This whitelist is a system setting in ADAM, named '.rest_SettingsWhitelist', in the form of a comma-separated list of allowed setting names, and can be updated through the System Studio. However, the whitelist does not affect users from the ADAM Administrator and Operator user groups: they have access to all their ADAM settings, irrespective of the whitelist.

After the whitelist has been properly configured, consumers can access the settings specified in the whitelist via the REST API.

Properties

Property	Description	Type
name	Gets the name of the setting.	string
value	Gets the value of the setting.	string

Relations

Method	Name	Select-key	Resource type	Description
GET	self			Provides a link to this resource.

Actions

Method

Action

Description

Response codes

PUT /setting/{settingName}

edit

Set the value of an existing setting for the specified scope.

204	Request completed successfully
400	Bad request (in general)
403	Insufficient permissions
404	Setting not found

Examples

Reading a setting

GET /setting/.defaultRecordTitleField HTTP/1.1

If the setting is found, a resource is returned containing the name and the value of the setting.

If the setting was not found, the API call will fail with a 404 Not found HTTP status code.

{
"_links": {
"self": {
"href": "/setting/.defaultRecordTitleField"
}
},
"name": ".defaultRecordTitleField",
"value": "DisplayTitle"
}

Reading a setting from a specific scope

GET /setting/.defaultRecordTitleField?scope=usergroup&scopeId=d4889b57-af11-4da9-aba1-c96d1b6a22ec HTTP/1.1

If the setting is found, within a given scope, a resource is returned containing the name and the value of the setting.

If the setting was not found, the API call will fail with a 404 Not found HTTP status code.

To access a setting through the Rest API, you must have the Role required to change which is defined on the setting definition.

{
"_links": {
"self": {
"href": "/setting/.defaultRecordTitleField?scope=usergroup&scopeId=d4889b57-af11-4da9-aba1-c96d1b6a22ec"
}
},
"name": ".defaultRecordTitleField",
"value": "DisplayTitle"
}

Setting a setting value

PUT /setting/.defaultRecordTitleField
{
"name": ".defaultRecordTitleField",
"value": "DisplayTitle",
"scope": "UserGroup",
"scopeId": "1ED74A99-84CD-4A9C-BFEB-A4D000EC3275"
}

Rules for passing parameters

Name, value and scope properties are required to set the setting.
Name and scope properties are required to read the setting value in specific scope.
Only Name is required to read the scope-independent setting value.
Scope can be system, user, usergroup or site.
When scope is set to user, scopeId is optional. Current user's id is used in this case.
When scope is set to usergroup or site, scopeId is mandatory.