Class OperationsService

APIs related to integrating Incident and Post-Incident Review (PIR) data with Jira Software. These APIs are available to Atlassian Connect apps. To use these APIs you must have the Operations module in your app's descriptor. Read more about Jira Software modules here.

Module

The Operations module allows third-party providers to add incident and PIR information through a public REST API.

Supplied incident information will be presented in the Incidents page in Jira Software, and as a link to any issues created via the Incidents Page.

This module also provides actions, one which allows Jira to provide a direct link to the operations provider where the user can create a post-incident review and two which allow Jira to search for relevant workspaces and devops components.

Note that the module key and name are not private and therefore should not contain any sensitive or personally identifiable information.

Example Module

An example can also be found at jira-data-provider-sample-addon, which has an atlassian-connect.json.

{
  "modules": {
    "jiraOperationsInfoProvider": {
      "homeUrl": "https://my-operations-provider.com",
      "logoUrl": "https://my-operations-provider.com/images/logo.svg",
      "documentationUrl":
"https://my-operations-provider.com/docs/jira-integration",
      "actions": {
          "fetchWorkspaces": {
              "templateUrl": "/workspaces/list"
          },
          "searchContainers": {
              "templateUrl": "/containers/search"
          },
          "createPostIncidentReview": {
              "url":
"https://my-operations-provider.com/my-workspace/create-post-incident-review?affected-component={component-id}&incident={incident-id}
          }
      },
      "name": {
        "value": "My Operations Provider"
      },
      "key": "operations-integration"
    }
  }
}

Properties

| Property | type | Description

| Required | |------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------|----------| | key | string | A key to identify this module. Must match ^[a-zA-Z0-9-]+$ pattern, with a max length of 100 | Yes | | name | object (i18N) | A human readable name. This object supports internationalization. | Yes | | homeUrl | string | URL to the provider’s homepage

Actions object

| Property | type | Description

| Required | |------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| | fetchWorkspaces | object | An action defined by the provider to allow Jira to retrieve details about operations workspaces via a post endpoint.

| |

See

https://developer.atlassian.com/cloud/jira/software/rest/api-group-operations

Hierarchy

CommonHttpService
- OperationsService

Index

Constructors

constructor

Methods

deleteEntityByProperty deleteIncidentById deleteReviewById deleteWorkspaces getIncidentById getReviewById getWorkspaces submitEntity submitOperationsWorkspaces initialize

Constructors

constructor

new OperationsService(getClientInstance): OperationsService
Internal
Create a new instance of the service.
Parameters
- getClientInstance: (() => CommonHttpClient)
  - - (): CommonHttpClient
    - Returns CommonHttpClient
Returns OperationsService
Inherited from CommonHttpService.constructor

Methods

deleteEntityByProperty

deleteEntityByProperty(params): Promise<void>
Bulk delete all Entties that match the given request.

One or more query params must be supplied to specify Properties to delete by. If more than one Property is provided, data will be deleted that matches ALL of the Properties (e.g. treated as an AND). See the documentation for the submitEntity operation for more details.

e.g. DELETE /bulkByProperties?accountId=account-123&createdBy=user-456

Deletion is performed asynchronously. The getIncidentById operation can be used to confirm that data has been deleted successfully (if needed).

Only Connect apps that define the jiraOperationsInfoProvider module can access this resource. This resource requires the 'DELETE' scope for Connect apps.
Parameters
- params: {
  authorization: string;
  }
  - authorization: string
    All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.
    
    If the JWT token corresponds to an app that does not define Operations Information module it will be rejected with a 403.
    
    See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.
Returns Promise<void>
Path
DELETE /rest/operations/1.0/bulkByProperties

See
https://developer.atlassian.com/cloud/jira/software/rest/api-group-operations#api-rest-operations-1-0-bulkbyproperties-delete

deleteIncidentById

deleteIncidentById(params): Promise<void>
Delete the Incident data currently stored for the given ID.

Deletion is performed asynchronously. The getIncidentById operation can be used to confirm that data has been deleted successfully (if needed).

Only Connect apps that define the jiraOperationsInfoProvider module can access this resource. This resource requires the 'DELETE' scope for Connect apps.
Parameters
- params: {
  authorization: string;
  incidentId: string;
  }
  - authorization: string
    All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.
    
    If the JWT token corresponds to an app that does not define Operations Information module it will be rejected with a 403.
    
    See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.
  - incidentId: string
    The ID of the Incident to delete.
Returns Promise<void>
Path
DELETE /rest/operations/1.0/incidents/{incidentId}

See
https://developer.atlassian.com/cloud/jira/software/rest/api-group-operations#api-rest-operations-1-0-incidents-incidentid-delete

deleteReviewById

deleteReviewById(params): Promise<void>
Delete the Review data currently stored for the given ID.

Deletion is performed asynchronously. The getReviewById operation can be used to confirm that data has been deleted successfully (if needed).

Only Connect apps that define the jiraOperationsInfoProvider module can access this resource. This resource requires the 'DELETE' scope for Connect apps.
Parameters
- params: {
  authorization: string;
  reviewId: string;
  }
  - authorization: string
    All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.
    
    If the JWT token corresponds to an app that does not define Operations Information module it will be rejected with a 403.
    
    See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.
  - reviewId: string
    The ID of the Review to delete.
