Change Templates API

List change templates

List all change templates for an account:

GET /change_templates

Response

Status: 200 OK
[
  {
    "created_at": "2016-03-14T03:13:47-06:00",
    "sourceID": null,
    "updated_at": "2016-03-14T03:13:47-06:00",
    "service": {
      "name": "Windows Server",
      "id": 33,
      "provider": {
        "name": "Widget Data Center, External IT",
        "id": 30
      }
    },
    "subject": "Windows server hardware upgrade",
    "id": 9,
    "disabled": false
  },
  {
    "created_at": "2016-03-14T03:13:47-06:00",
    "sourceID": null,
    "updated_at": "2016-03-14T03:13:47-06:00",
    "service": {
      "name": "Personal Computing",
      "id": 22,
      "provider": {
        "name": "Widget Data Center, Internal IT",
        "id": 32
      }
    },
    "subject": "Move desktop personal computer",
    "id": 8,
    "disabled": false,
    "recurrence": {
      "start_date": "2016-03-16",
      "day_of_week": true,
      "day_of_week_index": "first",
      "next_occurrence_at": "2016-04-02T02:00:00-05:00",
      "day_of_week_day": "monday",
      "last_occurrence_at": null,
      "id": 1,
      "day": null,
      "time_of_day": "09:00",
      "day_of_month": null,
      "interval": 1,
      "ical": "DTSTART;TZID=CET:20160316T000000\nRRULE:FREQ=YEARLY;BYMONTH=1,4,7,10;BYDAY=1MO",
      "disabled": false,
      "frequency": "yearly",
      "last_occurrence_object": null,
      "month_of_year": [
        1,
        4,
        7,
        10
      ],
      "time_zone": "Amsterdam",
      "end_date": null,
      "last_occurrence_errors": null
    }
  },
  "..."
]

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

States

The following states are available:

Collection Fields

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

id sourceID subject service created_at updated_at

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

Sorting

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

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

id sourceID subject service created_at updated_at times_applied

Get a single change template

GET /change_templates/:id

Response

Status: 200 OK
{
  "created_at": "2016-03-14T03:13:47-06:00",
  "category": "non_standard",
  "sourceID": null,
  "change_manager_id": null,
  "recurrence": null,
  "updated_at": "2016-03-14T03:13:47-06:00",
  "service": null,
  "subject": "Empty change template",
  "id": 1,
  "times_applied": 0,
  "note": null,
  "justification": null,
  "impact": "none",
  "disabled": false,
  "source": null,
  "instructions": "Add tasks to this change to ensure risk and impact analysis is performed, approvals are collected and all implementation steps defined.",
  "change_type": null,
  "ui_extension": null
}

The response contains these fields.

Create a change template

POST /change_templates

When creating a new change template these fields are available.

Response

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

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

Update a change template

PATCH /change_templates/:id

When updating a change template these fields are available.

Response

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

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

Fields

category
Optional enum — The Category field is used to select the category that needs to be selected in the Category field of a new change when it is being created based on the template. Valid values are:
  • standard: Standard - Approved Change Template Was Used
  • non_standard: Non-Standard - Approved Change Template Not Available
  • emergency: Emergency - Required for Incident Resolution
change_manager
Optional reference to Person — The Change manager field is used to select the Person who will be responsible for coordinating the changes that will be generated automatically in accordance with the recurrence schedule.
change_type
Optional enum — The Type field is used to select the type that needs to be selected in the Type field of a new change when it is being created based on the template. Valid values are:
  • application_change: Application Change
  • infrastructure_change: Infrastructure Change
created_at
Readonly datetime — The date and time at which the change template was created.
disabled
Optional boolean, default: false — The Disabled box is checked when the change template may not be used to help register new changes.
id
Readonly integer — The unique ID of the change template.
impact
Readonly enum, default: none — The Impact field shows the maximum impact level that is selected in the task templates that are a part of the change template. Valid values are:
  • none: None - Service Not Degraded
  • 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 the information that needs to be shown when a new change is being created based on the template. This field typically contains instructions about how to register the change.
