Directories

The Directories service provides the ability to perform various directory-related operations:

  • The /icws/{sessionId}/messaging/subscriptions/directories resource provides the ability to create and update a subscription to the metadata of all directories accessible to the logged in user. Directory metadata represents the information about the directories in the IC System and can be used to identify a directory of contact entries for use in directory subscriptions.
  • The /icws/{sessionId}/messaging/subscriptions/directories/{subscriptionId} resource provides the ability to create and update subscriptions to directories that are accessible to the logged in user. Directories are identified via the directoryID property from an associated directory metadata subscription response. Directory subscriptions provide a way to retrieve contact entries that are associated with the specified directory, as well as the ability to watch for contact additions, changes, and removals for the directory.
  • The /icws/{sessionId}/directories/lookup-entries resource provides the ability to retrieve lookup entries that match supplied query parameters. Lookup entries provides access to retrieve users, standalone phone, station, station group, attendant profile, and workgroup objects based on provided search criteria. For example, it can be used to retrieve all users that have a last name that exactly matches "Doe", such as "John Doe". Only objects that the logged in user has search access to can be retrieved.

Note

See Event Subscriptions and Messaging for information on how to work with subscriptions.

See Session Requests for information on the parameters necessary to perform Session Requests.

Jump to a section that describes each area of the directories API:

Directory Metadata

Managing directory metadata subscriptions

The directory metadata subscription provides the ability to retrieve information about the directories in the IC System that the logged in user has access to. The URI pattern to start a directory metadata subscription is:

PUT /icws/{sessionId}/messaging/subscriptions/directories

There are no other parameters needed for this request. A 204 HTTP status code with an empty response body will be returned if the directory metadata subscription was successfully started.

After starting a directory metadata subscription, the ICWS-based application must watch for the urn:inin.com:directories:directoriesMessage message type in order to retrieve the associated directory metadata changes. This message type will contain information for the directory metadata such as directoriesAdded, directoriesChanged, and directoriesRemoved.

To remove a directory subscription, use the following URI pattern:

DELETE /icws/{sessionId}/messaging/subscriptions/directories

There are no other parameters needed for this request. A 204 HTTP status code with an empty response body will be returned if the directory metadata subscription was successfully removed.

Back to top

Directories

Managing directory subscriptions

Directory subscriptions provide the ability to retrieve information about the objects that are contained within specified IC System directories. The URI pattern to start a directory subscription is:

PUT /icws/{sessionId}/messaging/subscriptions/directories/{subscriptionId}

Note

The {subscriptionId} can be assigned arbitrarily and should be managed by the ICWS-based application

There are a few request parameters that can be used when starting a directory subscription to tailor the results to what is needed, including count, filterItems, index, sortItems, and directoryId. The only required parameter of these is directoryId, which can be obtained from the directoryId property from the urn:inin.com:directories:directoriesMessage message type's representation that comes from a directory metadata subscription. For example, to get the first 100 contacts for a directory with the ID of "companyDirectory", the ICWS-based application would need to send the following request:

PUT /icws/{sessionId}/messaging/subscriptions/directories/{subscriptionId}
{
    "__type" : "urn:inin.com:directories:directorySubscriptionParameters",
    "count" : 100,
    "directoryId" : "companyDirectory"
}

In order to return the first 100 directory contacts from the "companyDirectory" that are in the "Development" or "Support" departments, sorted ascending by lastName, the ICWS-based application would need to send the following request:

PUT /icws/{sessionId}/messaging/subscriptions/directories/{subscriptionId}
{
	"__type" : "urn:inin.com:directories:directorySubscriptionParameters",
	"count" : 100,
	"directoryId" : "companyDirectory",
	"filterItems" : [{
			"contactProperty" : 5,
			"filterType" : 0,
			"filterExpressions" : ["Development", "Support"]
		}
	],
	"sortItems" : [{
			"contactProperty" : 2,
			"sortDirection" : 0
		}
	]
}

A 204 HTTP status code with an empty response body will be returned if the directory subscription was successfully started.

After starting a directory subscription, the ICWS-based application must watch for the urn:inin.com:directories:directoryMessage message type in order to retrieve the associated directory changes. This message type will contain information for the directory such as contactsAdded, contactsChanged, and contactsRemoved.

To remove a directory subscription, use the following URI pattern:

DELETE /icws/{sessionId}/messaging/subscriptions/directories/{subscriptionId}

In the previous snippet, {subscriptionId} will be the same subscriptionId that the ICWS-based application assigned in the PUT request.

A 204 HTTP status code with an empty response body will be returned if the directory subscription was successfully removed.

Back to top

Lookup Entries

Working with lookup entries

Lookup entries provide the ability to search IC System directories for objects based on supplied query parameters. The URI pattern to perform a lookup entry search is:

POST /icws/{sessionId}/directories/lookup-entries

Note

The logged in user must have the appropriate search rights configured in Interaction Administrator for results to be included. These search rights can be found in the Access Control container under the Search column.

Additionally, when specifying AttendantProfile (lookupEntryType value 5), attendant profiles can only be included in the lookup results if the logged in user has the sufficient search rights assigned. From within Interaction Administrator, the logged in user must have the search rights for the appropriate Email/Inbound/Operator/Outbound profiles set in the Access Control container. Additionally, the attendant profile must also be setup to be a transfer target from within Interaction Attendant.

There are a few request parameters that must be used when requesting lookup entries including lookupEntryTypes, lookupEntryProperties, lookupComparisonType, lookupString, and maxEntries. All of these parameters are required. The following requests the first 100 Users or Workgroups with an extension, businessPhone1, or businessPhone2 that contains "5555":

POST /icws/{sessionId}/directories/lookup-entries
{
    "lookupEntryTypes" : [1, 6],
    "lookupEntryProperties" : [6, 11, 12],
    "lookupComparisonType" : 3,
    "lookupString" : "5555",
    "maxEntries" : 100
}

A 200 HTTP status code will be returned with the lookup entry results in the message body if the lookup entry request was successful. The lookup entry results will have lookupEntriesList, moreEntriesMatched, and phoneNumber properties that represent the search results.

Back to top