Problems API

List problems

List all problems for an account:

GET /problems

Response

Status: 200 OK
[
  {
    "created_at": "2016-03-13T10:27:00-06:00",
    "analysis_target_at": "2016-03-20T03:00:00-06:00",
    "sourceID": null,
    "updated_at": "2016-03-14T03:14:13-06:00",
    "service": {
      "name": "Expense Reporting",
      "id": 14,
      "provider": {
        "name": "Widget Data Center, External IT",
        "id": 30
      }
    },
    "member": {
      "name": "Tom Waters",
      "id": 36
    },
    "solved_at": null,
    "subject": "Clicking on the Submit button does not submit new expense report",
    "id": 221,
    "impact": "top",
    "team": {
      "name": "Application Development",
      "id": 7
    },
    "status": "in_progress"
  },
  "..."
]

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

States

The following states are available:

Collection Fields

By default the following fields will appear in collections of problems:

id sourceID subject impact status known_error analysis_target_at solved_at team member service created_at updated_at

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

Sorting

By default a collection of problems is sorted descending by id.

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

id sourceID subject impact status known_error analysis_target_at solved_at team member service created_at updated_at

List problems relevant for API user

List all problems which manager is the API user:

GET /problems/managed_by_me

List all problems that are assigned to one of the teams that the API user is a member of:

GET /problems/assigned_to_my_team

List all problems that are assigned to the API user:

GET /problems/assigned_to_me

Response

The response is similar to the response in List problems

Get a single problem

GET /problems/:id

Response

Status: 200 OK
{
  "created_at": "2016-02-03T14:49:00-05:00",
  "category": "proactive",
  "analysis_target_at": null,
  "sourceID": null,
  "updated_at": "2016-03-14T03:14:12-06:00",
  "supplier": null,
  "service": {
    "name": "Windows Server",
    "id": 33,
    "provider": {
      "name": "Widget Data Center, External IT",
      "id": 30
    }
  },
  "new_assignment": true,
  "known_error": false,
  "solved_at": null,
  "member": {
    "name": "Barney Turban",
    "id": 58
  },
  "manager": {
    "name": "Frank Watson",
    "id": 32
  },
  "supplier_requestID": null,
  "subject": "Insufficient memory warnings for Sales Tracking Production",
  "id": 208,
  "change": null,
  "project": null,
  "knowledge_article": null,
  "workaround": null,
  "impact": "none",
  "team": {
    "name": "Windows Servers",
    "id": 14
  },
  "status": "change_requested",
  "source": null,
  "waiting_until": null
}

The response contains these fields.

Create a problem

POST /problems

When creating a new problem these fields are available.

Response

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

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

Update a problem

PATCH /problems/:id

When updating a problem these fields are available.

Response

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

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

Fields

analysis_target_at
Optional datetime — The Analysis target field is used to specify when the current assignee needs to have completed the root cause analysis of the problem.
attachments
Readonly aggregated Attachments
category
Optional enum, default: reactive — The Category field is used to select the category of the problem. Valid values are:
  • reactive: Reactive - Existing Problem
  • proactive: Proactive - Anticipated Problem
change
Optional reference to Change — The Change field is used to relate the problem to the Change that will implement the proposed permanent solution for the problem.
created_at
Readonly datetime — The date and time at which the problem 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.
id
Readonly integer — The unique ID of the problem.
impact
Required enum — The Impact field is used to select the extent to which the service is impacted when an incident occurs that is caused by the problem. Valid values are:
  • none: None - Does Not Degrade Service
  • low: Low - Degrades Service for One User
  • medium: Medium - Brings Service Down for One User
  • high: High - Degrades Service for Several Users
  • top: Top - Brings Service Down for Several Users
knowledge_article
Optional reference to Knowledge Article — The Knowledge article field is used to select the knowledge article which instructions should be followed to resolve incidents caused by this problem until a structural solution has been implemented.
known_error
Optional boolean — The Known error box is checked when the underlying cause of the problem has been found and a temporary workaround has been proposed.
manager
Required reference to Person — The Manager field is used to select the Person who is responsible for coordinating the problem through root cause analysis, the proposal of a structural solution and ultimately its closure.
member
Optional reference to Person — The Member field is used to select the person to whom the problem is to be assigned.
new_assignment
Readonly boolean — default: true
note
Optional text (max 64KB) — The Note field is used to provide a detailed description of the symptoms that are caused by the problem.

The Note field cannot be specified in the ?fields= parameter.

project
Optional reference to Project — The Project field is used to link the problem to a project.
service
Required reference to Service — The Service field is used to select the service in which instance(s) the problem resides.
solved_at
Readonly datetime — The Solved at field is automatically set to the date and time at which the problem is saved with the status “Solved”.
source
Optional string (max 30) - See source
sourceID
Optional string (max 128) - See source
status
Optional enum, default: assigned — The Status field is used to select the current status of the problem. Valid values are:
  • declined: Declined
  • assigned: Assigned
  • accepted: Accepted
  • in_progress: In Progress
  • waiting_for: Waiting for…
  • analyzed: Analyzed
  • change_requested: Change Requested
  • change_pending: Change Pending
  • project_pending: Project Pending
  • progress_halted: Progress Halted
  • solved: Solved
subject
Required string (max 255) — The Subject field is used to enter a short description of the symptoms that the problem causes.
supplier
Optional reference to Organization — The Supplier field is used to select the supplier organization that has been asked for a solution to the problem.
supplier_requestID
Optional string (max 255)
team
Required reference to Team — The Team field is used to select the Team to which the problem is to be assigned. After a service has been selected in the Service field, the support team of the service is automatically selected in this field.
ui_extension
Readonly reference to UI Extension — The UI extension field indicates the UI extension that is applied to the problem.
updated_at
Readonly datetime — The date and time of the last update of the problem. If the problem has no updates it contains the created_at value.
urgent
Optional boolean, default: false — When the problem has been marked as urgent, the Urgent field is set to true.
waiting_until
Optional datetime — The Waiting until field is used to specify the date and time at which the status of the problem is to be updated from waiting_for to assigned. This field is available only when the Status field is set to waiting_for.
workaround
Optional text (max 64KB) — The Workaround field is used to describe the temporary workaround that should be applied to resolve incidents caused by this problem until a structural solution has been implemented.