Configuration

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:

  • Singleton - There is only a single instance of this configuration object. An example of this is the System configuration object.
  • List - There are many instances of this configuration object. There is a search API for querying the list of items.
  • Sub-object - This is an object that is a child of a configuration object. An example of this is a Keyword configuration object is a sub-object to the Keyword Set configuration object.

Most configuration objects have a ConfigurationId consisting of three properties:

  • ID - The system identifier.
  • DisplayName - A user-friendly identifier for display purposes.
  • URI - Used to access the configuration object that the ConfigurationId refers to. For example, the User object has a 'workgroups' property which is a list of ConfigurationIds. The URIs in those ConfigurationIds can be used to directly access those workgroup configuration objects. The URI for a user object with an ID of 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:

Singleton objects

Getting a singleton configuration object

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

Back to top

Updating a singleton configuration object

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" 
}

Back to top

List-based objects

Searching for configuration objects

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

Back to top

Adding a new configuration object

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.

Back to top

Getting a specific list-based 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

Back to top

Deleting a list-based configuration object

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

Back to top

Updating a list-based configuration object

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,
    }
}

Back to top

About configuration properties

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

"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

"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

"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

"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.

Getting a configuration object's defaults

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

Back to top

Sub-objects

Getting information about an object-type's sub-objects

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.

Back to top

Adding one or more sub-objects

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.

Back to top

Updating one or more sub-objects

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.

Back to top

Adding, creating, and or deleting one or more sub-objects

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.

Back to top

Subscribing to workgroup configurations

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.

Back to top