v1.1.0 API documentation

ProForma provides an API to make it easier for our customers to access their data. This version 1.2 the API includes the Export API and a number of new form related features in the Form API. We plan to add more features to the Form API in future versions.

Refer to ProForma API Documentation for general information about the use of this API.

可用性

The API is available in Jira Server and Jira Data Center.

The ProForma Customer API is available in the following versions of ProForma:

ProForma Customer API	ProForma version
v1.2.0	v8.4.9 and later
v1.1.0 THIS VERSION	v8.4.0 and later
v1.0.0	v8.2.0 and later

ProForma Customer API V1.1.0 OAS3

Export API

The export APIs provide a way to export all data from ProForma forms.

POST Start export

/rest/proforma/1/export

/rest/proforma/1/export

Starts an export of ProForma data. Exports are performed as a background process so this API call does not immediately return the result, instead ProForma returns an export ID which you can use to check the status and download the export later. Exporting can be either a quick or a slow process depending on how big your Jira instance is. Expect an export to take a few seconds if your project has a few hundred issues, or take a few minutes if your project has a few thousand issues. Currently ProForma supports two exports: - responses-json a JSON document containing all responses to the specified template form on the specified project. - responses-xlsx an XLSX spreadsheet containing all responses to the specified template form on the specified project.

パラメーター

No parameters

Request body

application/json

The body of this POST request describes what will be exported. All form responses in the specified project that match the template form ID you specify will be exported.

値の例

{
  "type": "responses-xlsx",
  "projectKey": "ABC",
  "templateFormId": 1,
  "fields": [
    "summary",
    "priority",
    "customfield_10012"
  ],
  "jql": "(description ~ broken OR description ~ 'not working') AND created >= 2020-08-20"
}

スキーマ

ExportRequest {
`type*`	文字列 example: responses-xlsx The type of export. Currently `responses-json` and `responses-xlsx` are supported.
`projectKey*`	string example: ABC A string containing the project key to export data from. Only one project can be specified; multiple projects require multiple exports.
`templateFormId*`	number example: 1 The ID of the template form to export data from. To find the ID of a template form, open the form in the ProForma form builder. The URL of that page will end in `ac.form.id`, that number is the template form ID to provide here.
`fields`	[string] example: List [ "summary", "priority", "customfield_10012" ] An optional array with the name(s) of jira fields. The export will include the values of each of these jira fields, for each issue.
`JQL`	string example: (description ~ broken OR description ~ 'not working') AND created >= 2020-08-20 An optional string containing a JQL query. The export will be limited to include only issues that match this JQL query. NB: Including the project in the JQL (e.g. project = MyServiceDesk) is not required since ProForma will automatically include it.
}

レスポンス

コード説明

200

Indicates that the export process has started successfully. Use the information in this response to check the status of the export later. In particular you can poll the URL returned in the statusUrl value to check the status of the export.
x-summary: Export started successfully

Media type: application/json

値の例

{
  "type": "responses-xlsx",
  "id": "responses-xlsx-ABC-1-1234567890",
  "statusUrl": "https://jira.example.com/jira/rest/proforma/1/export/responses-xlsx-ABC-1-1234567890"
}

スキーマ

ExportStartResponse {
`type*`	string example: responses-xlsx A string identifying the export type.
`id*`	string example: responses-xlsx-ABC-1-1234567890 A string identifying the export task. Each export is given this unique ID to allow it to be retrieved later.
`statusURL*`	string example: https://jira.example.com/jira/rest/proforma/1/export/responses-xlsx-ABC-1-1234567890 The URL of the check status API which you can call to check the progress of this export.
}

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

値の例

{
  "error": "client"
}

スキーマ

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

値の例

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

スキーマ

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

値の例

{
  "error": "server",
  "message": "string"
}

スキーマ

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ server ]
message	文字列 A more user-friendly description of the error in English, if available.
}

Extensions

フィールド	値
x-permissions	["ProForma: Export All Data"]

GET Check status of export

/rest/proforma/1/export/{exportId}

/rest/proforma/1/export/{exportId}

Checks the status of an export: whether it has completed successfully or failed, and how much progress has been made if not complete. The URL of this API will be provided to you when you start an export using the "Start export" API above. You can poll the URL returned in the statusUrl value to check the status of the export.

パラメーター

名前説明

exportId*
string

(path)

