Problems API

List problems
Get a single problem
Create a problem
Update a problem
Archive a problem
Trash a problem
Restore a problem
Fields

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.

Predefined Filters

The following predefined filters are available:

/problems/active : List all active problems
/problems/known_errors : List all known_errors problems
/problems/progress_halted : List all progress_halted problems
/problems/solved : List all solved problems
/problems/managed_by_me : List all problems which manager is the API user
/problems/assigned_to_my_team : List all problems that are assigned to one of the teams that the API user is a member of
/problems/assigned_to_me : List all problems that are assigned to the API user

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 .

Filtering

Filtering is available for the following fields :

id source sourceID subject impact service status analysis_target_at solved_at created_at updated_at

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

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,
  "workflow": 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.

This operation can also be used to add a note to the problem. Set copy_note_to_requests to true to copy the content of the note field to the problem’s related requests.

Example

PATCH /problems/:id

{
  "note": "Root cause analysis completed. Please review the workaround and next steps.",
  "copy_note_to_requests": true
}

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

Archive a problem

POST /problems/:id/archive

Moves a given problem to the Archive . This action requires the Account Administrator or Directory Administrator role in the account of the problem.

Response

Status: 200 OK

{
  "archived": "true",
  "analysis_target_at": "...",
  "...": "..."
}

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

Trash a problem

POST /problems/:id/trash

Moves a given problem to the Trash . This action requires the Account Administrator or Directory Administrator role in the account of the problem.

Response

Status: 200 OK

{
  "trashed": "true",
  "analysis_target_at": "...",
  "...": "..."
}

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

Restore a problem

POST /problems/:id/restore

Moves a given problem from the Archive or the Trash back into the view of “Solved Problems”. This action requires the Account Administrator or Directory Administrator role in the account of the problem.

Response

Status: 200 OK

{
  "analysis_target_at": "...",
  "...": "..."
}

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

Fields

agile_board

Optional reference to Agile Board

The Agile board on which the problem is placed.

agile_board_column

Optional reference to Agile Board Column

The column of the agile board on which the problem is placed.

agile_board_column_position

Optional integer

The Position field is used to specify the position of the problem, relative to the other items within the column of the agile board. The topmost item has position 1.

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

Use Problems - Notes API to get note 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

created_at

Readonly datetime

The date and time at which the problem was created.

copy_note_to_requests

Optional boolean , default: false

Set to the value true to copy the content of the note field to the problem’s related requests when the problem is updated.

This field is available only in PATCH /problems/:id requests.

custom_fields

Optional custom fields

Custom fields provided in JSON format by the UI Extension that is linked to the problem.

custom_fields_attachments

Writeonly attachments The attachments used in Custom fields.

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 .

note_attachments

Writeonly attachments The attachments used in the Note field.

planned_effort

Optional integer (max 600000)

The Planned effort field is used to specify the number of minutes the member is expected to spend working on the problem.

product_backlog

Optional reference to Product Backlog

The Product backlog field is used to place the problem on a product backlog. When a problem is placed on a product backlog without specifying a product_backlog_position it is placed at the bottom of the product backlog.

product_backlog_position

Optional integer

The Product backlog position field is used to determine the relative position of the problem on the product backlog (the top most item has position 1). When a problem is placed on a product backlog without specifying a product_backlog_position it is placed at the bottom of the product backlog.

project

Optional reference to Project

The Project field is used to link the problem to a project.

resolution_duration

Readonly integer

The number of minutes it took to complete this problem, which is calculated as the difference between the created_at and solved_at values.

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
workflow_pending : Workflow Pending
on_backlog : On Backlog
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.

time_spent

Optional integer

The Time spent field is used to enter the time that you have spent working on the problem since you started to work on it or, if you already entered some time for this problem, since you last added your time spent in it.

This field cannot be specified in the ?fields= parameter .

time_spent_effort_class

Optional reference to Effort Class

The Effort class field is used to select the effort class that best reflects the type of effort for which time spent is being registered.

This field cannot be specified in the ?fields= parameter .

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.

workaround_attachments

Writeonly attachments The inline attachments used in the Workaround field.

workflow

Optional reference to Workflow

The Workflow field is used to relate the problem to the Workflow that will implement the proposed permanent solution for the problem.