Returns Promise<void>
Path
DELETE /rest/operations/1.0/post-incident-reviews/{reviewId}

See
https://developer.atlassian.com/cloud/jira/software/rest/api-group-operations#api-rest-operations-1-0-post-incident-reviews-reviewid-delete

deleteWorkspaces

deleteWorkspaces(params): Promise<void>
Bulk delete all Operations Workspaces that match the given request.

Only Connect apps that define the jiraOperationsInfoProvider module can access this resource. This resource requires the 'DELETE' scope for Connect apps.

e.g. DELETE /bulk?workspaceIds=111-222-333,444-555-666
Parameters
- params: {
  authorization: string;
  }
  - authorization: string
    All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.
    
    If the JWT token corresponds to an app that does not define the Operations module it will be rejected with a 403.
    
    See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.
Returns Promise<void>
Path
DELETE /rest/operations/1.0/linkedWorkspaces/bulk

See
https://developer.atlassian.com/cloud/jira/software/rest/api-group-operations#api-rest-operations-1-0-linkedworkspaces-bulk-delete

getIncidentById

getIncidentById(params): Promise<{
    affectedComponents: string[];
    associations?: ({
        associationType?: "issueIdOrKeys" | "serviceIdOrKeys" | "ati:cloud:compass:event-source";
        values?: string[];
    } & {
        [key: string]: unknown;
    })[];
    createdDate: string;
    description: string;
    id: string;
    lastUpdated: string;
    schemaVersion: "1.0";
    severity?: unknown;
    status: "open" | "unknown" | "resolved";
    summary: string;
    updateSequenceNumber: number;
    url: string;
}>
Retrieve the currently stored Incident data for the given ID.

The result will be what is currently stored, ignoring any pending updates or deletes.

Only Connect apps that define the jiraOperationsInfoProvider module can access this resource. This resource requires the 'READ' scope for Connect apps.
Parameters
- params: {
  authorization: string;
  incidentId: string;
  }
  - authorization: string
    All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.
    
    If the JWT token corresponds to an app that does not define Operations Information module it will be rejected with a 403.
    
    See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.
  - incidentId: string
    The ID of the Incident to fetch.
Returns Promise<{
    affectedComponents: string[];
    associations?: ({
        associationType?: "issueIdOrKeys" | "serviceIdOrKeys" | "ati:cloud:compass:event-source";
        values?: string[];
    } & {
        [key: string]: unknown;
    })[];
    createdDate: string;
    description: string;
    id: string;
    lastUpdated: string;
    schemaVersion: "1.0";
    severity?: unknown;
    status: "open" | "unknown" | "resolved";
    summary: string;
    updateSequenceNumber: number;
    url: string;
}>
The Incident data currently stored for the given ID.

Path
GET /rest/operations/1.0/incidents/{incidentId}

See
https://developer.atlassian.com/cloud/jira/software/rest/api-group-operations#api-rest-operations-1-0-incidents-incidentid-get

getReviewById

getReviewById(params): Promise<{
    associations?: ({
        associationType?: "issueIdOrKeys" | "serviceIdOrKeys" | "ati:cloud:compass:event-source";
        values?: string[];
    } & {
        [key: string]: unknown;
    })[];
    createdDate: string;
    description: string;
    id: string;
    lastUpdated: string;
    reviews: string[];
    schemaVersion: "1.0";
    status:
        | "unknown"
        | "completed"
        | "in progress"
        | "outstanding actions";
    summary: string;
    updateSequenceNumber: number;
    url: string;
}>
Retrieve the currently stored Review data for the given ID.

The result will be what is currently stored, ignoring any pending updates or deletes.

Only Connect apps that define the jiraOperationsInfoProvider module can access this resource. This resource requires the 'READ' scope for Connect apps.
Parameters
- params: {
  authorization: string;
  reviewId: string;
  }
  - authorization: string
    All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.
    
    If the JWT token corresponds to an app that does not define Operations Information module it will be rejected with a 403.
    
    See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.
  - reviewId: string
    The ID of the Review to fetch.
Returns Promise<{
    associations?: ({
        associationType?: "issueIdOrKeys" | "serviceIdOrKeys" | "ati:cloud:compass:event-source";
        values?: string[];
    } & {
        [key: string]: unknown;
    })[];
    createdDate: string;
    description: string;
    id: string;
    lastUpdated: string;
    reviews: string[];
    schemaVersion: "1.0";
    status:
        | "unknown"
        | "completed"
        | "in progress"
        | "outstanding actions";
    summary: string;
    updateSequenceNumber: number;
    url: string;
}>
The Review data currently stored for the given ID.

Path
GET /rest/operations/1.0/post-incident-reviews/{reviewId}

See
https://developer.atlassian.com/cloud/jira/software/rest/api-group-operations#api-rest-operations-1-0-post-incident-reviews-reviewid-get

getWorkspaces

getWorkspaces(params): Promise<OperationsWorkspaceIds>
Retrieve the either all Operations Workspace IDs associated with the Jira site or a specific Operations Workspace ID for the given ID.