Export task ID, provided by the response to the 'Start export' API.

レスポンス

コード説明

200

Export status loaded successfully.

Media type: application/json

値の例

{
  "type": "responses-xlsx",
  "id": "responses-xlsx-ABC-1-1234567890",
  "complete": false,
  "failed": false,
  "progress": 25
}

スキーマ

ExportStatusResponse {
`type*`	string example: responses-xlsx A string identifying the type of export. The only possible values in this version of the API are: - `responses-json`. - `responses-xlsx`
`id*`	string example: responses-xlsx-ABC-1-1234567890 A string identifying the export task. Each export is given this unique ID to allow it to be retrieved later.
`complete*`	boolean example: true Indicates whether the export has completed successfully. This will initially be `false` for all but the smallest projects, once it turns `true` the export has finished and the file can be downloaded.
`failed*`	boolean example: false Indicates whether the export has failed. If this is `true` then something unexpected has gone wrong in the processing of this export. Please contact us for assistance in resolving this problem.
`progress*`	number example: 25 The estimated percentage complete of this export, expressed as an integer from 0 to 100.
downloadURL	string example: https://jira.example.com/jira/rest/proforma/1/export/responses-xlsx-ABC-1-1234567890/ProForma-ABC-form-1.xlsx The URL where this export can be downloaded. This `downloadUrl` will not be provided until the export has successfully completed, so once it appears in the response it is safe to call the URL and download the export file.
message	string example: Error constructing JQL query A text-based message providing more information about the status (whether completed or failed) of the export.
}

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

値の例

{
  "error": "client"
}

スキーマ

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

値の例

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

スキーマ

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

404

ProForma could not find the export for the ID in the request. This may mean the export has been downloaded and is no longer in memory, or it may mean that the ID provided is invalid.

x-summary: Not found

Media type: application/json

値の例

{
  "error": "notFound",
  "message": "Export responses-xlsx-ABC-1-1234567890 not found"
}

スキーマ

NotFoundApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

値の例

{
  "error": "server",
  "message": "string"
}

スキーマ

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ server ]
message	文字列 A more user-friendly description of the error in English, if available.
}

Extensions

フィールド	値
x-permissions	["ProForma: Export All Data"]

GET Download export

/rest/proforma/1/export/{exportId}/{filename}

/rest/proforma/1/export/{exportId}/{filename}

Downloads the export file once it has completed processing. The URL of this API will be provided to you by calling the "Check status of export" API above. Don't call this API until the URL has been provided by the status check; this API will return an error if called before the export has finished processing. The file can only be downloaded once per export. Once you request the download from this URL the file will be deleted on the server to save resources. You will need to start another export if you wish to retrieve it again.

パラメーター

名前説明

exportId*
string

(path)

Export task ID, provided by the response to the 'Start export' API.

filename*
string

(path)

Name of the export file. The filename be provided by the check status API.

レスポンス

コード説明

200

File download

Media type: application/json

値の例

{
  "type": "responses-xlsx",
  "id": "responses-xlsx-ABC-1-1234567890",
  "complete": false,
  "failed": false,
  "progress": 25
}

スキーマ

ExportStatusResponse {
`type*`	string example: responses-xlsx A string identifying the type of export. The only possible values in this version of the API are: - `responses-json`. - `responses-xlsx`
`id*`	string example: responses-xlsx-ABC-1-1234567890 A string identifying the export task. Each export is given this unique ID to allow it to be retrieved later.
`complete*`	boolean example: true Indicates whether the export has completed successfully. This will initially be `false` for all but the smallest projects, once it turns `true` the export has finished and the file can be downloaded.
`failed*`	boolean example: false Indicates whether the export has failed. If this is `true` then something unexpected has gone wrong in the processing of this export. Please contact us for assistance in resolving this problem.
`progress*`	number example: 25 The estimated percentage complete of this export, expressed as an integer from 0 to 100.
downloadURL	string example: https://jira.example.com/jira/rest/proforma/1/export/responses-xlsx-ABC-1-1234567890/ProForma-ABC-form-1.xlsx The URL where this export can be downloaded. This `downloadUrl` will not be provided until the export has successfully completed, so once it appears in the response it is safe to call the URL and download the export file.
message	string example: Error constructing JQL query A text-based message providing more information about the status (whether completed or failed) of the export.
}

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

値の例

{
  "error": "client"
}

スキーマ

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

