Changes API
- List changes
- Get a single change
- Create a change
- Update a change
- Archive a change
- Trash a change
- Restore a change
- Fields
List changes
List all changes for an account:
GET /changes
Response
Status: 200 OK
[
{
"completed_at": null,
"created_at": "2016-03-10T12:32:00-06:00",
"category": "standard",
"sourceID": null,
"updated_at": "2016-03-14T03:14:17-06:00",
"service": {
"id": 21,
"name": "Email",
"localized_name": "Email",
"provider": {
"name": "Widget Data Center, External IT",
"id": 44,
"account": {
"id": "widget",
"name": "Widget International"
}
}
},
"manager": {
"id": 37,
"name": "Barney Turban",
"account": {
"id": "widget",
"name": "Widget International"
}
},
"subject": "Upgrade Email servers to Exchange Server 2007 SP2",
"id": 1686,
"impact": "top",
"status": "risk_and_impact",
"completion_target_at": "2016-03-15T16:33:00-06:00"
},
"..."
]
The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of changes.
Predefined Filters
The following predefined filters are available:
/changes/completed
: List all completed changes/changes/open
: List all open changes/changes/managed_by_me
: List all changes which manager is the API user
Collection Fields
By default the following fields will appear in collections of changes:
id
sourceID
subject
manager
category
impact
status
completion_target_at
completed_at
service
created_at
updated_at
Obtain a different set of fields using the ?fields= parameter.
Sorting
By default a collection of changes is sorted descending by id
.
The following fields are accepted by the ?sort= parameter:
id
sourceID
subject
manager
category
impact
status
completion_target_at
completed_at
service
created_at
updated_at
Response
The response is similar to the response in List changes
Get a single change
GET /changes/:id
Response
Status: 200 OK
{
"completion_reason": "complete",
"completed_at": "2016-03-14T03:14:13-06:00",
"created_at": "2009-02-03T03:08:00-06:00",
"category": "standard",
"sourceID": null,
"updated_at": "2016-03-14T03:14:13-06:00",
"release": null,
"project": null,
"service": {
"name": "Rack Space",
"id": 26,
"provider": {
"name": "Widget Data Center, External IT",
"id": 44
}
},
"manager": {
"id": 77,
"name": "Carla Cluster",
"account": {
"id": "widget",
"name": "Widget International"
}
},
"subject": "Install new rack",
"start_at": "2016-03-14T09:14:13Z",
"id": 238,
"justification": "expansion",
"impact": "none",
"status": "completed",
"source": "4me",
"change_type": "infrastructure_change",
"completion_target_at": null,
"template": {
"id": 37,
"subject": "Non-standard infrastructure change"
},
"custom_fields": null
}
The response contains these fields.
Create a change
POST /changes
When creating a new change these fields are available.
Response
Status: 201 Created
{
"category": "...",
"...": "..."
}
The response contains all fields of the created change and is similar to the response in Get a single change
Update a change
PATCH /changes/:id
When updating a change these fields are available.
Response
Status: 200 OK
{
"category": "...",
"...": "..."
}
The response contains all fields of the updated change and is similar to the response in Get a single change
Archive a change
POST /changes/:id/archive
Moves a given change to the Archive. This action requires the Account Administrator or Directory Administrator role in the account of the change.
Response
Status: 200 OK
{
"archived": "true",
"analysis_target_at": "...",
"...": "..."
}
The response contains all fields of the archived change and is similar to the response in Get a single change
Trash a change
POST /changes/:id/trash
Moves a given change to the Trash. This action requires the Account Administrator or Directory Administrator role in the account of the change.
Response
Status: 200 OK
{
"trashed": "true",
"analysis_target_at": "...",
"...": "..."
}
The response contains all fields of the archived change and is similar to the response in Get a single change
Restore a change
POST /changes/:id/restore
Moves a given change from the Archive or the Trash back into the view of “Completed Changes”. This action requires the Account Administrator or Directory Administrator role in the account of the change.
Response
Status: 200 OK
{
"analysis_target_at": "...",
"...": "..."
}
The response contains all fields of the archived change and is similar to the response in Get a single change
Fields
- actual_effort
- Readonly integer — The Actual effort field shows the total time that has already been spent on the change. This is the sum of the time spent on each of the change’s tasks.
- category
- Required enum — The Category field is used to select the category of the change. A change is either planned or unplanned. Select the category “Emergency” for changes that were not planned. Changes that were planned by applying a standard change template are automatically set to the category “Standard”. When a change template is used that is not approved as a standard change, then the option “Non-Standard” is automatically selected in this field. Valid values are:
-
standard
: Standard - Approved Change Template Was Usednon_standard
: Non-Standard - Approved Change Template Not Availableemergency
: Emergency - Required for Incident Resolution
- change_type
- Required enum — The Type field is used to indicate whether the change needs to be implemented following the procedure steps for application changes or for infrastructure changes. Valid values are:
-
application_change
: Application Changeinfrastructure_change
: Infrastructure Change
- completed_at
- Readonly datetime — The Completed at field is automatically set to the date and time at which the change is saved with the status “Completed”.
- completion_reason
- Optional enum — The Completion reason field is used to select the appropriate completion reason for the change when it has been completed. It is automatically set to “Complete” when all tasks related to the change have reached the status “Completed”, “Approved” or “Canceled”. Valid values are:
-
withdrawn
: Withdrawn - Withdrawn by Requesterrejected
: Rejected - Rejected by Approverrolled_back
: Rolled Back - Original Environment Restoredfailed
: Failed - No Requirements Metpartial
: Partial - Not All Requirements Metdisruptive
: Disruptive - Caused Service Disruptioncomplete
: Complete - All Requirements Met
- completion_target_at
- Readonly datetime — The Completion target field shows the target date and time of the last task of the change.
- created_at
- Readonly datetime — The date and time at which the change was created.
- custom_fields
- Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the related change template.
- effort_indication
- Readonly integer — The Effort indication field shows the difference between the planned effort and the sum of the actual effort plus the remaining effort as a percentage of the planned effort.
- id
- Readonly integer — The unique ID of the change.
- impact
- Readonly enum, default:
none
— The Impact field shows the maximum impact level that is selected in the tasks that are a part of the change. This indicates the maximum extent to which the service is impacted when the implementation tasks that are related to the change are executed. Valid values are: -
none
: None - Service Not Degradedlow
: Low - Service Degraded for One Usermedium
: Medium - Service Down for One Userhigh
: High - Service Degraded for Several Userstop
: Top - Service Down for Several Users
- justification
- Required enum — The Justification field is used to select the reason why the change was requested. Valid values are:
-
compliance
: Compliancecorrection
: Correctionexpansion
: Expansionimprovement
: Improvementmaintenance
: Maintenancemove
: Moveremoval
: Removalreplacement
: Replacement
- manager
- Required reference to Person — The Manager field is used to select the Person who is responsible for coordinating the implementation of the change. If a manager is not specified for a new change, the API user is selected in the Manager field by default.
- note
- Optional text (max 64KB) — The Note field is used to provide a high-level description of the result that should be accomplished by the implementation of the change. It is also used to add any information that could prove useful for anyone affected by the change, including the people whose approval is needed and the specialists who are helping to implement it.
-
The Note field cannot be specified in the ?fields= parameter.
- note_attachments
- Writeonly attachments The attachments used in the Note field.
- planned_effort
- Readonly integer — The Planned effort field shows the total planned effort of the change. This is the sum of the planned effort (or planned duration if the planned effort is empty) of the change’s tasks.
- project
- Optional reference to Project — The Project field is used to link the change to a project.
- release
- Optional reference to Release — The Release field is used to select the release that the change is a part of.
- remaining_effort
- Readonly integer — The Remaining effort field shows the total amount of effort that is still planned to be spent on the change. This is determined by calculating for each of the change’s tasks the remaining effort. The remaining effort for a task is calculated by subtracting the total time spent on the task from its planned effort (or planned duration if the planned effort is empty). The result of this calculation cannot be lower than zero. The tasks that have already reached their final status are excluded.
- service
- Required reference to Service — The Service field is used to select the Service that will directly be affected by the change implementation, or in case of an emergency change, the service that was directly affected by the change implementation.
- source
- Optional string (max 30) - See source
- sourceID
- Optional string (max 128) - See source
- start_at
- Optional datetime — The Start at field is used to specify the date and time at which the Status field of the first tasks of the change will automatically be set to “Assigned”.
- status
- Optional enum, default:
registered
— The Status field is automatically set based on the status of the change’s tasks. Valid values are: -
being_created
: Being Createdregistered
: Registeredrisk_and_impact
: Risk & Impactapproval
: Approvalimplementation
: Implementationprogress_halted
: Progress Haltedcompleted
: Completed
- subject
- Required string (max 255) — The Subject field is used to enter a short description of the objective of the change.
- template
- Required reference to Change Template — The Template field contains the link to the change template that was used to register the change.
- updated_at
- Readonly datetime — The date and time of the last update of the change. If the change has no updates it contains the
created_at
value.