The result will be what is currently stored, ignoring any pending updates or deletes.

e.g. GET /workspace?workspaceId=111-222-333

Only Connect apps that define the jiraOperationsInfoProvider module can access this resource. This resource requires the 'READ' scope for Connect apps.
Parameters
- params: {
  authorization: string;
  }
  - authorization: string
    All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.
    
    If the JWT token corresponds to an app that does not define the Operations Information module it will be rejected with a 403.
    
    See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.
Returns Promise<OperationsWorkspaceIds>
Either the ID provided if stored or a list of available IDs.

Path
GET /rest/operations/1.0/linkedWorkspaces

See
https://developer.atlassian.com/cloud/jira/software/rest/api-group-operations#api-rest-operations-1-0-linkedworkspaces-get

submitEntity

submitEntity(params): Promise<SubmitIncidentsResponse>
Update / insert Incident or Review data.

Incidents and reviews are identified by their ID, and existing Incident and Review data for the same ID will be replaced if it exists and the updateSequenceNumber of existing data is less than the incoming data.

Submissions are performed asynchronously. Submitted data will eventually be available in Jira; most updates are available within a short period of time, but may take some time during peak load and/or maintenance times. The getIncidentById or getReviewById operation can be used to confirm that data has been stored successfully (if needed).

In the case of multiple Incidents and Reviews being submitted in one request, each is validated individually prior to submission. Details of which entities failed submission (if any) are available in the response object.

A maximum of 1000 incidents can be submitted in one request.

Only Connect apps that define the jiraOperationsInfoProvider module can access this resource. This resource requires the 'WRITE' scope for Connect apps.
Parameters
- params: {
  authorization: string;
  submitIncidentsRequest: SubmitIncidentsRequest;
  }
  - authorization: string
    All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.
    
    If the JWT token corresponds to an app that does not define the Operations Information module it will be rejected with a 403.
    
    See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.
  - submitIncidentsRequest: SubmitIncidentsRequest
    Incident data to submit.
Returns Promise<SubmitIncidentsResponse>
Submission accepted. Each submitted Incident that is of a valid format will be eventually available in Jira.

Details of which Incidents were submitted and which failed submission (due to data format problems etc.) are available in the response object.

Path
POST /rest/operations/1.0/bulk

See
https://developer.atlassian.com/cloud/jira/software/rest/api-group-operations#api-rest-operations-1-0-bulk-post

submitOperationsWorkspaces

submitOperationsWorkspaces(params): Promise<SubmitOperationsWorkspacesResponse>
Insert Operations Workspace IDs to establish a relationship between them and the Jira site the app is installed in. If a relationship between the Workspace ID and Jira already exists then the workspace ID will be ignored and Jira will process the rest of the entries.

Only Connect apps that define the jiraOperationsInfoProvider module can access this resource. This resource requires the 'WRITE' scope for Connect apps.
Parameters
- params: {
  authorization: string;
  submitOperationsWorkspacesRequest: SubmitOperationsWorkspacesRequest;
  }
  - authorization: string
    All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.
    
    If the JWT token corresponds to an app that does not define the Operations module it will be rejected with a 403.
    
    See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.
  - submitOperationsWorkspacesRequest: SubmitOperationsWorkspacesRequest
    Operations Workspace ids to submit.
Returns Promise<SubmitOperationsWorkspacesResponse>
Submission accepted. Each submitted Operations Workspace ID will be linked to Jira.

Path
POST /rest/operations/1.0/linkedWorkspaces/bulk

See
https://developer.atlassian.com/cloud/jira/software/rest/api-group-operations#api-rest-operations-1-0-linkedworkspaces-bulk-post

`Protected` `Static`initialize

initialize(): void
Method to initialize the class. Normally used to set up validation rules.

Returns void
Overrides CommonHttpService.initialize

Class OperationsService

Module

Example Module

Properties

Actions object

See

Hierarchy

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns CommonHttpClient

Returns OperationsService

Methods

deleteEntityByProperty

Parameters

authorization: string

Returns Promise<void>

Path

See

deleteIncidentById

Parameters

authorization: string

incidentId: string

Returns Promise<void>

Path

See

deleteReviewById

Parameters

authorization: string

reviewId: string

Returns Promise<void>

Path

See

deleteWorkspaces

Parameters

authorization: string

Returns Promise<void>

Path

See

getIncidentById

Parameters

authorization: string

incidentId: string

Path

See

getReviewById

Parameters

authorization: string

reviewId: string

Path

See

getWorkspaces

Parameters

authorization: string

Returns Promise<OperationsWorkspaceIds>

Path

See

submitEntity

Parameters

authorization: string

submitIncidentsRequest: SubmitIncidentsRequest

Returns Promise<SubmitIncidentsResponse>

Path

See

submitOperationsWorkspaces

Parameters

authorization: string

submitOperationsWorkspacesRequest: SubmitOperationsWorkspacesRequest

Returns Promise<SubmitOperationsWorkspacesResponse>

Path

See

Protected Staticinitialize

Returns void

Settings

On This Page

`Protected` `Static`initialize