値の例

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

スキーマ

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

404

ProForma could not find the export for the ID in the request. This may mean the export has been downloaded and is no longer in memory, or it may mean that the ID provided is invalid.

x-summary: Not found

Media type: application/json

値の例

{
  "error": "notFound",
  "message": "Export responses-xlsx-ABC-1-1234567890 not found"
}

スキーマ

NotFoundApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

値の例

{
  "error": "server",
  "message": "string"
}

スキーマ

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ server ]
message	文字列 A more user-friendly description of the error in English, if available.
}

Extensions

フィールド	値
x-permissions	["ProForma: Export All Data"]

Form API

The form APIs provide a way to interact with forms on an issue.

POST Add form to issue

/rest/proforma/1/issue/{issueKey}/form

/rest/proforma/1/issue/{issueKey}/form

Adds a form to an issue. The ID of the template form to add is provided in the body of the request, optionally along with the number of copies to add and whether to make it available externally (on the Jira Service Desk portal). ProForma will only add the form if the user calling the API has permission to edit that issue. This API does not check if the form already exists on the issue; if the form already exists on the issue that form will be added again without affecting the existing form. Multiple copies of the same form can be added by using the add parameter of the API.

パラメーター

名前説明

issueKey*
string

(path)

Issue key for Jira issue

Request body

application/json

The body of this POST request describes the form to add to an issue.

値の例

{
  "templateFormId": 1,
  "visibility": "external",
  "add": 2
}

スキーマ

AddFormRequest {
`templateFormId*`	number example: 1 The ID of the template form to export data from. To find the ID of a template form, open the form in the ProForma form builder. The URL of that page will end in `ac.form.id`, that number is the template form ID to provide here.
`visibility`	string example: external Optional parameter specifying whether the form is visible externally (on the Jira Service Desk portal). Only applicable to Service Desk projects. The form will be an internal form if no value is specified. Enum: Array [ 2 ] [ internal, external ]
`add`	number($int64) example: 2 A number specifying the number of times to add this form. One form will be added if no value is specified.
}

レスポンス

コード説明

200

Indicates the form has been added successfully.
x-summary: Form added successfully

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

値の例

{
  "error": "client"
}

スキーマ

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

値の例

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

スキーマ

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

404

Proforma could not find the specified form.

x-summary: Not found

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

値の例

{
  "error": "server",
  "message": "string"
}

スキーマ

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ server ]
message	文字列 A more user-friendly description of the error in English, if available.
}

Extensions

フィールド	値
x-permissions	["Edit issues"]

POST Copy a form from one issue to another

/rest/proforma/1/issue/{issueKey}/form/{formId}/copy/{toIssueKey}

/rest/proforma/1/issue/{issueKey}/form/{formId}/copy/{toIssueKey}

Copy a form from one issue to another

パラメーター

名前説明

issueKey*
string

(path)

Issue key for Jira issue.

formId*
number

(path)

ID of the ProForma form.

toIssueKey*
string

(path)

Issue key for Jira issue.

Request body

application/json

値の例

{
  "status": "open",
  "visibility": "internal"
}

スキーマ

CopyFormRequest {

ステータス

FormStatusCustomer string

The status of a form, which can be

open - for forms which are open
submitted - for forms which have been submitted
locked - for forms which have been locked

Enum:

Array [ 3 ]

[ open, submitted, locked ]

visibility

FormVisibility string

The visibility of the form, which is only applicable for Service Desk projects.

internal - for forms which are set to Internal and only accessible via the Agent view
external - for forms which are set to External and accessible via the Portal

Enum:

Array [ 2 ]

[ internal, external ]

}

レスポンス

コード説明

200

Operation completed successfully.

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

値の例

{
  "error": "client"
}

スキーマ

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

値の例

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

スキーマ

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

値の例

{
  "error": "server",
  "message": "string"
}

スキーマ

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ server ]
message	文字列 A more user-friendly description of the error in English, if available.
}

Extensions

フィールド	値
x-permissions	["Browse Projects","Edit Issues"]

POST Submit a form

/rest/proforma/1/issue/{issueKey}/form/{formId}/submit

/rest/proforma/1/issue/{issueKey}/form/{formId}/submit

Change the status of a form attached to an issue to submitted

パラメーター

名前説明

issueKey*
string

(path)

Issue key for Jira issue.

formId*
number

(path)

