Agent API
Download this chapter
Agent APIAgent API
 Feedback

Agent API

You can use the Agent API to list the Agents currently defined in the database, define new Agents, and view, edit, or delete records of existing Agents.

Agent API Commands

This section explains the five supported API operations for Agent and outlines the parameters.

API Parameters

The following table shows the parameters for Agent API.

Parameter Name

Description

agentId

The peripheral number.

description

The description of this desk setting.

agentStateTrace

If true, turn on Agent State Tracing for the agent. A maximum of 100 agents can have this flag set to true.

changeStamp

The version of the agent object. Initially set by the database during a create. Must be passed back for update operations.

AgentDeskSettings.refURL

refURL to the agentDeskSettings object.

person.firstName

First name of the agent/person.

person.lastName

Last name of the agent/person.

person.userName

User name of the agent/person.

person.password

Password for the agent/person.

Note    This is not returned in read operations.

person.loginEnabled

Indicates whether an agent/person can log in.

supervisor

Indicates whether the agent is marked as supervisor.

supervisorUserInfo.userName

The Active Directory userName for this supervisor.

supervisorUserInfo.domainName

The Active Directory Domain name for this supervisor. If empty, it uses the default domain name.

agentAttribute.attributeValue

The value of the attribute for the agent.

agentAttribute.description

Per agent attribute description.

agentAttribute.attribute.refURL

The refURL to the attribute object.

agentAttribute.attribute.name

Name of the attribute.

agentAttribute.attribute.dataType

Type of attribute.

agentAttribute.attribute.description

Attribute description.

skillGroup.refURL

The refURL to the skill group.

skillGroup.name

Name of the skill group.

defaultSkillGroup.refURL

The refURL to the default skill group.

defaultSkillGroup.name

Name of the default skill group.

agentTeam.refURL

The refURL to the agent team.

agentTeam.name

Name of the agent team.

supervisorTeam.refURL

The refURL to the supervisor's team.

supervisorTeam.name

Name of the supervisor's team.

create

Creates an Agent record and stores the data in the database.

URL:

https://<server>/unifiedconfig/config/agent

HTTP Method:

POST

Input/Output Format:

XML

Parameters:

See API Parameters

Example Response: 

<agent>
        <agentId>8006</agentId>
        <agentStateTrace>false</agentStateTrace>
        <description>an agent</description>
        <person>
             <firstName>Agent2</firstName>
             <lastName>Agent2</lastName>
             <loginEnabled>true</loginEnabled>
             <userName>Agent2</userName>
             <password>mypassword</password>
       </person>
        <agentDeskSettings>
             <refURL>/unifiedconfig/config/agentdesksetting/5434</refURL>
        </agentDeskSettings>
         <supervisor>true</supervisor>
         <supervisorUserInfo>
               <userName>boston</userName>
               <domainName>boston.com</domainName>
         </supervisorUserInfo>
         <agentAttributes>
               <agentAttribute>
                    <attribute>
                        <refURL>/unifiedconfig/config/attribute/5004</refURL>
                        <name>Sales</name>
                        <dataType>4</dataType>
                        <description>Sales proficiency</description>
                    </attribute>
                    <attributeValue>8</attributeValue>
                    <description>masters certification</description>
              </agentAttribute>
         </agentAttributes>
         <skillGroups>
            <skillGroup><refURL>/unifiedconfig/config/skillgroup/18434</refURL>
            </skillGroup>
            <skillGroup><refURL>/unifiedconfig/config/skillgroup/18435</refURL>
            </skillGroup>
        </skillGroups>
        <defaultSkillGroup><refURL>/unifiedconfig/config/skillgroup/18434</refURL>
        </defaultSkillGroup>
        <agentTeam><refURL>/unifiedconfig/config/agentteam/5003</refURL></agentTeam>
        <supervisorTeams>
           <supervisorTeam><refURL>/unifiedconfig/config/agentteam/5003</refURL>
           </supervisorTeam>
           <supervisorTeam><refURL>/unifiedconfig/config/agentteam/5006</refURL>
           </supervisorTeam>
       </supervisorTeams>
</agent>

Response:

In the Response, the Location header has a URL to the newly created Agent, if successful.

See also HTTP Responses.

Operation Validation:

agentId

  • Optional field.
  • Max: 11-digit number.
  • Leading zeros are allowed.
  • Auto-generated if not supplied.

description

  • Optional field.
  • No restriction of characters.
  • Max length of 255 bytes allowed.
  • For details on valid characters for this field, see Internationalization.

agentStateTrace

  • Optional field.
  • True or false; default value is false.
  • Capacity limit of 100 Agents with this parameter set to true.

agentDeskSettings.refURL

  • Optional field.
  • Valid AgentDeskSettings URL.
  • Null is also valid.

