Request Endpoint

1. Create Incident / Change Request / Service Request

createIncident (String itemNumber, String classificationId, String subject, String description, HashMap customFieldValues)
createChangeRequest (String itemNumber, String classificationId, String subject, String description, HashMap customFieldValues) (since 5.5)
createServiceRequest (String itemNumber, String classificationId, String subject, String description, HashMap customFieldValues) (since 6.0)

Parameters

  • itemNumber The unique Item Number used for the basis of this request
  • classificationId The Item classification Id to use for this request. Use getClassifications(String itemNumber) for a list of classifications available for this item.
  • subject The subject line of this new request.
  • description The description of this request.
  • customFieldValues A HashMap of values with keys custom1 through custom5.

Description

Use these functions to create an Incident, Change Request or Service Request for the logged in User. Simply supply the function with the number of the Item you wish to raise an Incident, Change or Service Request against, the ID of the Classification the Incident falls under and a text description of the problem.

If custom fields are enabled for the Request type being created, these values need to be passed into the customFieldValues HashMap, with keys custom1 through to custom5.

The Item Number and Classification must exist in this function’s derived lists for the Request to be successfully created. The function returns a HashMap containing two fields: ‘success’ and ‘message’.

The value returned in the ‘success’ field will be a string representation of a boolean (‘true’ or ‘false’) indicating whether or not the Request’s creation attempt was successful.

If a Request was successfully created (i.e. the ‘success’ field is ‘true’), the value returned in the ‘message’ field will be a String representation of the new Request’s ID number.

If the process fails for any reason (i.e. the ‘success’ field is ‘false’), the ‘message’ field will contain a text message explaining why the failure occurred.

All three arguments (‘itemNumber,’ ‘classificationNumber’ and ‘Description’) are required. Omitting any of the three will result in failure and a message explaining the circumstances.

2. Create Incident / Change Request / Service Request (for a Customer)

createIncidentCustomer (String customerId, String itemNumber, String classificationId, String subject, String description, HashMap customFieldValues)
createIncidentDates(String customerId, String itemNumber, String classificationId, String subject, String description, HashMap customFieldValues, String reportDate, String closeDate, String closingTechId) (since 6.5)
createChangeRequestCustomer (String customerId, String itemNumber, String classificationId, String subject, String description, HashMap customFieldValues) (since 5.5)
createServiceRequestCustomer (String customerId, String itemNumber, String classificationId, String subject, String description, HashMap customFieldValues) (since 6.0)

Parameters

  • customerId The unique Customer Id to create the request against.
  • itemNumber The unique Item Number used for the basis of this request
  • classificationId The Item classification Id to use for this request. Use getClassifications(String itemNumber) for a list of classifications available for this item.
  • subject The subject line of this new request.
  • description The description of this request.
  • customFieldValues A HashMap of values with keys custom1 through custom5.
  • reportDate The date the request will be initially recorded. Date must be formatted as ‘yyyy-mm-dd hh:mm’
  • closeDate The date the request should be recorded as closed. Date must be formatted as ‘yyyy-mm-dd hh:mm’
  • closingTechId The id of the technician that closed the request.

Description

Use this to create an Incident, Change Request or Service Request for a Customer created from the createCustomer() function. Provide the Customer ID, the Item Number you wish to raise the Request against, the ID of the Classification the Request falls under and a text description of the problem.

If Custom Fields are enabled for the Request type being created, these values need to be passed into the customFieldValues HashMap, with keys custom1 through to custom5.

The item number and classification must exist in this function’s derived lists for the Incident to be successfully created.

The function returns a HashMap containing two fields: ‘success’ and ‘message’.

The value returned in the ‘success’ field will be a string representation of a boolean(‘true’ or ‘false’) indicating whether or not the Incident’s creation attempt was successful.

If a Request was successfully created (i.e. the ‘success’ field is ‘true’), the value returned in the ‘message’ field will be a String representation of the new Incidents’s ID number. If the process fails for any reason (i.e. the ‘success’ field is ‘false’), the ‘message’ field will contain a text message explaining why the failure occurred.

All four arguments (‘customerId’, ‘itemNumber,’ ‘classificationNumber’ and ‘Description’) are required.

