createIncident (String itemNumber, String classificationId, String subject, String description, HashMap customFieldValues)
createChangeRequest (String itemNumber, String classificationId, String subject, String description, HashMap customFieldValues)
createServiceRequest (String itemNumber, String classificationId, String subject, String description, HashMap customFieldValues)
This API is used 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 following are the input parameters for this API:
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.
NOTE:All three arguments (‘itemNumber,’ ‘classificationNumber’ and ‘Description’) are required. Omitting any of the three will result in failure and a message explaining the circumstances.
This API 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 (that is the success field is true), the value returned i the message field will be a String representation of the new Request’s ID number.If the process fails for any reason (that is. the success field is false), the message field will contain a text message explaining why the failure occurred.
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)
createChangeRequestCustomer (String customerId, String itemNumber, String classificationId, String subject, String description, HashMap customFieldValues)
createServiceRequestCustomer (String customerId, String itemNumber, String classificationId, String subject, String description, HashMap customFieldValues)
This API is used 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 Request to be successfully created.
The following are the input parameters for this API:
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. The closingTechId if set will be used in conjunction with the closeDate to set the technician to credit for the closure.
NOTE:All four arguments (‘customerId’, ‘itemNumber,’ ‘classificationNumber’ and ‘Description’) are required.
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.
This API 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 (that is the success field is true), the value returned i the message field will be a String representation of the new Incidents’s ID number.
If the process fails for any reason (that is. the success field is false), the message field will contain a text message explaining why the failure occurred.
getClassifications (String itemNumber)
This API returns a list of all the classifications that exist in the system for the selected item type.
The following are the input parameters for this API:
itemNumber: The unique ItemNumber to retrieve classifications from.
This API returns a HashMap that contains the list of Classification IDs as field names. Each field has a String value containing the name of the Classification. In Service Desk, 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.
getSubject (String requestId)
This API returns a HashMap containing the ‘subject’ for the provided Request ID.
The following are the input parameters for this API:
requestId: The unique id of the request to retrieve subject from.
None
getDescription (String requestId)
This API returns a HashMap containing the ‘description’ for the provided Request ID.
The following are the input parameters for this API:
requestId: The unique of the request to retrieve description from.
None
getRequestCountByStatus (String statusId)
This API returns a HashMap containing the ‘requestCount’ for the provided Status ID.
The following are the input parameters for this API:
statusId: The id of the status to retrieve the request count for. This is the a synonym for the workflow status.
None
getRequestsByStatus (String statusId, String pageNo)
This API 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.
The following are the input parameters for this API:
statusId: The id of the status to return requests against.
pageNo: The page number to retrieve. These are returned 100 requests at a time.
None
getRequestDetail (String requestId)
This API 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 following are the input parameters for this API:
requestId: The unique request Id of the request to return details from.
The API returns a 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. |
|
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. |
|
itemCriticality |
Configuration Item criticality. |
|
status |
Request status |
|
statusId |
Request status ID |
|
statusEntry |
If the request is at an entry state of the workflow |
|
statusExit |
If the request is at an exit state of the workflow |
|
statusIsApproval |
If the request is in an approval status state on the workflow |
|
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 |
|
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 |
|
workflow |
The current workflow |
|
workflowId |
The current workflow Id |
|
editable |
If the request is editable by the current user based on team membership and other permissions |
getPublicNotes (String requestId)
This API returns a list of all the public Notes for a given requestId. The returned HashMap contains the Note ID and Note Date.
The following are the input parameters for this API:
requestId: The unique Request Id from which to retrieve notes.
None
getNotes (String requestId)
This API returns a list of all the Notes for a given requestId. The returned HashMap contains the Note ID and Note Date.
The following are the input parameters for this API:
requestId: The unique Request Id from which to retrieve notes.
None
getNotesDetail (String requestId, int pageSize, int pageNumber)
This API 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.
The following are the input parameters for this API:
requestId: The unique Request Id from which to retrieve notes.
pageSize: The number of elements to return for each page.
pageNumber: The page number to retrieve with given pageSize.
None
getNoteContent (String requestId, String noteId)
This API returns the content of the Note for the provided Request ID and Note ID.
The following are the input parameters for this API:
requestId: The unique Request Id from which to retrieve note content.
noteId: The note id to retrieve.
None
updateRequest (String requestId, HashMap fieldValues)
This API is used to update a request of any type (Incident, Change Request or Service Request).
The following are the input parameters for this API:
requestId: The Request Id to be updated
fieldValues: The 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.
This API returns a HashMap containing a success flag to deal with Requests that can not be processed for various reasons, along with a message to state the reason.
findIncident (String itemNumber, String classificationId, HashMap fieldValues)
findChangeRequest (String itemNumber, String classificationId, HashMap fieldValues)
findServiceRequest (String itemNumber, String classificationId, HashMap fieldValues)
This API is used 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 following are the input parameters for this API:
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. Takes the same keys as updateRequestDetail.
This API returns a HashMap containing the success flag and a message.
addNoteToRequest (String requestId, String note)
addNoteToRequest (String requestId, String note, String privateNdx)
addNoteToRequest (String requestId, String note, String privateNdx, String timeMins)
This API is used to add a note to a request by members of the assigned team, or the customer of the request. 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.
The following are the input parameters for this API:
requestId: The requestId to add the note to.
note: The note contents.
priateNdx: 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.
This API returns a HashMap containing 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.
closeRequest (String requestId, String reason)
This API is used to set the Request 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 following are the input parameters for this API:
requestId: The request Id to be closed.
reason: The reason for closing this request.
This API returns a HashMap containing the success flag and a reason field.
getResponseTemplates (String requestId)
This API returns a list of valid response templates for this request.
The following are the input parameters for this API:
requestId: The request Id to retrieve the response templates for.
This API 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.
getResponseTemplateContent (String responseId)
This API returns the actual contents of a response template by ID.
The following are the input parameters for this API:
responseId: The response Id of the template to retrieve.
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 using the rich text editor.
getMyFilters ()
This API returns a list of Filters by Id and name for the current logged in user.
None
This API returns a HashMap containing the filter Id as the key and filter name as the value.
getMyTaskCount ()
getMyTaskCount (int filterId)
This API retrieves the number of currently active and assigned tasks to the current logged in user. If a filterId is passed in then it will return the number of requests with the given filter applied.
The following are the input parameters for this API:
filterId: The unique filter Id to use to return the number of requests available with that filter.
This API returns a HashMap containing a success flag and the number of tasks.
getMyTasks (int pageSize, int pageNumber, List fields, HashMap sortMap)
getMyTasks (int filterId, int pageSize, int pageNumber, List fields, HashMap sortMap)
This API 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 |
|
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 |
The following are the input parameters for this API:
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.
This API returns a HashMap containing a success flag and the number of tasks.
getAttachments (String requestId)
This API retrieves 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.
The following are the input parameters for this API:
requestId: The request Id for which attachments have to be got.
None
getIncidentStates ()
This API returns all Workflow States allowed for Incidents in a HashMap, keyed on ID and name formatted as ‘workflow – state name’.
None
None
getProblemStates ()
This API returns all Workflow States allowed for Problems in a HashMap, keyed on ID and name formatted as ‘workflow – state name’.
None
None
getChangeRequestStates ()
This API returns all Workflow States allowed for Change Requests in a HashMap, keyed on ID and name formatted as ‘workflow – state name’.
None
None
getServiceRequestStates ()
This API returns all Workflow States allowed for Service Requests in a HashMap, keyed on ID and name formatted as ‘workflow – state name’.
None
None
getNextStates (String requestId)
This API returns the next available Workflow States allowed for the identified request in a HashMap, keyed on ID and name formatted as ‘state name’.
The following are the input parameters for this API:
requestId: The request Id for which attachments have to be got.
None