URL

Operations

• create: Creates an agent.

• delete: Marks one agent for deletion, but does not permanently delete the agent.

• get: Returns one agent, using the URL https://<server>/unifiedconfig/config/agent/<id>.

• list: Retrieves a list of agents.

  • Query parameters:

    • selectedAttribute: Use this query parameter to augment the returned agent parameters with an extra parameter called selectedAttribute. This parameter indicates if the agent belongs to the attribute with the ID specified in this query parameter. For example, to find out which agents belong to the specified attribute, add selectedAttribute=5000.

      Note	Using selectedAttribute automatically sets the summary list query parameter to true.

    • selectedSkillGroup: Use this query parameter to augment the returned agent parameters with an extra parameter called selectedSkillGroup. This parameter indicates if the agent belongs to the skill group with the ID specified in this query parameter. For example, to find out which agents belong to the specified skill group, add selectedSkillGroup=5001.

    • ignoreRole: Use this query parameter to allow a supervisor to see a list of all agents in the system, including agents the supervisor does not supervise. For example, to see all agents, add ignoreRole=true.

    • Summary list: See list.

• update: Updates one agent.

Note	API access is provided to users who have Configuration access (but not Setup access) assigned on the User List page. Additionally, the Agent Explorer must be enabled in the Feature Control Set List page.

Parameters

• refURL: The refURL for the agent. See Shared Parameters.

• agentId: The unique peripheral number. Maximum length of 11 characters allowed. The default is an autogenerated 7-digit number.

• changeStamp: See Shared Parameters.

• description: See Shared Parameters.

• agentStateTrace: Indicates if agent state tracing is turned on for the agent. True or false.

• agentDeskSettings: A reference to the agent's agentDeskSettings, including the refURL and name. See References.

• peripheral: Required for Create API only but not-required for Update API. Includes the following parameters:

  • id: A mandatory field for Create API only. Peripheral's ID under which the new agent exists. This value is not allowed to be changed or updated.

• department: Ignored for Create and Update APIs.

• name: The agent's enterprise name. It is autogenerated if not explicitly set. This name can be updated.

• person: Required. Includes the following parameters:

  • firstName: Agent's first name. Maximum of 32 characters. International characters are allowed.

  • lastName: Agent's last name. Maximum of 32 characters. International characters are allowed.

  • userName: Agent's username. Maximum of 32 alphanumeric characters.

  • password: Agent's password. Maximum of 256 ASCII characters. The password is case-sensitive. Password can be used when creating or updating, but is not returned.

  • changeStamp: Mandatory for any person Update action.

  • emailAddress: The email address of the person. It can be updated.

  • description: Optional. Person's description. It can be updated.

  • department: Ignored for Create, Update, and Read APIs.

• supervisor: Required. Indicates whether the agent is marked as supervisor. True or false.

• supervisorUserInfo: Required if supervisor is set to true. User information about an existing Active Directory account for the supervisor. Includes the following parameters:

  • userName: Supervisor's Active Directory username.

  • domainName: Supervisor's Active Directory (Active Directory Domain API) domain name. If the domainName is empty, system uses default domain name.

• agentAttributes: A collection of agent attribute (Attribute API) references for this agent, including the refURL, and read-only parameters name, dataType, and description for each associated attribute. Also includes the attributeValue parameter which indicates the value (true or false or 1-10), and description of the attribute for this agent. See References.

• agentAttributesAdded: A collection of agent attribute references (Attribute API) to be added to the agent, including the agent refURL and the attributeValue of each attribute. If the attributeValue is not specified, it is assigned the default value. Agents that already have this attribute are updated with the specified attributeValue. This parameter is update only, and cannot be used with the agentAttributes parameter. This parameter can be used with the agentAttributesRemoved parameter. See References.

• agentAttributesRemoved: A collection of agent attribute references (Attribute API) to be removed from the agent, including the refURL of each attribute. This parameter is update only, and cannot be used with the agentAttributes parameter. This parameter can be used with the agentAttributesAdded parameter. See References.

• selectedAttribute: Indicates if the agent has the specified attribute. Returned only when using the selectedAttribute query parameter. True or false.

• skillGroups: A collection of skill group references for this agent (Skill Group API), including the refURL and name of each associated skill group. See References.

• skillGroupsAdded: A collection of skill group references to be added to the agent, including the refURL of each skill group to be added. This parameter is update only, and cannot be used with the skillGroups parameter. This parameter can be used with the skillGroupsRemoved parameter. See References.