[colored_box variation=”slategrey”]
reportDate and closeDate must be formatted as ‘yyyy-mm-dd hh:mm’ strings to be correctly parsed and will set the dates the request was logged and closed, setting the appropriate times against the SLA. This can be combined with adding incident notes to import legacy data into the system.

The closingTechId if set will be used in conjunction with the closeDate to set the technician to credit for the closure.

3. Get Classifications

getClassifications (String itemNumber)

Parameters

  • itemNumber The unique ItemNumber to retrieve classifications from.

Description

The ‘getClassification’ function returns a list of all the classifications that exist in the system for the selected item type. The response is in the form of a HashMap that uses the list of Classification IDs as field names. Each field has a String value containing the name of the Classification. In HEAT LiveTime, Classifications are grouped into a hierarchical tree. The list returned by ‘getClassifications’ will be ordered according to the hierarchical tree as it would appear in the application.

In the event that no Classifications are found, only the ‘message’ field will be present and will contain a text message explaining that no Classifications were found.

Once you have the names of the fields (iter.next() – Classification ID numbers in the above example) you can then use them to look up the names of the Classifications associated with them in the HashMap.

4. Get Subject

getSubject (String requestId) (since 6.0.1)

Parameters

  • requestId Unique id of the request to retrieve subject from.

Description

Returns a HashMap containing the ‘subject’ for the provided Request ID.

5. Get Description

getDescription (String requestId) (since 6.0)

Parameters

  • requestId Unique id of the request to retrieve description from.

Description

Returns a HashMap containing the ‘description’ for the provided Request ID.

6. Get Request Count By Status

getRequestCountByStatus (String statusId) (since 6.0)

Parameters

  • statusId The id of the status to retrieve the request count for. This is the a synonym for the workflow status.

Description

Returns a HashMap containing the ‘requestCount’ for the provided Status ID.

7. Get Requests By Status

getRequestsByStatus (String statusId, String pageNo) (since 6.0)

Parameters

  • statusId The id of the status to return requests against.
  • pageNo The page number to retrieve. These are returned 100 requests at a time.

Description

Returns a HashMap containing the ‘requestId’ as a key and the description as the value, for all Requests in a Status with the given statusId. The returned HashMap also contains the success flag to deal with Requests that can’t be processed for various reasons, along with a message to state the reason.

8. Get Request Detail

getRequestDetail (String requestId) (since 6.0)

Parameters

  • requestId Unique request Id of the request to return details from.

Description

Returns a HashMap containing various fields that make up the request.

The returned HashMap also contains the success flag to deal with requests that can’t be processed for various reasons, along with a message to state the reason.

The returned HashMap contains a success flag and the values for the keys of the given fields:

Key Description
customer Customers full name
customerId Customer ID
customerPhone Customers contact phone number. (since 6.1.4)
orgUnit Organizational Unit display name
orgUnitId Organizational Unit ID
item Configuration Item name
itemId Configuration Item ID
itemNumber Configuration Item Number as displayed to users.
itemStatus Configuration Item status. (since 6.1.4)
itemCriticality Configuration Item criticality. (since 6.1.4)
status Request status
statusId Request status ID
statusEntry If the request is at an entry state of the workflow (since 6.5)
statusExit If the request is at an exit state of the workflow (since 6.5)
statusIsApproval If the request is in an approval status state on the workflow (since 6.5)
classification Request classification
classificationId Request classification ID
impact Request impact
impactId Request impact ID
urgency Request urgency
urgencyId Request urgency ID
priorityType Request priority
priorityTypeId Request priority ID
technician Assigned Technician. (since 6.1.4)
team Assigned Team
teamId Assigned Team ID
dateCreated Request creation date (MM/dd/yyyy HH:mm)
dateClosed Request closed date (MM/dd/yyyy HH:mm)
dateDue Request due date (MM/dd/yyyy HH:mm)
lastUpdated Date request was last updated (MM/dd/yyyy HH:mm)
type Process type (since 6.1.4)
workflow The current workflow (since 6.5)
workflowId The current workflow Id (since 6.5)
editable If the request is editable by the current user based on team membership and other permissions (since 6.5)

9. Get Public Notes

getPublicNotes (String requestId) (since 6.1.1)

Parameters

  • requestId unique Request Id from which to retrieve notes.

Description

