Service Level Agreements API
- List service level agreements
- Get a single service level agreement
- Create a service level agreement
- Update a service level agreement
- Fields
List service level agreements
List all service level agreements for an account:
GET /slas
Response
Status: 200 OK
[
{
"name": "BlackBerry Standard Smart Phone for Widget Data Center, External IT",
"created_at": "2016-03-14T03:10:46-06:00",
"sourceID": null,
"updated_at": "2016-03-14T03:10:46-06:00",
"account": {
"name": "Widget North America",
"id": "wna"
},
"id": 145,
"service_offering": {
"name": "BlackBerry Standard Smart Phone",
"service": {
"name": "Smart Phone",
"account": {
"name": "Widget North America",
"id": "wna"
},
"id": 45,
"provider": {
"name": "Widget North America, Information Technology",
"account": {
"name": "Widget North America",
"id": "wna"
},
"id": 45
}
},
"account": {
"name": "Widget North America",
"id": "wna"
},
"id": 62
},
"status": "active"
},
{
"name": "BlackBerry Standard Smart Phone for Widget Data Center, Internal IT",
"created_at": "2016-03-14T03:10:46-06:00",
"sourceID": null,
"updated_at": "2016-03-14T03:10:46-06:00",
"account": {
"name": "Widget North America",
"id": "wna"
},
"id": 146,
"service_offering": {
"name": "BlackBerry Standard Smart Phone",
"service": {
"name": "Smart Phone",
"account": {
"name": "Widget North America",
"id": "wna"
},
"id": 45,
"provider": {
"name": "Widget North America, Information Technology",
"account": {
"name": "Widget North America",
"id": "wna"
},
"id": 45
}
},
"account": {
"name": "Widget North America",
"id": "wna"
},
"id": 62
},
"status": "active"
},
"..."
]
The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of service level agreements.
Predefined Filters
The following predefined filters are available:
/slas/active
: List all active service level agreements/slas/inactive
: List all inactive service level agreements
Collection Fields
By default the following fields will appear in collections of service level agreements:
service_offering
id
sourceID
name
status
created_at
updated_at
Obtain a different set of fields using the ?fields= parameter.
Filtering
Filtering is available for the following fields:
id
source
sourceID
name
status
created_at
updated_at
service_offering
service_instance
Sorting
By default a collection of service level agreements is sorted ascending by name
.
The following fields are accepted by the ?sort= parameter:
service_offering
id
sourceID
name
status
created_at
updated_at
Get a single service level agreement
GET /slas/:id
Response
Status: 200 OK
{
"start_date": "2016-03-03",
"service_instance": {
"name": "ITRP Production",
"account": {
"name": "ITRP Institute",
"id": "itrp"
},
"id": 1
},
"name": "Premium Plus IT Resource Planning (ITRP) for Widget Data Center",
"remarks": null,
"notice_date": null,
"created_at": "2016-03-14T03:10:43-06:00",
"coverage": "service_instances",
"sourceID": null,
"updated_at": "2016-03-14T03:10:43-06:00",
"account": {
"name": "ITRP Institute",
"id": "itrp"
},
"id": 5,
"expiry_date": null,
"service_offering": {
"name": "Premium Plus IT Resource Planning (ITRP)",
"service": {
"name": "IT Resource Planning (ITRP)",
"account": {
"name": "ITRP Institute",
"id": "itrp"
},
"id": 1,
"provider": {
"name": "ITRP Institute, Inc.",
"account": {
"name": "ITRP Institute",
"id": "itrp"
},
"id": 1
}
},
"account": {
"name": "ITRP Institute",
"id": "itrp"
},
"id": 4
},
"customer_rep": {
"name": "Howard Tanner",
"id": 5
},
"customer": {
"name": "Widget Data Center, External IT",
"id": 30
},
"status": "active",
"source": null,
"service_level_manager": {
"name": "Frederieke Winkler Prins",
"account": {
"name": "ITRP Institute",
"id": "itrp"
},
"id": 9
}
}
The response contains these fields.
Create a service level agreement
POST /slas
When creating a new service level agreement these fields are available.
Response
Status: 201 Created
{
"coverage": "...",
"...": "..."
}
The response contains all fields of the created service level agreement and is similar to the response in Get a single service level agreement
Update a service level agreement
PATCH /slas/:id
When updating a service level agreement these fields are available.
Response
Status: 200 OK
{
"coverage": "...",
"...": "..."
}
The response contains all fields of the updated service level agreement and is similar to the response in Get a single service level agreement
Fields
- activityID_low
- Optional string — Represents the activityID for low incidents. The Activity ID is the unique identifier by which an activity that is performed in the context of a service offering is known in the billing system of the service provider.
- activityID_medium
- Optional string — Represents the activityID for medium incidents. The Activity ID is the unique identifier by which an activity that is performed in the context of a service offering is known in the billing system of the service provider.
- activityID_high
- Optional string — Represents the activityID for high incidents. The Activity ID is the unique identifier by which an activity that is performed in the context of a service offering is known in the billing system of the service provider.
- activityID_top
- Optional string — Represents the activityID for top incidents. The Activity ID is the unique identifier by which an activity that is performed in the context of a service offering is known in the billing system of the service provider.
- activityID_rfc
- Optional string — Represents the activityID for RFCs. The Activity ID is the unique identifier by which an activity that is performed in the context of a service offering is known in the billing system of the service provider.
- activityID_rfi
- Optional string — Represents the activityID for RFIs. The Activity ID is the unique identifier by which an activity that is performed in the context of a service offering is known in the billing system of the service provider.
- activityID_case
- Optional string — Represents the activityID for case. The Activity ID is the unique identifier by which an activity that is performed in the context of a service offering is known in the billing system of the service provider.
- agreementID
- Optional string — The Agreement ID is the unique identifier by which all the activities that are performed through the coverage of the SLA are known in the billing system of the service provider.
- attachments
- Readonly aggregated Attachments
- coverage
- Optional enum — The Coverage field is used to specify how people who are to be covered by the service level agreement are to be selected. Valid values are:
-
customer_account
: All People of Customer Accountorganizations_and_descendants
: People of the Following Organization(s) and Their Descendantsorganizations
: People of the Following Organization(s)sites
: People of the Following Site(s)organizations_and_sites
: People of an Organization and Site from the Followingpeople
: People Selected Belowcis_of_service_instance
: People Using CIs of the Service Instanceservice_instances
: Members of Support Teams of the Following Service Instancesskill_pools
: Members of the Following Skill Pool(s)
- created_at
- Readonly datetime — The date and time at which the service level agreement was created.
- customer
- Required reference to Organization — The Customer field is used to select the Organization that pays for the service level agreement.
- customer_account
- Optional reference to Account — This field is used to specify the Account which service level managers are allowed to update the parts of the SLA that are intended to be maintained by the service level managers of the customer. More importantly, this field is used to specify whether specialists of the customer are allowed to see the requests that include this SLA in their Affected SLAs section.
- customer_rep
- Optional reference to Person — deprecated field containing the first customer representative of the SLA. Please use the specific customer representatives endpoint to retrieve and manipulate the SLA’s customer representatives. When this field is used to update an existing SLA, all customer representatives that are linked to this SLA will be replaced by the new customer representative.
- customer_representative_ids
- Writeonly references to People — This field is used to specify the full list of customer representatives of the SLA. In general, it is preferred to use the specific customer representatives endpoint to retrieve and manipulate the SLA’s customer representatives. However, since it is required to specify at least one customer representative when a SLA is activated, the
customer_representative_ids
field must be used when creating a new, active, SLA. - expiry_date
- Optional date — The Expiry date field is used to specify the date through which the service level agreement (SLA) will be active. The SLA expires at the end of this day if it is not renewed before then. When the SLA has expired, its status will automatically be set to “Expired”.
- id
- Readonly integer — The unique ID of the service level agreement.
- name
- Required string (max 160) — The Name field is used to enter the name of the service level agreement.
- notice_date
- Optional date — The Notice date field is used to specify the last day on which the service provider organization can still be contacted to terminate the service level agreement (SLA) to ensure that it expires on the intended expiry date. The Notice date field is left empty, and the Expiry date field is filled out, when the SLA is to expire on a specific date and no notice needs to be given to terminate it.
- remarks
- Optional text (max 64KB) — The Remarks field is used to add any additional information about the service level agreement that might prove useful.
- remarks_attachments
- Writeonly attachments The attachments used in the Remarks field.
- service_instance
- Optional reference to Service Instance — The Service instance field is used to select the Service Instance that will be used to provide the service to the customer of the service level agreement. Only service instances that are linked to the same service as the selected service offering can be selected.
- service_level_manager
- Optional reference to Person — The Service level manager field is used to select the person of the service provider organization who acts as the service level manager for the customer of the service level agreement.
- service_offering
- Required reference to Service Offering — The Service offering field is used to select the Service Offering that specifies the conditions that apply to the service level agreement.
- source
- Optional string (max 30) - See source
- sourceID
- Optional string (max 128) - See source
- start_date
- Optional date — The Start date field is used to specify the first day during which the service level agreement (SLA) is active.
- status
- Optional enum, default:
being_prepared
— The Status field displays the current status of the service level agreement (SLA). Valid values are: -
being_prepared
: Being Preparedscheduled_for_activation
: Scheduled for Activationactive
: Activeexpired
: Expired
- updated_at
- Readonly datetime — The date and time of the last update of the service level agreement. If the service level agreement has no updates it contains the
created_at
value. - use_knowledge_from_service_provider
- Optional boolean — The Use knowledge from service provider box is checked when the knowledge articles for the service instance that is selected in the Service instance field need to be made available to the people who are covered by an active SLA for the service instances selected in the Service instances table field.