...
Note: The ‘values’ member is present for any field of type picklist, and picklist fields that do not have the ‘restricted’ member are advisory. The Service Desk WS API enforces the list of values for picklist fields on insert or update.
The query call always returns the value, not the label. The corresponding label for a value in the describe response can be used when displaying the value to the user in any user interface.
Date Time Fields
The Service Desk WS API transfers all Date/Time fields using the XML-RPC type dateTime.iso8601 or the SOAP type dateTime. However, Service Desk has two different ways of handling dates and times internally.
In some cases, you can handle these Date/Time fields identically, but in other cases you can treat them differently.
Regular Date/Time Fields:
The Regular Date/Time fields are stored as the number of seconds after midnight January 1, 1970 GMT. They are automatically converted in the GMT/UTC time zone. You do not need to translate your local timestamp into GMT/UTC time zone value.
Examples of regular the Date/Time fields include all Create Date fields and the Start and End DateTime fields.
Date-Only Fields:
Some fields in Service Desk are Date-Only fields. The time portion of a Date-Only field is not relevant, and is set to midnight in the GMT/UTC time zone.
The Date-Only fields are transferred in the API as dateTime types for SOAP and as dateTime.iso8601 types for XML-RPC calls, since XMLRPC does not have a Date-Only type.
Consider the following best practices:
- Handle the Date-Only field values differently than regular Date/Time values:
- Ignore any time portion.
- Send time portions as all zeroes.
The Service Desk accepts Date-Only values that have a non-zero time portion. However, the time portion is always truncated to zero. Do not alter any Date-Only values to account for time zone changes, since the time portion is irrelevant.
Custom Fields
In the Service Desk user interface, organizations can define a set number of custom fields for different entities. Usually, clients of the Service Desk WS API do not need to know whether a field is a standard field or a custom field for the organization.
Custom fields have a unique field ID, rather than an English-readable ID name. This unique field ID is always prefixed with ‘cf_’ in all calls. When making requests, you must also prefix any custom field IDs with the string ‘cf_’. This restriction does not apply to the XML-RPC implementation of the Service Desk WS API.Note: All
| Note |
|---|
All numeric custom fields are handled as type integer. |
The ID Fields
The id field is created automatically upon insertion. This field cannot change over the lifetime of that record, even when the record is deleted and then undeleted. Each id value is guaranteed to be globally unique. The id of a record is the best way to identify that record uniquely. When inserting or updating records, the API accepts an integer ID.
The Cross-Reference ID Fields
Many entities contain cross-reference ID fields, which are similar to foreign key fields in a database table. In some cases, an entity can refer to another entity of its same type. For example, tickets have a parent link that can point to another ticket.
You can also query each cross-referenced entity. When you query a cross-reference ID field, it returns an entity ID of the appropriate type. You can then query that ID to get more information about the entity, using the ID in the id field for that query.
The cross reference ID field value is either a valid record in your organization, or an empty value, which indicates an empty reference.
The cross-reference ID field value, if nonempty, is guaranteed to be an entity in your organization. However, it is not guaranteed that you can query that entity.
Users of an organization who are granted the necessary privileges (permissions) to access query operation on that entity can query that entity. Other users who belong to the same organization can be restricted from viewing or editing the referenced entity.
Specifying a value for a cross-reference ID field when inserting or updating a record has specific limitations also. The value must be a valid entity of the appropriate type. The user must have appropriate access to that entity.
Long Text Fields
You can clear text fields that are not mandatory by entering ##NULL##. However, when you enter ##NULL## in a mandatory field, the standard message displays, indicating that the field is mandatory.
System ModTimeStamp Fields
Most entities have a standard systemModstamp field that contains a timestamp of when the record was last changed. This field is automatically maintained. You cannot insert, update, or delete the field.