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.

Predefined Filters

The following predefined filters 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.

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.

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.
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.
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.

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.