The configuration namespace provides the API that allows one to access IC server configuration data. There are many different configuration object types like Users, Roles and Workgroups. The API to access and make modifications to configuration data is the same across all object types.
Configuration objects typically fall under three types:
Most configuration objects have a ConfigurationId consisting of three properties:
theUser
would look like /configuration/users/theUser
.Each object type that has one or more sub-object types associated with it also has a property on it for each of the sub-object types. For example, the Keyword Set object type has a Keywords property on it.
Jump to a section that describes each area of the configuration API:
The API to get a singleton configuration object follows this pattern:
GET /icws/{sessionID}/configuration/{objectType}
Note: this API is only for singleton configuration objects. In the example above, {objectType}
should be replaced with the object type that you want to fetch. Below is an example of this API:
Get the system configuration singleton object:
GET /icws/{sessionID}/configuration/system
Get the system configuration singleton object's default language:
GET /icws/{sessionID}/configuration/system?select=defaultLanguage&rightsFilter=view
The API to update a singleton configuration object follows this pattern:
PUT /icws/{sessionID}/configuration/{objectType}
Note: this API is only for singleton configuration objects. In the example above, {objectType}
should be replaced with the object type that you want to update. Below is an example of this API:
Update the system configuration singleton object:
PUT /icws/{sessionID}/configuration/system { "defaultLanguage": "en-US" }
The API to search for a list of configuration objects follows this pattern:
GET /icws/{sessionID}/configuration/{objectType}
Note: this API is only for list-based configuration objects. In the example above, {objectType}
should be replaced with the object type that you want to search. The example above will return a list of ID and Display Name pairs for all of the objects that the user has Administrative access to. There are many query string parameters for this API to return additional data or a different set of objects that are filtered by a different security right. Refer to the specific configuration object API for a description of these options. Below are a few more examples of this API:
Get a list of Users that the logged on user has view rights to. The result of this search will include the extension
property with the objects, and the results will also be sorted by the extension
property.
GET /icws/{sessionID}/configuration/users?select=extension&rightsFilter=view&orderBy=extension
Get a list of skills where the display name starts with 'Skill'
GET /icws/{sessionID}/configuration/skills?where=configurationID.displayName sw skill
The API to add new configuration objects follows this pattern:
POST /icws/{sessionID}/configuration/{objectType}
Note: this API is only for list-based configuration objects. In the example above, {objectType}
should be replaced with the object type that you want to add.
The body of the request should contain the JSON representation of the object that is to be added. It is expected that the body of the request is created with the defaults API for the object type if it has one to ensure the object is created correctly. Additionally, the configurationId of the newly created object must be set. Without it, the server will return an error.
Any validation errors that occurred when saving the object will be returned in the response. Below is an example of this API:
Add a new User with an ID of theUser
:
POST /icws/{sessionID}/configuration/users { "configurationId": { "id": "theUser", "displayName": "The User" } }
Note: In some cases it is possible that the ID returned in the response will not match the ID sent in the request. If this occurs, the ID returned in the response should be considered as the correct ID for that configuration object.
The API to get a specific configuration object follows this pattern:
GET /icws/{sessionID}/configuration/{objectType}/{ID}
Note: this API is only for list-based configuration objects. In the example above, {objectType}
should be replaced with the object type that you want to search, and {ID}
should be replaced with the ID of the object to fetch. This API has some of the same query string parameters as the search for objects API. Below is an example of this API:
Get a user with an ID of theUser
and include its extension and notes properties
GET /icws/{sessionID}/configuration/users/theUser?select=extension,notes
The API to delete a specific configuration object follows this pattern:
DELETE /icws/{sessionID}/configuration/{objectType}/{ID}
Note: this API is only for list-based configuration objects. In the example above, {objectType}
should be replaced with the object type that you want to search, and {ID}
should be replaced with the ID of the object to delete. Below is an example of this API:
Delete a user with an ID of theUser
:
DELETE /icws/{sessionID}/configuration/users/theUser
The API to update a specific configuration object follows this pattern:
PUT /icws/{sessionID}/configuration/{objectType}/{ID}
Note: this API is only for list-based configuration objects. In the example above, {objectType}
should be replaced with the object type that you want to update, and {ID}
should be replaced with the ID of the object to update. The request body should contain the JSON representation of the object that you want to update. Below is an example of this API:
Update a user with an ID of theUser
:
PUT /icws/{sessionID}/configuration/users/theUser { "personalInformationProperties": { "phoneNumberOfHome1" : NewHomePhoneNumber1, "phoneNumberOfHome2" : NewHomePhoneNumber2, } }
When retrieving configuration objects, there are 4 types of configuration values that can be obtained. If no other type is specified in the configuration query, only the "effective values" will be returned. The other 3 configuration value types that can be returned are "actual values", "inherited values", and "inherited from values". These can be returned by specifying either the actualValues
, inheritedValues
or singlePropertyInheritedFrom
flag in the configuration query.
"Actual values" can be returned by setting the actualValues
parameter in the configuration query to true
and can be accessed from the actualValue
part of the configuration property. "Actual values" are the value that is explicitly set on the object and does not take into account any "inherited values". This value is most often used by administrative type applications, and it is the only configuration value type that is supported when doing a PUT
or POST
operation.
"Effective values" are returned by default and can be accessed from the effectiveValue
part of the configuration property. "Effective values" are the final calculated value for a configuration property, taking into account the "actual value" and all of the "inherited values" that could affect it (such as a Role
or Workgroup
). As such, the "effective value" is generally the value that most applications would be interested in retrieving. For instance, if user "John Doe" is a member of the "Support" workgroup, then any of the access rights that are assigned to the Support workgroup would be inherited by John Doe and taken into account when calculating John Doe's access rights. If a particular access right is not set on John Doe's user explicitly (via the "actual value"), but it is set on the Support workgroup, then the effectiveValue
for the access right would be equal to the access right from the workgroup (assuming that no other inherited objects are affecting the value).
"Inherited values" can be returned by setting the inheritedValues
parameter in the configuration query to true
and can be accessed from the inheritedValue
part of the configuration property. The "inherited value" is simply the "effective value" without taking into account the "actual value".
"Inherited from values" can be returned by setting the singlePropertyInheritedFrom
parameter in the configuration query to true
and can be accessed from the inheritedFromValue
part of the configuration property. This value can only be returned when querying for a single property for a specific object. The "inherited from value" contains the list of objects that the "inherited values" came from.
The API to get the default values for a configuration object follows this pattern:
GET /icws/{sessionID}/configuration/defaults/{objectType}
In the example above, {objectType}
should be replaced with the object type that you want to get the defaults of. Only the object types that have properties with a default value will have this API. The response body will contain the JSON representation of the object with default values for all of the properties. Below is an example of this API:
Get the default values for a user:
GET /icws/{sessionID}/configuration/defaults/user
To get the information about an object type's sub-objects, a Get Object List or Get Object request for the object type can be made with the properties that represent the sub-object type(s) in the URL query string. This returns all information about the sub-object instances for the specified parent objects. In other words, there is no way to control what sub-object(s) are returned.
Adding one or more sub-objects to a parent object can be accomplished in one of two ways:
For both of these methods, the request body should contain the JSON representation of the sub-object(s) that you want to add.
The API for the second approach is detailed in the bulk update section.
Updating one or more sub-objects on a parent object can be accomplished in one of two ways:
For both of these methods, the request body should contain the JSON representation of the sub-object(s) that you want to add.
The API for the second approach is detailed in the bulk update section.
The API for adding, creating, and or deleting one or more sub-objects on a parent object follows this pattern:
POST /icws/{sessionID}/configuration/{object-type}/{id}/{sub-object-type}
Note: this API is only for sub-object-based configuration objects. In the example above, {objectType}
should be replaced with the parent object type that you want to update, {ID}
should be replaced with the ID of the parent object to update, and {sub-object-type}
should be replaced with the sub-object type.
This example will demonstrate how to subscribe to workgroup configurations to receive updates when specific properties change.
PUT /icws/{essionID}/configuration/workgroups/ { "configurationIds": [ "*" ], "properties": [ "hasQueue", "isActive", "isWrapUpActive", "isCallbackEnabled", "isAcdEmailRoutingActive" ], "rightsFilter": "view" }
In the example above, the '*' will retrieve all workgroups that the user has view rights to. If any changes to the properties listed are made, a message will be sent with the updated values.