Service Level Agreements API

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:

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 Account
  • organizations_and_descendants: People of the Following Organization(s) and Their Descendants
  • organizations: People of the Following Organization(s)
  • sites: People of the Following Site(s)
  • organizations_and_sites: People of an Organization and Site from the Following
  • people: People Selected Below
  • cis_of_service_instance: People Using CIs of the Service Instance
  • service_instances: Members of Support Teams of the Following Service Instances
  • skill_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 Prepared
  • scheduled_for_activation: Scheduled for Activation
  • active: Active
  • expired: 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.