justification
Optional enum — The Justification field is used to select the justification that needs to be selected in the Justification field of a new change when it is being created based on the template. Valid values are:
  • correction: Correction
  • expansion: Expansion
  • improvement: Improvement
  • maintenance: Maintenance
  • move: Move
  • removal: Removal
  • replacement: Replacement
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 change when it is being created based on the template.
recurrence
Optional aggregated — The recurrence settings hash, missing in case the change template has no recurrency defined. See Recurrence for the fields in the recurrence hash.
service
Optional reference to Service — The Service field is used to select the Service that should be selected in the Service field of a new change when it is being created based on the template.
source
Optional string (max 30) - See source
sourceID
Optional string (max 128) - See source
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 Change when it is being created based on the template.
times_applied
Readonly integer — The number of times the change template is used to create a Change.
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 change when it is being created based on the template.
updated_at
Readonly datetime — The date and time of the last update of the change template. If the change template has no updates it contains the created_at value.

Recurrence

The Recurrence record is aggregated within the change template record in case recurrency is defined for the change template. It consists of the following fields:

id
Readonly integer — The unique ID of the Recurrency.
frequency
Readonly enum, default: no_repeat — The frequency of the recurrency.
  • no_repeat: No Repeat
  • daily: Daily
  • weekly: Weekly
  • monthly: Monthly
  • yearly: Yearly
interval
Required integer, default: 1 — The interval of the Frequency, e.g. every 2nd week or every 10th day.
disabled
Optional boolean, default: false — The Disabled box is recurrency should be temporarily disabled.
time_of_day
Required time of day — The time of day to start the scheduled Change.
time_zone
Required string (max 50) — The Time zone field is used to select the time zone for the time_of_day field.
start_date
Required date — The date at which to start the Recurrence.
end_date
Optional date — The date at which to end the Recurrence.
day
Optional stringRequired when frequency is daily, ignored in all other cases. Comma separated list of days of the week, e.g. 1,2,3,4,5.
  • 0: Sunday
  • 1: Monday
  • 2: Tuesday
  • 3: Wednesday
  • 4: Thursday
  • 5: Friday
  • 6: Saturday
day_of_month
Optional stringRequired when frequency is monthly and day_of_week is false, ignored in all other cases. Comma separated list of days of the month, e.g. 11,21,-1.
  • 1: Day one
  • 2: Day two
  • 3: Day three
  • 30: Day thirty
  • 31: Day thirty-one
  • -1: Last day of month
day_of_week
Required boolean, default: false — Indicates whether or not the day_of_week_index and day_of_week_day values should be considered. Can only be set to true when frequency is monthly or yealy.
day_of_week_index
Optional enum, default: firstRequired when day_of_week is true, ignored in all other cases.
  • first: First
  • second: Second
  • third: Third
  • fourth: Fourth
  • last: Last
day_of_week_day
Optional stringRequired when day_of_week is true, ignored in all other cases. Comma separated list of days of the week, e.g. 1,2,3,4,5.
  • monday: Monday
  • tuesday: Tuesday
  • wednesday: Wednesday
  • thursday: Thursday
  • friday: Friday
  • saturday: Saturday
  • sunday: Sunday
month_of_year
Optional stringRequired when frequency is yearly, ignored in all other cases. Comma separated list of months of the year, e.g. 3,6,9,12.
  • 1: January
  • 2: February
  • 3: March
  • 4: April
  • 5: May
  • 6: June
  • 7: July
  • 8: August
  • 9: September
  • 10: October
  • 11: November
  • 12: December
last_occurrence_at
Readonly datetime — The time and date at which the last Change was created.
last_occurrence_object
Readonly reference to Change — The Change created at during the last occurrence.
last_occurrence_errors
Readonly string (max 1024) — The validation errors during the last occurrence that prevented the Change from being created.
next_occurrence_at
Readonly datetime — The time and date at which the next Change will be created.
ical
Readonly string (max 2048) - The ICAL representation of the recurrency (without time_of_day)