Request Templates API

List request templates

List all request templates for an account:

GET /request_templates

Response

Status: 200 OK
[
  {
    "created_at": "2016-03-14T03:13:49-06:00",
    "category": "rfi",
    "sourceID": null,
    "updated_at": "2016-03-14T03:13:49-06:00",
    "service": {
      "name": "Warehouse Management",
      "id": 32,
      "provider": {
        "name": "Widget Data Center, External IT",
        "id": 30
      }
    },
    "subject": "Request for information concerning the Warehouse Management service",
    "id": 118,
    "impact": null,
    "disabled": false
  },
  "..."
]

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of request templates.

States

The following states are available:

Collection Fields

By default the following fields will appear in collections of request templates:

id sourceID subject category impact service created_at updated_at

Obtain a different set of fields using the ?fields= parameter.

Sorting

By default a collection of request templates is sorted descending by id.

The following fields are accepted by the ?sort= parameter:

id sourceID subject category impact service created_at updated_at times_applied

Get a single request template

GET /request_templates/:id

Response

Status: 200 OK
{
  "completion_reason": null,
  "created_at": "2014-12-14T03:13:48-06:00",
  "category": "complaint",
  "support_hours": null,
  "sourceID": null,
  "change_template": null,
  "change_manager": null,
  "copy_subject_to_requests": true,
  "self_service": true,
  "service_hierarchy_browser": true,
  "updated_at": "2014-12-14T03:13:48-06:00",
  "desired_completion": null,
  "supplier": null,
  "service": null,
  "member": {
    "name": "Khunal Shrestra",
    "account": {
      "name": "VirtualSupport",
      "id": "virtualsupport"
    },
    "id": 2
  },
  "asset_selection": false,
  "assign_to_self": false,
  "subject": "Complaint",
  "localized_subject": "Complaint",
  "id": 30,
  "times_applied": 1,
  "resolution_target": null,
  "ci": null,
  "note": null,
  "time_zone": null,
  "impact": null,
  "disabled": false,
  "team": {
    "name": "Service Desk",
    "account": {
      "name": "VirtualSupport",
      "id": "virtualsupport"
    },
    "id": 2
  },
  "status": null,
  "source": null,
  "registration_hints": "Explain in the Note field the reason for the dissatisfaction with the support provided by Widget Data Center.",
  "localized_registration_hints": "Explain in the Note field the reason for the dissatisfaction with the support provided by Widget Data Center.",
  "instructions": "Explain to the user that this request will be assigned to Widget Data Center's service desk manager.",
  "ui_extension": null,
  "urgent": false
}

The response contains these fields.

Create a request template

POST /request_templates

When creating a new request template these fields are available.

Response

Status: 201 Created
{
  "assign_to_self": "...",
  "...": "..."
}

The response contains all fields of the created request template and is similar to the response in Get a single request template

Update a request template

PATCH /request_templates/:id

When updating a request template these fields are available.

Response

Status: 200 OK
{
  "assign_to_self": "...",
  "...": "..."
}

The response contains all fields of the updated request template and is similar to the response in Get a single request template

Fields

asset_selection
Optional boolean, default: false — The Asset Selection box is checked when, after selecting the request template in Self Service, the user needs to be able to select a configuration item in the Asset field..
assign_to_self
Optional boolean, default: false — The Assign to self box is checked to ensure that the person who is registering a new request based on the template is selected in its Member field.
category
Optional enum — The Category field is used to select the category that needs to be selected in the Category field of a new request when it is being created based on the template. Valid values are:
  • incident: Incident - Request for Incident Resolution
  • rfc: RFC - Request for Change
  • rfi: RFI - Request for Information
  • complaint: Complaint - Request for Support Improvement
  • compliment: Compliment - Request for Bestowal of Praise
  • other: Other - Request is Out of Scope