The number of the form attached to an issue. The number is determined by the order in which the forms are added to an issue. So the first form is 1, the second form is 2; however, if the the second form is then delete the next form will take the id 3 (not 2).

レスポンス

コード説明

200

The form has been successfully submitted.

Media type: application/json

値の例

{
  "status": "o",
  "transitioned": true
}

スキーマ

FormStateChangeResult {
The status and visibility of an issue form, as well as a flag indicating if the issue was transitioned to a new status (due to ProForma automation rules) as a result of the change.
`status`	FormStatus string The status of a form, which can be o - for forms which are open s - for forms which have been submitted l - for forms which have been locked Enum: ここをクリックして展開... [ o, s, l ]
transitioned	ブーリアン
}

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

値の例

{
  "error": "client"
}

スキーマ

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

値の例

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

スキーマ

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

値の例

{
  "error": "server",
  "message": "string"
}

スキーマ

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ server ]
message	文字列 A more user-friendly description of the error in English, if available.
}

Extensions

フィールド	値
x-permissions	["Edit Issues"]

POST Reopen a form

/rest/proforma/1/issue/{issueKey}/form/{formId}/reopen

/rest/proforma/1/issue/{issueKey}/form/{formId}/reopen

Change the status of a submitted form to open

パラメーター

名前説明

issueKey*
string

(path)

Issue key for Jira issue.

formId*
number

(path)

The number of the form attached to an issue. The number is determined by the order in which the forms are added to an issue. So the first form is 1, the second form is 2; however, if the the second form is then delete the next form will take the id 3 (not 2).

レスポンス

コード説明

200

The form has been successfully reopened.

Media type: application/json

値の例

{
  "status": "o",
  "transitioned": true
}

スキーマ

FormStateChangeResult {
The status and visibility of an issue form, as well as a flag indicating if the issue was transitioned to a new status (due to ProForma automation rules) as a result of the change.
`status`	FormStatus string The status of a form, which can be o - for forms which are open s - for forms which have been submitted l - for forms which have been locked Enum: ここをクリックして展開... [ o, s, l ]
transitioned	ブーリアン
}

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

値の例

{
  "error": "client"
}

スキーマ

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

値の例

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

スキーマ

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

値の例

{
  "error": "server",
  "message": "string"
}

スキーマ

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ server ]
message	文字列 A more user-friendly description of the error in English, if available.
}

Extensions

フィールド	値
x-permissions	["Edit Issues"]

POST Unlock a form

/rest/proforma/1/issue/{issueKey}/form/{formId}/unlock

/rest/proforma/1/issue/{issueKey}/form/{formId}/unlock

Change the status of a locked form to unlocked, so it can then be reopened.

パラメーター

名前説明

issueKey*
string

(path)

Issue key for Jira issue.

formId*
number

(path)

The number of the form attached to an issue. The number is determined by the order in which the forms are added to an issue. So the first form is 1, the second form is 2; however, if the the second form is then delete the next form will take the id 3 (not 2).

レスポンス

コード説明

200

The form has been successfully unlocked.

Media type: application/json

値の例

{
  "status": "o",
  "transitioned": true
}

スキーマ

FormStateChangeResult {
The status and visibility of an issue form, as well as a flag indicating if the issue was transitioned to a new status (due to ProForma automation rules) as a result of the change.
`status`	FormStatus string The status of a form, which can be o - for forms which are open s - for forms which have been submitted l - for forms which have been locked Enum: ここをクリックして展開... [ o, s, l ]
transitioned	ブーリアン
}

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

値の例

{
  "error": "client"
}

スキーマ

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

値の例

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

スキーマ

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

値の例

{
  "error": "server",
  "message": "string"
}

スキーマ

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ server ]
message	文字列 A more user-friendly description of the error in English, if available.
}

Extensions

フィールド	値
x-permissions	["Administer Projects","Edit Issues"]

GET Download a PDF of a form

/rest/proforma/1/issue/{issueKey}/form/{formId}/pdf

/rest/proforma/1/issue/{issueKey}/form/{formId}/pdf

Download a PDF of a form. A rich PDF is downloaded by default, or you can download a plain PDF by indicating with a query param.

パラメーター

名前説明

issueKey*
string

(path)

Issue key for Jira issue.

formId*
number

(path)

The number of the form attached to an issue. The number is determined by the order in which the forms are added to an issue. So the first form is 1, the second form is 2; however, if the the second form is then delete the next form will take the id 3 (not 2).

