Service API

The Service API provides Engage and Insight customers with a set of services based on major functional areas such as security and contact center management. The API includes:

• Fully supported API to access cloud platform
• Broad coverage of features accessible from platform
• Language neutral for external access - must support C#, C++, Java, VB.NET
• Full multi-channel support

Business objects represent manageable entities in the system. These objects are designed to be outward facing and easily understood by people with a contact center management domain background. Objects are attribute-based and attributes optionality depends on the usage context.

Definitions

• Query by Example – See http://en.wikipedia.org/wiki/Query_by_Example
• E.123 – See http://en.wikipedia.org/wiki/E.123

Integration Requirements

Requirements for .NET clients to support WS-Security 1.0 and 1.1:

• Either
  • .NET Framework 3.5
  • Web Services Enhancements (WSE) 3.0 for Microsoft .NET
• Or
  • .NET Framework 4.0 with Windows Communication Foundation

Requirements for Java clients to support WS-Security 1.0:

• WS-Security compatible Web Service client framework version 2.2.X

or

• JBossWS-NativeUserGuide

API Design

• Consistent use of the following verbs as prefixes:
  • create – create an instance of an object, typically of the form ‘create<Type>’. Response is typically the object created (exception is for asynchronous operations). In general form should be ‘create<Type>(object, context)’. For some operations a plural form is supported with a signature of ‘create<Type>s(object, context)’, this enables the bulk creation of objects of this Type.
  • delete – remove an instance of an object, typically of the form ‘delete<Type>’. Typically no response is returned. Form is ‘delete<Type>(object). For some operations a plural form is supported with a signature of ‘delete<Type>s(object, context)’, this enables the bulk deletion of objects of this Type.
  • show – return an instance of an object, typically of the form ‘show<Type>’. Response is typically the object located. Form is ‘show<Type>(object). Type can either be an entity or a state and object is typically an entity. For the associated attributes of the object only those attributes that have a current meaningful value will be returned.
  • list – enumerate a set of objects, typically of the form ‘list<Type>s’. Response is typically an array of <object> where the objects are populated. In general, form should be list<Type>(context [, narrowing criteria]). If result set is empty then an empty array is returned with no error.
  • change – update fields/attributes of an object, typically of the form ‘change<Type>’. Response is commonly the updated object unless this would impact performance unduly. Form is ‘change<Type>(object). Only the key attribute and the attributes that wish to be changed should be supplied. Not all attributes can be changed and those that can will be indicated in the notes. For those Base Entities that support changing the externalId this can be effected by supplying both the internalId and a new externalId on the change request.
  • add – add the supplied elements to the supplied object, typically of the form ‘addTo<Type>’. Typically no response is returned (exception is for asynchronous operations). For is ‘addTo<Type>(base object, added object).
• Consistent use of the following as suffixes:
  • xxxxxxUsing<Type> – indicates that this method uses an argument of type <Type> to further qualify the methods scope.
  • xxxxxxAs<Type> – indicates that this method returns a result of type <Type>.
  • If both suffixes are being used ‘As’ should be the last.
• General authorization rules:
  • Any SOAP client of the API must have the WebServiceUser role.
  • In addition for authorization the context must match an additional role, i.e. if the additional role is AccountManager then the context must be account or below, for EnterpriseManager the context must be Enterprise or below.

API Usage

• All change methods associated with Entity Objects update all fields/attributes to new values
• All change methods associated with State Objects only change non-null fields/attributes
• All methods return a response type consisting of both a data element and an error element. If there are errors then the data element will be null.
• When using “query by example” – only the desired fields need to be provided and all provided fields must be equal in order for a match to succeed.