This function returns a list of all the public Notes for a given requestId. The returned HashMap contains the Note ID and Note Date.

10. Get Notes

getNotes (String requestId) (since 6.0)

Parameters

  • requestId unique Request Id from which to retrieve notes.

Description

This function returns a list of all the Notes for a given requestId. The returned HashMap contains the Note ID and Note Date.

11. Get Notes Detail

getNotesDetail (String requestId, int pageSize, int pageNumber) (since 6.1.4)

Parameters

  • requestId unique Request Id from which to retrieve notes detail.
  • pageSize the number of elements to return for each page.
  • pageNumber the page number to retrieve with given pageSize.

Description

This function returns a list of all the Notes for a given requestId. The page size and page number can also be specified. The returned HashMap contains the Note ID, Note Date, Private Note Flag, Author and the Note Content.

12. Get Note Content

getNoteContent (String requestId, String noteId) (since 6.0)

Parameters

  • requestId unique Request Id from which to retrieve note content.
  • noteId Note Id to retrieve.

Description

This function returns the content of the Note for the provided Request ID and Note ID.

13. Update Request

updateRequest (String requestId, HashMap fieldValues) (since 6.0)

Parameters

  • requestId The request Id to update.
  • fieldValues Map of Strings to Strings. Valid keys are: customerId, itemId, statusId, classificationId, impactId, urgencyId, custom1, custom2, custom3, custom4 and custom5. (Since 6.1) typeCustom1, typeCustom2, typeCustom3, typeCustom4 and typeCustom5.

Description

Use this function to update a request of any type (Incident, Change Request or Service Request).

The returned HashMap will contain a success flag to deal with Requests that can’t be processed for various reasons, along with a message to state the reason.

14. Find Incident / Change Request / Service Request

findIncident (String itemNumber, String classificationId, HashMap fieldValues) (since 6.0)
findChangeRequest (String itemNumber, String classificationId, HashMap fieldValues) (since 6.0)
findServiceRequest (String itemNumber, String classificationId, HashMap fieldValues) (since 6.0)

Parameters

  • itemNumber Find and Incident based upon on a unique item number
  • classificationId Find an incident based on this classification Id.
  • fieldValues A haspmap of fieldValues that can be searched. Accepts the same keys as updateRequestDetail as well as ‘fulltext’ (Since 8.7) to facilitate full text searches against request content

Description

Use these functions to find an Incident ,Change Request or Service Request. Simply supply the function with the parameters desired to search against and process the resultant list of requests that are returned. The ‘fieldValues’ parameter can take all the arguments that are used in the updateRequestDetail method above. The returned HashMap contains the success flag and a message.

15. Add Note To Request

addNoteToRequest (String requestId, String note) (since 6.0)
addNoteToRequest (String requestId, String note, String privateNdx) (since 6.1)
addNoteToRequest (String requestId, String note, String privateNdx, String timeMins) (since 6.2)

Parameters

  • requestId The requestId to add the note to.
  • note The note contents
  • privateNdx A flag to define the note as being private (1) or public (0).
  • timeMins The time in minutes to add to this note for timesheet reporting and billing.

Description

Members of the assigned team, or the customer of the request can use this method (when logged in) to add a note to a request. The returned HashMap contains the success flag to deal with requests that can’t be processed for various reasons, along with a message to state the reason. If privateNdx is not specified, added notes will be visible to the public. If the privateNdx flag is specified, the value should either be set to 1 or 0, to define the note as being private or public respectively. Time can be assigned to this note for timesheet reporting by using the associated method and adding the time in minutes.

16. Close Request

closeRequest (String requestId, String reason) (since 6.0)

Parameters

  • requestId The request Id to close.
  • reason The reason for closing this request.

Description

The Request is set to the default closed state of the assigned Workflow and add the supplied reason as the solution (if defined), and the target Request is an Incident or Service Request. The returned HashMap contains the success flag and a reason field.

17. Get Response Templates

getResponseTemplates (String requestId) (since 6.5)

Parameters

  • requestId the request Id to retrive the response templates for.

Description

This returns a list of valid response templates for this request. Returns the responseId as the key and the template Title as the value in the response. Use getResponseTemplateContent to retrieve the actual content of a response based on a returned ID from this call.

18. Get Response Template Content

