Service Instances API

• List service instances
• Get a single service instance
• Create a service instance
• Update a service instance
• Fields

List service instances

List all service instances for an account:

GET /service_instances

Response

Status: 200 OK

[
  {
    "name": "Amsterdam Network",
    "created_at": "2016-03-14T03:10:38-06:00",
    "sourceID": null,
    "updated_at": "2016-03-14T03:10:38-06:00",
    "service": {
      "name": "Network Connectivity",
      "id": 20,
      "provider": {
        "name": "Widget Data Center, External IT",
        "id": 30
      }
    },
    "support_team": {
      "name": "Operations",
      "id": 11
    },
    "id": 23,
    "status": "in_production"
  },
  {
    "name": "AT&T Smart Phone for Widget Data Center, External IT",
    "created_at": "2016-03-14T03:10:39-06:00",
    "sourceID": null,
    "updated_at": "2016-03-14T03:11:39-06:00",
    "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"
    },
    "support_team": {
      "name": "End-User Support, Chicago",
      "account": {
        "name": "Widget North America",
        "id": "wna"
      },
      "id": 16
    },
    "id": 133,
    "status": "in_production"
  },
  "..."
]

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

Predefined Filters

The following predefined filters are available:

• /service_instances/active : List all active service instances
• /service_instances/inactive : List all inactive service instances

Collection Fields

By default the following fields will appear in collections of service instances:

id sourceID name status service support_team 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 service support_team created_at updated_at

Sorting

By default a collection of service instances is sorted ascending by name .

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

id sourceID name status service support_team created_at updated_at

Get a single service instance

GET /service_instances/:id

Response

Status: 200 OK

{
  "name": "ITRP Production",
  "remarks": null,
  "created_at": "2016-03-14T03:10:38-06:00",
  "sourceID": null,
  "updated_at": "2016-03-14T03:10:53-06:00",
  "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"
  },
  "support_team": {
    "name": "Service Desk",
    "account": {
      "name": "ITRP Institute",
      "id": "itrp"
    },
    "id": 1
  },
  "id": 1,
  "status": "in_production",
  "source": null
}

The response contains these fields .

Create a service instance

POST /service_instances

When creating a new service instance these fields are available.

Response

Status: 201 Created

{
  "created_at": "...",
  "...": "..."
}

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

Update a service instance

PATCH /service_instances/:id

When updating a service instance these fields are available.

Response

Status: 200 OK

{
  "created_at": "...",
  "...": "..."
}

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

Fields

attachments

Readonly aggregated Attachments

created_at

Readonly datetime — The date and time at which the service instance was created.

custom_fields

Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the service instance.

custom_fields_attachments

Writeonly attachments The attachments used in Custom fields.

first_line_team

Optional reference to Team — The First line team field is used to select the team that will automatically be selected in the Team field of requests to which the service instance is linked after they have been submitted using Self Service or when they are generated using the Requests API , Mail API or Events API .

id

Readonly integer — The unique ID of the service instance.

impact

Readonly enum — The Impact field shows the impact based on the highest impact of the affected SLAs for which the current user has read access. 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

maintenance_window

Optional reference to Calendar — The Maintenance window field is used to select a Calendar that defines the periods in which workflow tasks with an impact related to this service instance may be implemented.

name

Required string (max 80) — The Name field is used to enter the name of the service instance.

picture_uri

Optional string — The hyperlink to the image file for the service instance.

remarks

Optional text (max 64KB)

remarks_attachments

Writeonly attachments The attachments used in the Remarks field.

service

Required reference to Service — The Service field is used to select the Service which functionality the service instance provides.

source

Optional string (max 30) - See source

sourceID

Optional string (max 128) - See source

status

Optional enum , default: being_prepared — The Status field is used to select the current status of the service instance. Valid values are:

• being_prepared : Being Prepared
• in_production : In Production
• discontinued : Discontinued

support_team

Optional reference to Team — The Support team field is used to select the team that will, by default, be selected in the Team field of a request when the service instance is manually selected in the Service instance field of the request, or when the service instance is applied from the Service Hierarchy Browser.

time_zone

Optional time_zone — The Time zone field is used to select the time zone that applies to the selected maintenance window.

ui_extension

Readonly reference to UI Extension — The UI extension field indicates the UI extension that is applied to the service instance.

updated_at

Readonly datetime — The date and time of the last update of the service instance. If the service instance has no updates it contains the created_at value.