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

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

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

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

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

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

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

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.

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 to a parent object can be accomplished in one of two ways:

• Adding them when adding a parent object.
• Adding them to an existing parent object.

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 on a parent object can be accomplished in one of two ways:

• Updating them when updating a parent object.
• Modifying them on an existing parent object.

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

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