Usage and Behavior

Duplicate Parameters

If a parameter is duplicated, the final value that is specified will be used by the API.

Read-Only Fields

Read-only parameters are ignored on create and update operations.

References

References are a type of parameter that provide a way to connect one item to another item, defining the relationship between them.

For example, to define which team an agent belongs to, the agent contains a reference to a team. When performing list or get operations, the reference contains the refURL of the item and the name. For example:

Code Snippet

Copy<agent>
   <team>
     <refURL>/unifiedconfig/team/5000</refURL>
     <name>NameOfTeam</name>
   </team>
  …
</agent>

For items that do not have a name parameter, other parameters such as firstName and lastName are included.

Code Snippet

Copy<agent>
  <refURL>/unifiedconfig/config/agent/5000</refURL>
  <firstName>Jane</firstName>
  <lastName>Doe</lastName>
  <userName>username</userName>
  <agentId>8007</agentId>
  <canRemove>true</canRemove>
</agent>

When doing create or update, only the refURL parameter is required. Additional parameters are ignored. For example:

Code Snippet

Copy<agent>
   <team>
     <refURL>/unifiedconfig/team/5000</refURL>
   </team>
  …
</agent>

Items can also contain a collection of references. For example, if an agent belongs to multiple skill groups, the skillGroups parameter contains a reference to each associated skill group:

Code Snippet

Copy<agent>
  <skillGroups>
    <skillGroup>
      <refURL>/unifiedconfig/config/skillgroup/5001</refURL>
      <name>FirstSkill</name>
    </skillGroup>
    <skillGroup>
      <refURL>/unifiedconfig/config/skillgroup/5005</refURL>
      <name>AnotherSkill</name>
    </skillGroup>
  </skillGroups>
  …
</agent>

If the referenced item belongs to a department, then department information is included within that reference:

Code Snippet

Copy<agentDeskSettings>
   <refURL>/unifiedconfig/config/agentdesksetting/5001</refURL>
   <name>mike</name>
   <department>
      <refURL>/unifiedconfig/config/department/5003</refURL>
      <name>d1</name>
   </department>
</agentDeskSettings>

If the referenced item is a global item, then department information is omitted from the reference.

XML

XML is case sensitive. When XML data is sent to the server, the tag names must match. <Name> and <name> are two different XML elements.