Standard Field Types

The server determines whether a standard, predefined numeric field can be handled as a double XML-RPC type or as an i4 XML-RPC type. Normally, the server chooses to use type i4 when the scale is zero and type double when the scale is greater than zero.

The i4 type in XMLRPC is limited to a 4-byte integer. It cannot handle the full range of integer values that are supported by Service Desk integer fields. As a result, the server indicates a type of double for numeric fields with a scale greater than zero, or with a precision greater than nine.

However, there is no loss of precision for large integer values (greater than 15 or 16 digits) that are transferred using the Service Desk WS API. Clients should not encode this logic themselves, but should use the type that is specified in the describe response.

The decision of when to use double or i4 type can change in the future. However, changes are reflected in the describe response.

This article contains the following topics:

Enumerated Fields

In the Service Desk WS API, enumerated fields are fields that are restricted to a defined list of values. They are indicated in the describe response with the Boolean value ‘1’ for the ‘restricted’ member of the ‘fields’ substructure. The allowed values for enumerated fields are specified in the ‘values’ array of the ‘display’ substructure of the describe response.

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.

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

Several entities contain long text fields (256 bytes, 4000 bytes, and so on) that can contain data spanning multiple lines.

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.