changeStamp

  • Optional field.
  • Integers only: start with 0.

person.userName

  • Required field.
  • Max length of 32 bytes allowed.
  • Valid characters are period (.), underscore (_), and alphanumeric. The first character must be alphanumeric.
  • Name must be unique.
  • Does not allow internationalized characters.

person.firstName

  • Required field.
  • No restriction of characters.
  • Max length of 32 bytes.
  • For details on valid characters for this field, see Internationalization.

person.lastName

  • Required field.
  • No restriction of characters.
  • Max length of 32 bytes.
  • For details on valid characters for this field, see Internationalization.

person.password

  • Optional field.
  • No restriction of characters.

person.loginEnabled

  • Optional field.
  • True or false; default value is true.

supervisor

  • Optional field.
  • If present and set as true, supervisorInfo element must exist.
  • If set as false, supervisorInfo is ignored.

userName

  • Required field if the agent is set to be a supervisor.
  • Max: 64 bytes.
  • Valid characters are period (.), underscore (_), and alphanumeric. The first character must be alphanumeric.
  • User must exist in the Active Directory.

domainName

  • Optional field: if missing, uses the default domain name.
  • Max: 64 bytes.
  • Valid characters are period (.), underscore (_), and alphanumeric. The first character must be alphanumeric.

agentAttributes

  • Optional field.
  • Zero or more attributes can be specified.
  • The attribute.refURL must refer to valid, non-deleted attributes. It must be specified.
  • The agentAttribute.attributeValue must be valid for the attribute type (for boolean: true or false; for proficiency: integer between 1 and 10 inclusive).
  • No more than 50 attribute values per Agent.

skillGroups

  • Optional field.
  • Zero or more Skill Groups can be specified.
  • The skillGroup.refURL must refer to a valid, non-deleted Skill Group. If a Skill Group is specified, the refURL must be specified.

defaultSkillGroup

  • Optional field.
  • Only one defaultSkillGroup can be specified.
  • If the defaultSkillGroup tag is specified, it must reference a Skill Group that is listed in the skillGroups. That is, it must reference a Skill Group that the Agent is a member of.

agentTeam

  • Optional field.
  • An agent can only belong to one team, at most.
  • If the agentTeam tag is specified, the agentTeam.refURL tag must be specified and refer to a valid team.
  • A team can contain up to 50 agents.

supervisorTeam

  • The Agent must be a Supervisor.
  • The supervisorTeam.refURL tag must be valid and refer to a valid team.
  • A Supervisor can supervise from 0-20 teams.
  • A team can have 0-10 Supervisors.
  • A Supervisor can be both a member of and a Supervisor of the same team.

delete

Deletes one Agent record and the associated Person object from the database.

The delete operation automatically deletes any Skill, Attribute, Team, or Supervisor reference to the Agent.


Note
The operation only marks the record for deletion, it does not permanently delete it.

URL:

https://<server>/unifiedconfig/config/agent/<id>

HTTP Method:

DELETE

Response:

See HTTP Responses.

Operation Validation:

You cannot delete an Agent that is referenced by a Script.

You cannot delete an agent that is a supervisor assigned to an Agent Team.

When you try to delete an Agent who is assigned as Supervisor, the associated record created in UserGroup is deleted. In addition, other items are cleaned up, such as the record in User_Supervisor_Map.

list

Retrieves a list of agents.

URL:

https://<server>/unifiedconfig/config/agent

HTTP Method:

GET

Example XML Response: 

<results>
  <pageInfo>
    ...  (see pagination data)
  </pageInfo>
  <agents>
    <agent>...</agent>
    <agent>...</agent>
  </agents>
</results>

Note    The preceding example XML response does not show all of the data for pagination.

See Pagination.

Also, the example XML response does not show permissions information. See Permissions Information.

See also HTTP Responses.

Summary List

By default, the list command returns a list of Agents with all the agent data that is returned by the GET command documented below. However if Agents contain a large number of skillgroups and attributes, this can result in a large amount of data being returned. Therefore the summary=true query option returns a much smaller amount of data per agent. It just returns the basic agent data and the person data. An example is performing a GET on https://<server>:<serverport>/unifiedconfig/config/agent2?summary=true. 

<results>
  <pageInfo>
    ...  (see pagination data)
  </pageInfo>
  <agents>
    <agent xsi:type="agentSummary">
        <changeStamp>7</changeStamp>
        <refURL>/unifiedconfig/config/agent/10884</refURL>
        <agentId>4294305</agentId>
        <agentStateTrace>false</agentStateTrace>
        <agentTeam>
           <refURL>/unifiedconfig/config/agentteam/5005</refURL>
           <name>monsters</name>
        </agentTeam>
        <description>Here is a descr</description>
        <person>
            <firstName>as</firstName>
            <lastName>a1</lastName>
            <loginEnabled>true</loginEnabled>
            <userName>aaa</userName>
        </person>
       <supervisor>false</supervisor>
    </agent>
    <agent>...</agent>
  </agents>
