Web Service API Calls

All WS API calls must be contained in an HTTP request with appropriate HTTP headers. All Service Desk WS API calls require the following standard arguments:
 
This section contains the following topics:       
                                                                                            

Response to All Calls:

The response to Service Desk WS API calls comprises of a default service response bean class regardless of whether the request succeeded or failed. The get response bean class can contain the following members:

The Get Call

The get call is used to retrieve a predefined set of field values for an entity that is based on the record identifier.

The get Request

Beyond the normal login id and password arguments, the get call also requires the following argument:

The get Response

The default service response for the API calls contains the record in the requested output format for a get call.

The List Call

The list call is used to retrieve records (entities) based on the specified search criteria.

The list Request: Beyond the normal login id and password arguments, the list call also requires the following arguments:

The list Response

The default service response for all the API calls contains the set of records matching the search criteria in the requested output format for a list call.

The insert Call

The insert call is used to create a new record (entity) of a particular type with the specified values.

The insert Request- Beyond the normal login id and password arguments, the insert call also requires the following arguments:

During an insert, you do not need to specify all fields for that entity type. Most fields are optional, except for those fields marked as required in the describe response, indicated by the attribute ‘nullable’ with the Boolean value ‘0’. Fields that are not specified are set to blank or to default values. Fields that are too long are truncated.

When you send unrecognized field values in the insert request, the Web Service API rejects the call. As a result, status code 300 is transmitted, as indicated by the following message:

Rejecting the value that is supplied for input data element "{ 0} "; due to a correlation failure because the data transformation process could not resolve the supplied input data element into native format.

The API applies a strict definition of unrecognized field values such that all fields in the call must be valid for the user for that operation.

For example:

• The API rejects calls that specify a value for a custom field that was deleted or removed from a user's access.
• The API rejects calls that specify read-only fields.

For some types of entities, the API does not insert new records when you insert a record that existed previously.

The insert Response

The default service response for all the API calls contains the Record Identifier (Row ID) of a record being inserted in the requested output format for an insert call.

The update Call

The update call is used to modify an existing record (entity) identified by the record identifier with specified values.

The update Request

Beyond the normal login id and password arguments, the update call also requires the following arguments:

Member: Bean Class

Description: Entity-specific java bean class (complex data type) containing values for the fields which must be updated, while updating an existing entity identified by the record identifier.

During an update, you do not need to specify all fields for that entity type. Pass the values for those fields which you would like to update during this call.

Fields that are not specified are kept intact. Fields that are too long are truncated. If you send unrecognized field values in the update request, the Service Desk WS API rejects the call and sends status code 300 with an associated status message that indicated the following:

Rejecting the value supplied for input data element "{ 0} "; due to a correlation failure because the data transformation process could not resolve the supplied input data element into native format.

• The API applies a strict definition of unrecognized field values such that all fields in the call must be valid for the user for that operation. For example: The API rejects calls that specify a value for a custom field that was deleted or removed from a user’s access.
• The API rejects calls that specify read-only fields.

The update Response: The default service response for all the API calls contain the Record Identifier (Row ID) of a record being updated in the requested output format for an update call.

When a user tries to update the ticket, an error message displays indicating that the following fields are read-only fields:

• Requester Organization
• Requester Location
• Requester Site
• Requested for Organization
• Requested for Location
• Requested for Site
• Parent Case

The delete Call

The delete call is used to delete an existing record (entity) identified by the record identifier.

The delete Request- Beyond the normal login id and password arguments, the delete call also requires the following argument:

The delete Response

The default service response for all the API calls contain the Record Identifier (Row ID) of a record being deleted in the requested output format for a delete call.

The relate Call

The relate call is used to relate an entity (record) to another entity identified by their respective record identifiers.

The relate Request: Beyond the normal login id and password arguments, the relate call also requires the following arguments:

The relate Response: The default service response for all the API calls can contain the Record Identifier (Row ID) of a record being inserted into the relationship table in the requested output format for a relate call.

The unrelate Call

The unrelate call is used to unrelate an entity record from another entity that is identified by their respective record identifiers.

The unrelate Request- Beyond the normal login id and password arguments, the unrelate call also requires the following arguments:

The unrelate Response: The default service response for all the API calls can contain the Record Identifier (Row ID) of a record being inserted into the relationship table in the requested output format for a relate call.

Field-level Security

The Service Desk WS API enforces the field-level security model that is set up in the Service Desk user interface. In the user interface, certain fields could be marked as read-only or hidden in the page layouts.

For a particular user, the API can access only those fields that are accessible to that user in their assigned page layout. The following restrictions apply:

• The API can query read-only fields, but cannot insert or update them for that user.
• The API cannot query, insert, or update fields that are marked as hidden for that user.

With the Service Desk WS API, hidden fields are not visible to any users, even users with full privileges. This behavior is consistent with how the application functions.

Numeric Fields

The numeric fields include fields of type integer and double. The standard, predefined fields are of type integer or double, according to criteria explained in Determining the Type of Standard Fields. All numeric custom fields are handled as type double. 

The numeric fields must be transferred as i4 or double types, as appropriate, with the exception that you can set a numeric field to null by setting it to a blank string value. The type is indicated in the describe response for an entity. 

The type must be respected in all future calls that refer to that field, including the insert and update calls. The type for the field is also returned from the query call. 

The numeric field bounds are enforced when inserting or updating records. The bounds are indicated in the describe response by the ‘digits’ attribute to an integer field, or by the ‘scale’ and ‘precision’ attributes to a double field.

The maximum number of digits to the left of the decimal place is equal to ‘precision’ minus ‘scale’. In the Service Desk user interface, precision is defined differently; it is the maximum number of digits that are allowed to the left of the decimal place. 

The limits for numeric fields are enforced when inserting or updating data. However, the Service Desk WS API can return data that does not meet these restrictions.