REST API: Integrity Check

On this page:

1 URI structure
2 Step-by-step guide for using the API
- 2.1 Run an integrity check
- 2.2 Track progress
- 2.3 Download the results as .csv
- 2.4 Cancel a running integrity check
- 2.5 Snapshot scope

For details and examples, take a look at the REST API reference:

Documentation for Integrity Check REST API 1.4 - available with CMJ 6.6.6 or later.

URI structure

Integrity Check for Jira’s REST API provides means to run integrity checks, track their progress, and get the results as json/csv. URIs for Integrity Check's REST API resource have the following structure:

http://yourjira.com/jira/rest/integrity-check/api/1.4/integrity

Step-by-step guide for using the API

Run an integrity check

POST /integrity

Use this request to run an integrity check of your Jira configuration.

On Windows, single quotes around JSON code might not work. Try escaping them like so:
“{\"scope\":\"system\"...

Request

Parameter	Type	Description

Parameter

Type

Description

scope

string

Required

Accepted values: "system", "project" or "projectWithIssues".

Examples:

{
  "scope" : "system"
}

or

{
  "scope" : "system",
  "includeAllFilters" : true,
  "includeAllBoards" : true,
  "includeAllDashboards" : true
}

or

{
  "scope": "project",
  "projectKey": "PRJA",
  "includeProjectBoards": false,
  "includeProjectFilters": true
}

curl -u admin:admin -i -H "Content-Type: application/json" -X POST http://localhost:2990/jira/rest/integrity-check/api/1.4/integrity -d '{"scope" : "system"}'

Responses

STATUS 201 - application/json - Returns the id of the operation.
Headers

Location: required(string)
The URI pointing to the started Integrity Check operation. The operation id can be used for getting operation progress, downloading results as .csv, or canceling the operation.

Example:

{
 "id":2
}

STATUS 400 - The value 'exampleValue' is not a valid enumerator of 'SnapshotType'.

Track progress

GET /integrity/{id}

Get the progress or end result of the Integrity Check operation with the given id.

For running operations, the response contains the progress of the operation, which is between 0 and 1, and the operation status.

For completed operations, the response contains an integrityModel property, which includes any integrity violations.

Request

Parameter	Type	Description

Parameter

Type

Description

id

integer

Required

The id of the operation.

curl -u admin:admin -i -H "Content-Type: application/json" -X GET http://localhost:2990/jira/rest/integrity-check/api/1.4/integrity/1

Responses

STATUS 200 - application/json - Returns the status of the progress of the operation.

Example:

{"id":8,"message":"Integrity Check in progress. Checking Filters: 56 of 492.",
"progressMessages":[...],"progressDouble":0.4227642276422765,"status":"Running"}

or

{"id":14,"integrityModel":{"maxSeverity":"Warning","containsUnknownErrors":false,
"objectCount":227,"hasValidLicense":false,"quickfixablePathsCount":0},
"message":"Integrity check succeeded","progressDouble":1.0,"status":"Succeeded"}

or

{integrityModel={objectCount=914, hasValidLicense=false, 
violations=[{severity=Warning, solution=Modify the objects to point to an existing project or remove the reference to the missing project., 
paths=[{elements=[{name=Engineering Stories Sprint 16 (mwoodbu), id=null, type=Filter, url=http://localhost:2990/jira/issues/?filter=10001},
{name=project = ABGF AND issuetype = Story...

STATUS 400 - Request is invalid.

STATUS 404 - No Integrity check operation with the given id.

Download the results as .csv

GET /integrity/{id}/csv

Get a .csv file with the end result of the Integrity Check operation with the given id.

The .csv file will be empty if no integrity violations are detected.

Request

Parameter	Type	Description

Parameter

Type

Description

id

integer

Required

The id of the operation.

curl -u admin:admin -i -H "Content-Type: application/json" -X GET http://localhost:2990/jira/rest/integrity-check/api/1.4/integrity/1/csv

Responses

STATUS 200 - text/csv - Returns a .csv file.

STATUS 400 - Request is invalid.

STATUS 404 - No Integrity check operation with the given id.

Cancel a running integrity check

PUT /integrity/{id}/cancel

Cancel a running Integrity Check operation.

Request

Parameter	Type	Description

Parameter

Type

Description

id

integer

Required

The id of the operation.

curl -u admin:admin -i -H "Content-Type: application/json" -X PUT http://localhost:2990/jira/rest/integrity-check/api/1.4/integrity/1/cancel

Responses

STATUS 200 - Cancellation request received.

STATUS 400 - An error occurred while canceling the Integrity Check operation.

STATUS 404 - No Integrity check operation with the given id.

Snapshot scope

POST /integrity/scoped

Start an Integrity Check operation on the last unsuccessful snapshot. After successfully completing the operation, use "/integrity/{id}" to get the result.

Responses

STATUS 200 - Operation successfully completed.

Headers

Location: required(string)
Contains the operation Id.

STATUS 500 - Could not retrieve snapshot metadata, i.e. unsuccessful snapshot is missing.