</results>

Note that the " <agent ..> " tag has the attribute: xsi:type="agentSummary" that indicates it contains a agent summary object. For non-summary lists, the value would be: xsi:type="agent".

Supervisor Search

The supervisor search parameter allows you to specify a search to find Agents that are (or are not) supervisors.

For example:
  • q=supervisor:true Returns all agents who are supervisors.
  • q=supervisor:false Returns all agents who are not supervisors.

Advanced Search

In addition to the supervisor search, you can perform the following advanced searches:

  • attributes: (attr1 & attrt2 & attr3, ...)
  • skillgroups: (skill1 & skill2 & skill3,...)
  • team: (team1|team2|team3, ...)

The attributes search returns all Agents that have all the specified attributes. Up to ten attributes can be specified. The attribute names are fully matched.

The skillgroups search returns all agents that have all the specified skillgroups. Up to ten skillgroups can be specified. The skillgroup names are fully matched.

The team search returns all agents who belong to any of the specified teams. Up to ten team names can be specified. The team name is fully matched.

The following restrictions apply:
  • Searches for attribute names, skillgroup names, and team names are case insensitive.
  • There must be a space separator between any of the special search terms.
  • The & separator within the attributes:() and skillgroups:() search must be URL-encoded to %26 before being sent to the server, otherwise the server will interpret it as an http parameter separator.
  • The search terms can be separated in any order, such as:
    q=test description attributes:(a1 & a2) skillgroups:(sk1 & sk5) team:(sales | support) supervisor:false
    • The above must be sent as: q=test description attributes:(a1 %26 a2) skillgroups:(sk1 %26 sk5) team:(sales | support) supervisor:false
    Or:
    q=team:(sales) attributes:(a1 & a2) test description
    • The above must be sent as: q=team:(sales) attributes:(a1 %26 a2) test description

get

Returns one Agent record from the database.

URL:

https://<server>/unifiedconfig/config/agent/<id>

HTTP Method:

GET

Example XML Response: 

<agent>
	<changeStamp>2877</changeStamp>
        <refURL>/unifiedconfig/config/agent/5017</refURL>
        <agentId>8006</agentId>
        <agentStateTrace>false</agentStateTrace>
        <description>an agent</description>
        <person>
             <firstName>Agent2</firstName>
             <lastName>Agent2</lastName>
             <loginEnabled>true</loginEnabled>
             <userName>Agent2</userName>
             <password>mypassword</password>
       </person>
        <agentDeskSettings>
             <name>test2</name>
             <refURL>/unifiedconfig/config/agentdesksetting/5434</refURL>
        <supervisor>true</supervisor>
        </agentDeskSettings>
        <supervisorUserInfo>
              <userName>boston</userName>
              <domainName>boston.com</domainName>
        </supervisorUserInfo>
        <agentAttributes>
               <agentAttribute>
                    <attribute>
                        <refURL>/unifiedconfig/config/attribute/5004</refURL>
                        <name>Sales</name>
                        <dataType>4</dataType>
                        <description>Sales proficiency</description>
                    </attribute>
                    <attributeValue>8</attributeValue>
                    <description>masters certification</description>
              </agentAttribute>
         </agentAttributes>
         <skillGroups>
             <skillGroup>
                 <refURL>/unifiedconfig/config/skillgroup/5229</refURL>
                 <name>Support</name>
             </skillGroup>
        </skillGroups>

        <defaultSkillGroup>
             <refURL>/unifiedconfig/config/skillgroup/5229</refURL>
             <name>Support</name>
        </defaultSkillGroup>

         <agentTeam>
             <refURL>/unifiedconfig/config/agentteam/5003</refURL>
             <name>theTeam</name>
         </agentTeam>
         <supervisorTeams>
             <supervisorTeam>
                <refURL>/unifiedconfig/config/agentteam/5003</refURL>
                <name>theTeam</name>
             </supervisorTeam>
             <supervisorTeam>
                <refURL>/unifiedconfig/config/agentteam/5006</refURL>
                <name>theBTeam</name>
             </supervisorTeam>
        </supervisorTeams>
  </agent>

See HTTP Responses.

Example XML Response, if Supervisor is False: 