plain
boolean

(query)

Query param to specify a plain formatted PDF

Default value : false

レスポンス

コード説明

200

File download

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

値の例

{
  "error": "client"
}

スキーマ

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

値の例

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

スキーマ

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

値の例

{
  "error": "server",
  "message": "string"
}

スキーマ

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ server ]
message	文字列 A more user-friendly description of the error in English, if available.
}

Extensions

フィールド	値
x-permissions	["Browse Projects"]

POST Change the visibility for an issue form

/rest/proforma/1/issue/{issueKey}/form/{formId}/visibility/{visibility}

/rest/proforma/1/issue/{issueKey}/form/{formId}/visibility/{visibility}

Change the visibility for an issue form. NB: The form can only have its visibility set to external for issues in a Service Desk project.

パラメーター

名前説明

issueKey*
string

(path)

Issue key for Jira issue.

formId*
number

(path)

The number of the form attached to an issue. The number is determined by the order in which the forms are added to an issue. So the first form is 1, the second form is 2; however, if the the second form is then delete the next form will take the id 3 (not 2).

visibility*
string

(path)

Action to take for the issue form

Available values : internal, external

レスポンス

コード説明

200

Operation completed successfully.

Media type: application/json

値の例

{
  "visibility": "internal"
}

スキーマ

VisibilityChangeResult {
The visibility of the issue form.
`visibility`	FormVisibility string The visibility of the form, which is only applicable for Service Desk projects. internal - for forms which are set to Internal and only accessible via the Agent view external - for forms which are set to External and accessible via the Portal Enum: Array [ 1 ] [ internal, external ]
}

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

値の例

{
  "error": "client"
}

スキーマ

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

値の例

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

スキーマ

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

値の例

{
  "error": "server",
  "message": "string"
}

スキーマ

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ server ]
message	文字列 A more user-friendly description of the error in English, if available.
}

Extensions

フィールド	値
x-permissions	["Edit Issues"]

Schemas

AddFormRequest

AddFormRequest {
`templateFormId*`	number($int64) example: 1 The ID of the template form to add to this issue. To find the ID of a template form, open the form in the ProForma form builder. The URL of that page will end in `ac.form.id`, that number is the template form ID to provide here.
`visibility`	number($int64) example: 2 A number specifying the number of times to add this form. One form will be added if no value is specified. Array [ 2 ] [ internal, external ]
`add`	number($int64) example: 2 A number specifying the number of times to add this form. One form will be added if no value is specified.
}

ExportRequest

ExportRequest {
`type*`	string example: responses-xlsx The type of export. Currently `responses-json` and `responses-xlsx` are supported.
`projectKey*`	string example: ABC A string containing the project key to export data from. Only one project can be specified; multiple projects require multiple exports.
`templateFormId*`	number example: 1 The ID of the template form to export data from. To find the ID of a template form, open the form in the ProForma form builder. The URL of that page will end in `ac.form.id`, that number is the template form ID to provide here.
フィールド	[string] example: List [ "summary", "priority", "customfield_10012" ]
jql	string example: (description ~ broken OR description ~ 'not working') AND created >= 2020-08-20 An optional string containing a JQL query. The export will be limited to include only issues that match this JQL query. NB: Including the project in the JQL (e.g. project = MyServiceDesk) is not required since ProForma will automatically include it.
}

ExportStartResponse

ExportStartResponse {
`type*`	string example: responses-xlsx A string identifying the export type.
`id*`	string example: responses-xlsx-ABC-1-1234567890 A string identifying the export task. Each export is given this unique ID to allow it to be retrieved later.
`statusURL*`	string example: https://jira.example.com/jira/rest/proforma/1/export/responses-xlsx-ABC-1-1234567890 The URL of the check status API which you can call to check the progress of this export.
}

ExportStatusResponse