getResponseTemplateContent (String responseId) (since 6.5)

Parameters

  • responseId The response Id of the template to retrieve.

Description

Returns the actual contents of a response template by ID. Use getResponseTemplates to get a list of valid ID’s you can use for this call. Note that the text will be HTML formatted if the text was styled usng the rich text editor and any replacement parameters will show the placeholders (i.e. the placeholders won’t have been replaced with value from the request content).

19. Get Response Template Contents

getResponseTemplateContents (String responseId, String requestId) (since 8.6)

Parameters

  • responseId The response ID of the template to retrieve.
  • requestId The request ID to use for parameter substitution into the template content

Description

Returns the actual contents of a response template by ID, with any parameters populated using the corresponding values of the request specified by request ID. Use getResponseTemplates to get a list of valid ID’s you can use for the response ID. Note that the text will be HTML formatted if the text was styled usng the rich text editor and any replacement parameters will show the actual replacement values using the targeted request.

20. Get My Filters

getMyFilters () (since 6.2)

Parameters

None.

Description

Retrieves a list of Filters by Id and name for the current logged in user. The returned HashMap contains the filter Id as the key and filter name as the value.

21. Get My Task Count

getMyTaskCount () (since 6.1.1)
getMyTaskCount (int filterId) (since 6.2)

Parameters

  • filterId The unique filter Id to use to return the number of requests available with that filter.

Description

Retrieves the number of currently active and assigned tasks to the current logged in user. The returned HashMap contains a success flag and the number of tasks. If a filterId is passed in then it will return the number of requests with the given filter applied.

22. Get My Tasks

getMyTasks (int pageSize, int pageNumber, List fields, HashMap sortMap) (since 6.1.1)
getMyTasks (int filterId, int pageSize, int pageNumber, List fields, HashMap sortMap) (since 6.2)

Parameters

  • filterId The filterId to apply when returning the tasks.
  • pageSize The maximum number of tasks that can be returned per query
  • pageNumber In situations where there are more tasks than can fit on a page size, this number specifies the next set of tasks to be retrieved.
  • fields Specifies the field data whose values will be retrieved from the task.
  • sortMap Specifies the fields on which to sort the retrieved tasks.

Description

Retrieves a list of tasks based on the data sent to the web-service function. The returned HashMap contains a success flag and the values for the keys of the given fields.

Requests will be sorted by their ID in ascending order if no sortMap is defined. The sortMap accepts all the above fields as keys. Acceptable values include:

ASC – perform an ascending sort on the field
DESC – perform a descending sort on the field

Key Description
customer Customers full name
orgUnit Organizational Unit display name
item Item number
status Status name
classification Classification
impact Impact name
urgency Urgency name
priorityType Priority name
team Team name
type Process type (since 6.1.4)
status status name
dateCreated Request creation date (MM/dd/yyyy HH:mm)
dateClosed Request closed date (MM/dd/yyyy HH:mm)
dateDue Request due date (MM/dd/yyyy HH:mm)
lastUpdated Date request was last updated (MM/dd/yyyy HH:mm)
subject Request subject
description Request description
custom1…custom5 Request custom fields
typeCustom1…typeCustom5 Item type custom fields

23. Get Attachments (prior to v8.5)

getAttachments (String requestId) (v6.5 - v8.1)

Parameters

  • requestId Get Attachments for this request id

Description

This returns a list of attachments for the defined requestId as a Name/URL as a key/value pair. As long as the session is valid you can then stream the file directly to the client using the specified URL.

24. Get Attachments (v8.5 and beyond)

getAttachments (String requestId) (since v8.5)

Parameters

  • requestId Get Attachments for this request id

Description

This returns a Map of attachment definition objects for each attachment attached to the request specified. This new implementation supersedes the previous implementation as of v8.5 as the previous results could yield non-unique entries and essentially skip results. The returned Map contains keys of attachment id’s, and the value is a child map. The structure of this child map is as follows:

Key Description
name Attachment Filename
size Attachment File size
description The description of the attachment as defined in the service desk
isHidden String “true” or “false” to denote if the attachment is private
attachmentType The attachment type label
url The download URL for this attachment. If used appropriately, this link can be used to download the attachment (provided the session is correctly managed).
uploadDateTime When the attachment was uploaded to the service desk