• skillGroupsRemoved: A collection of skill group references to be removed from the agent, including the refURL of each skill group to be removed. This parameter is update only, and cannot be used with the skillGroups parameter. This parameter can be used with the skillGroupsAdded parameter. See References.

• defaultSkillGroup: A reference to a skill group, including the refURL and name. Identifies the default skill group associated with this agent. See References

  .

• selectedSkillGroup: Indicates if the agent has the specified skill group. Returned only when using the selectedSkillGroup query parameter. True or false.

• agentTeam: A reference to the agent's team (Agent Team API), including the refURL and name. See References.

• supervisorTeams: If this agent has supervisor access, this collection of references is for this supervisor's teams, including the refURL and name of each supervised team. See References.

Search and Sort Values

The following table shows the parameters that are searchable and the parameters that are sortable.

See Search and Sort.

Advanced search parameters

• supervisor: (true/false) Find agents that are (or are not) supervisors.

  • q=supervisor:true Returns all agents who are supervisors.

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

• attributes: (attr1 & attrt2 & attr3, ...) find all agents that have all the specified attributes. Up to 10 attributes can be specified. The attribute names are fully matched.

• skillgroups: (skill1 & skill2 & skill3,...) find all agents that have all the specified skillgroups. Up to 10 skillgroups can be specified. The skill group names are fully matched.

• team: (team1|team2|team3, ...) find all agents who belong to any of the specified teams. Up to ten team names can be specified. The team name is fully matched.

• include: (ID1 & ID2 & ID3, ...) find all specified agents even if they do not meet other search criteria. Each ID is fully matched. Obtain this ID from the refURL. For example, 5017 is the ID in the following refURL <refURL>/unifiedconfig/config/agent/5017</refURL>.

• exclude: (ID1 & ID2 & ID3, ...) exclude all specified agents from the results even if they meet all other search criteria. Each ID is fully matched. Obtain this ID from the refURL. For example, 5017 is the ID in the following refURL <refURL>/unifiedconfig/config/agent/5017</refURL>.

Agent-Person Mapping

There are the following allowed Agent-Person relation:

• many-to-one: when agents are mapped to different peripherals;

From the Peripheral resource perspective, there is the following allowed Peripheral-Agent-Person relation:

• one-many-one: which means that a Person resource is not allowed to have more than one Agents for a specific Peripheral;

Example of Agent-Person Mapping requests:

Create a new Agent resource:

• by mapping it to a non existing Person resource

  <agent>
      <peripheral>
          <id>5000</id>
      </peripheral>
      <person>
          <firstName>SVFN1</firstName>
          <lastName>SVLN1</lastName>
          <loginEnabled>true</loginEnabled>
          <ssoEnabled>false</ssoEnabled>
          <userName>SVLoginName1</userName>
      </person>
      ...
  </agent>

• by mapping it to an existing Person resource without updating Person fields

  <agent>
      <peripheral>
          <id>5000</id>
      </peripheral>
      <person>
          <refURL>/unifiedconfig/config/person/14915</refURL>
      </person>
      ...
  </agent>

• by mapping it to an existing Person resource and by updating some Person fields

  <agent>
      <changeStamp>8</changeStamp>
      <person>
          <firstName>SVFN1</firstName>
          <lastName>SVLN1</lastName>
          <loginEnabled>true</loginEnabled>
          <ssoEnabled>false</ssoEnabled>
          <userName>SVLoginName1</userName>
      </person>
      ...
  </agent>
  
  

Example Get Response

  <agent>
        <changeStamp>2877</changeStamp>
        <refURL>/unifiedconfig/config/agent/5017</refURL>
        <agentId>8006</agentId>
        <agentStateTrace>false</agentStateTrace>
        <peripheral>
             <id>5000</id>
             <name>CUCM_PG_1</name>
        </peripheral>
        <description>an agent</description>
        <person>
             <firstName>Agent2</firstName>
             <lastName>Agent2</lastName>
             <loginEnabled>true</loginEnabled>
             <userName>Agent2@cisco.com</userName>
             <password>mypassword</password>
             <ssoEnalbed>false</ssoEnabled>
       </person>
        <agentDeskSettings>
             <name>test2</name>
             <refURL>/unifiedconfig/config/agentdesksetting/5434</refURL>
        </agentDeskSettings>
        <supervisor>true</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>
         <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>