change_manager
Optional reference to Person — The Change manager field is used to relate a Change Manager to the request template. Required when a Change Template is defined, and the Service does not define a Change Manager.
change_template
Optional reference to Change Template — The Change template field is used to relate a Change Template to the request template. Required when the Status is set to Change Pending.
ci
Optional reference to Configuration Item — The Configuration item field is used to select the CI that needs to be copied to the Configuration item field of a new request when it is being created based on the template.
completion_reason
Optional enum — The Completion reason field is used to select the completion reason that needs to be selected in the Completion reason field of a new request when it is being created based on the template. Valid values are:
  • solved: Solved - Root Cause Analysis Not Required
  • workaround: Workaround - Root Cause Not Removed
  • gone: Gone - Unable to Reproduce
  • withdrawn: Withdrawn - Withdrawn by Requester
  • conflict: Conflict - In Conflict with Internal Standard or Policy
  • unsolvable: Unsolvable - Unable to Solve
copy_subject_to_request
Optional boolean, default: true — The Copy subject to requests box is checked when the subject of the request template needs to become the subject of a request when the template is applied, provided that the Subject field of this request is empty.
created_at
Readonly datetime — The date and time at which the request template was created.
desired_completion
Optional integer — The Desired completion field is used to enter the number of hours and minutes within which requests that are based on the request template are to be resolved.
disabled
Optional boolean, default: false — The Disabled box is checked when the request template may not be used to help register new requests.
id
Readonly integer — The unique ID of the request template.
impact
Optional enum — The Impact field is used to select the impact level that needs to be selected in the Impact field of a new request when it is being created based on the template. Valid values are:
  • low: Low - Service Degraded for One User
  • medium: Medium - Service Down for One User
  • high: High - Service Degraded for Several Users
  • top: Top - Service Down for Several Users
instructions
Optional text (max 64KB) — The Instructions field is used to enter instructions for the support staff who will work on requests that are based on the template.
localized_note
Readonly text (max 64KB) — Translated Note in the current language, defaults to note in case no translation is provided.
localized_registration_hints
Readonly text (max 64KB) — Translated Registration hints in the current language, defaults to registration_hints in case no translation is provided.
localized_subject
Readonly string (max 255) — Translated Subject in the current language, defaults to subject in case no translation is provided.
member
Optional reference to Person — The Member field is used to select the Person who should be selected in the Member field of a new request when it is being created based on the template.
note
Optional text (max 64KB) — The Note field is used to enter the information that needs to be copied to the Note field of a new request when it is being created based on the template.
registration_hints
Optional text (max 64KB) — The Registration hints field is used to enter the information that needs to be displayed after the template has been applied to a new or existing request. This field typically contains step-by-step instructions about how to complete the registration of a request that is based on the template.
self_service
Optional boolean, default: true — The Self Service box is checked when the request template is shown in Self Service.
service
Optional reference to Service — The Service field is used to select the Service for which the request template is made available.
service_hierarchy_browser
Optional boolean, default: true — The Service Hierarchy Browser box is checked when the request template is shown in the Service Hierarchy Browser.
source
Optional string (max 30) - See source
sourceID
Optional string (max 128) - See source
status
Optional enum — The Status field is used to select the status value that needs to be selected in the Status field of a new request when it is being created based on the template. Valid values are:
  • declined: Declined
  • assigned: Assigned
  • accepted: Accepted
  • in_progress: In Progress
  • waiting_for: Waiting for…
  • waiting_for_customer: Waiting for Customer
  • change_pending: Change Pending
  • completed: Completed
subject
Required string (max 255) — The Subject field is used to enter a short description that needs to be copied to the Subject field of a new Request when it is being created based on the template.
supplier
Optional reference to Organization — The Supplier field is used to select the supplier organization that should be selected in the Supplier field of a new request when it is being created based on the template.
support_hours
Optional reference to Calendar — The Support hours field is used to select a calendar that is to be used to calculate the desired completion for requests that are based on the request template.
team
Optional reference to Team — The Team field is used to select the Team that should be selected in the Team field of a new request when it is being created based on the template.
time_zone
Optional string (max 50) — The Time zone field is used to select the time zone that applies to the selected support hours.
times_applied
Readonly integer — The number of times the request template is used to create a Request.
ui_extension
Optional reference to UI Extension — The UI extension field is used to select the UI extension that is to be added to a new request when it is being created based on the template.
updated_at
Readonly datetime — The date and time of the last update of the request template. If the request template has no updates it contains the created_at value.
urgent
Optional boolean, default: false — The Mark as urgent box is checked when a new request that is created based on the template is to be marked as urgent.