<agent>
	<changeStamp>2877</changeStamp>
        <refURL>/unifiedconfig/config/agent/5017</refURL>
        <agentId>8006</agentId>
        <agentStateTrace>false</agentStateTrace>
        <description>an agent</description>
        <person>
             <firstName>Agent2</firstName>
             <lastName>Agent2</lastName>
             <loginEnabled>true</loginEnabled>
             <userName>Agent2</userName>
             <password>mypassword</password>
       </person>
        <agentDeskSettings>
             <name>test2</name>
             <refURL>/unifiedconfig/config/agentdesksetting/5434</refURL>
        </agentDeskSettings>
        <supervisor>false</supervisor>
        <agentAttributes>
               <agentAttribute>
                    <attribute>
                        <refURL>/unifiedconfig/config/attribute/5004</refURL>
                        <name>Sales</name>
                        <dataType>4</dataType>
                        <description>Sales proficiency</description>
                    </attribute>
                    <attributeValue>8</attributeValue>
                    <description>masters certification</description>
              </agentAttribute>
         </agentAttributes>
 </agent>

update

Updates one Agent record in the database.

URL:

https://<server>/unifiedconfig/config/agent/<id>

HTTP Method:

PUT

Input/Output Format:

xml

Example XML Request Payload: 

<agent>
    <changeStamp>2877</changeStamp>

<refURL>/unifiedconfig/config/agent/5017</refURL>
        <agentId>8006</agentId>
        <agentStateTrace>false</agentStateTrace>
        <description>an agent</description>
        <person>
             <firstName>Agent2</firstName>
             <lastName>Agent2</lastName>
             <loginEnabled>true</loginEnabled>
             <userName>Agent2</userName>
             <password>mypassword</password>
       </person>
        <agentDeskSettings>
             <name>test2</name>

<refURL>/unifiedconfig/config/agentdesksetting/5434
</refURL>
        <supervisor>true</supervisor>
        <supervisorUserInfo>
              <userName>boston</userName>
              <domainName>boston.com</domainName>
        </supervisorUserInfo>
        </agentDeskSettings>
        <agentAttributes>
               <agentAttribute>
                    <attribute>
                        <refURL>/unifiedconfig/config/attribute/5004</refURL>
                        <name>Sales</name>
                        <dataType>4</dataType>
                        <description>Sales proficiency</description>
                    </attribute>
                    <attributeValue>8</attributeValue>
                    <description>masters certification</description>
              </agentAttribute>
         </agentAttributes>
</agent>

Parameters:

See API Parameters.

Response:

See HTTP Responses.

Operation Validation:

Restrictions:

  • All of the restrictions from the create operation apply.
  • Also: you must specify valid Change Stamps for the Agent.

Attribute Update Behavior:

  • If you specify a list of Agent attributes, the list replaces the current list of Agent attributes for the specified Agent.
  • If you specify an empty list of Agent attributes via the <agentAttributes/> tag or equivalent, any current attributes are removed from the Agent.
  • If you do not specify an <agentAttributes/> tag, the current settings remain.

Supervisor Update Behavior:

If you change the supervisor from true to false, you must make sure that supervisor is not referenced by an Agent Team.

SkillGroup Update Behavior:

  • If you specify a list of Skill Groups, it replaces the current list of Skill Groups for the specified Agent.
  • If you specify an empty list of Skill Groups via the <skillGroups/> tag or equivalent, the Agent is removed from all Skill Groups.
  • If you do not specify a skillGroups tag, the current Skill Groups settings remain.

DefaultSkillGroup update Behavior:

If you change the list of Skill Groups that the Agent is a member of, you must also update the defaultSkillGroup to either be Null or point to one of the new Skill Groups.

AgentTeam Update Behavior:

  • If you specify an Agent Team, the Agent is removed from the current team (if they are already in one) and added to the specified team.
  • If you specify an empty team via the <agentTeam/> tag or equivalent, the Agent is removed from the current team.
  • If you do not specify an agentTeam tag, the current Agent Team settings remain.

SupervisorTeam Update Behavior:

  • You must be a Supervisor to specify Supervisor Teams.
  • If you specify a list of Supervisor Teams, the list replaces the current list of Supervisor Teams for the Supervisor.
  • All supervisorTeam.refURLs must be valid refURLs.
  • If you specify an empty list of Supervisor Teams via the supervisorTeams tag or equivalent, the Supervisor is removed as a Supervisor from all teams they currently supervise.
  • A Supervisor can be both a member of and a Supervisor of the same team.
  • If you demote Supervisors to non-supervisors, they are no longer Supervisors for any of their previous teams. In a case where a Supervisor already supervised teams, you must delete that Supervisor's supervisorTeam settings when demoting the supervisor by specifying the empty <supervisorTeams/> tag.

Asynchronous API

See section on Asynchronous API.


Note
For Agent API, the Asynchronous feature is supported only for the create, update, and delete operations.