ExportStatusResponse {
`type*`	string example: responses-xlsx A string identifying the type of export. The only possible values in this version of the API are: - `responses-json`. - `responses-xlsx`
`id*`	string example: responses-xlsx-ABC-1-1234567890 A string identifying the export task. Each export is given this unique ID to allow it to be retrieved later.
`complete*`	boolean example: true Indicates whether the export has completed successfully. This will initially be `false` for all but the smallest projects, once it turns `true` the export has finished and the file can be downloaded.
`failed*`	boolean example: false Indicates whether the export has failed. If this is `true` then something unexpected has gone wrong in the processing of this export. Please contact us for assistance in resolving this problem.
`progress*`	number example: 25 The estimated percentage complete of this export, expressed as an integer from 0 to 100.
downloadURL	string example: https://jira.example.com/jira/rest/proforma/1/export/responses-xlsx-ABC-1-1234567890/ProForma-ABC-form-1.xlsx The URL where this export can be downloaded. This `downloadUrl` will not be provided until the export has successfully completed, so once it appears in the response it is safe to call the URL and download the export file.
message	string example: Error constructing JQL query A text-based message providing more information about the status (whether completed or failed) of the export.
}

CustomerApiError

CustomerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred
`message`	文字列 A more user-friendly description of the error in English, if available.
}

ClientApiError

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

ForbiddenApiError

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

NotFoundApiError

NotFoundApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ not found ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

ServerApiError

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ server ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

InvalidJsonApiError

InvalidJsonApiError {
Error response specific to request JSON parsing errors. It may include further details on the cause of the parsing error.
`error*`	文字列 The type of error that occurred Enum: Array [ 1 ] [ json ]
`message`	文字列 A more user-friendly description of the error in English, if available.
}

FormStatus

FormStatus string

The status of a form, which can be

o - for forms which are open
s - for forms which have been submitted
l - for forms which have been locked

Enum:

Array [ 3 ]

[ o, s, l ]

CopyFormRequest

CopyFormRequest {
ステータス	FormStatusCustomer string The status of a form, which can be open - for forms which are open submitted - for forms which have been submitted locked - for forms which have been locked Enum: Array [ 3 ] [ open, submitted, locked ]
`visibility`	FormVisibility string The visibility of the form, which is only applicable for Service Desk projects. internal - for forms which are set to Internal and only accessible via the Agent view external - for forms which are set to External and accessible via the Portal Enum: Array [ 2 ] [ internal, external ]
}

FormStatusCustomer

FormStatusCustomer string

The status of a form, which can be

open - for forms which are open
submitted - for forms which have been submitted
locked - for forms which have been locked

Enum:

Array [ 3 ]

[ open, submitted, locked ]

FormVisibility

FormVisibility string

The visibility of the form, which is only applicable for Service Desk projects.

internal - for forms which are set to Internal and only accessible via the Agent view
external - for forms which are set to External and accessible via the Portal

Enum:

Array [ 3 ]

[ internal, external ]

FormStateChangeResult

FormStateChangeResult {
The status and visibility of an issue form, as well as a flag indicating if the issue was transitioned to a new status (due to ProForma automation rules) as a result of the change.
`status`	FormStatus string The status of a form, which can be o - for forms which are open s - for forms which have been submitted l - for forms which have been locked Enum: ここをクリックして展開... [ o, s, l ]
transitioned	ブーリアン
}

VisibilityChangeResult

VisibilityChangeResult {
The visibility of the issue form.
`visibility`	FormVisibility string The visibility of the form, which is only applicable for Service Desk projects. internal - for forms which are set to Internal and only accessible via the Agent view external - for forms which are set to External and accessible via the Portal Enum: Array [ 1 ] [ internal, external ]
}

ページ

Viewport

Confluence

v1.1.0 API documentation

ProForma 開発者向けドキュメント

このページの内容

関連コンテンツ

お困りですか?

可用性

ProForma Customer API V1.1.0 OAS3

Export API

パラメーター

Request body

値の例

スキーマ

値の例

スキーマ

値の例

スキーマ

値の例

スキーマ

値の例

スキーマ

Extensions

パラメーター

レスポンス

値の例

スキーマ

値の例

スキーマ

値の例

スキーマ

値の例

スキーマ

値の例

スキーマ

Extensions

パラメーター

レスポンス

値の例

スキーマ

値の例

スキーマ

値の例

スキーマ

値の例

スキーマ

値の例

スキーマ

Extensions

Form API

パラメーター

Request body

値の例

スキーマ

値の例

スキーマ

値の例

スキーマ

値の例

スキーマ

Extensions

パラメーター

Request body

値の例

スキーマ

レスポンス

値の例

スキーマ

値の例

スキーマ

値の例

スキーマ

Extensions

パラメーター

レスポンス

値の例

スキーマ

値の例

スキーマ