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.

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.