Introduction
ProForma provides an API to make it easier for our customers to access their data. This version 1.1 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 https://thinktilt.atlassian.net/wiki/spaces/PFDEV/pages/1223361160 for general information about the use of this API.
Table of Contents |
---|
Availability
The API is available in Jira Server and Jira Data Center but it is not available in Jira Cloud. If you are a Cloud customer who would find this API useful, please contact us to discuss whether we can find a solution for you.
The ProForma Customer API is available in the following versions of ProForma:
ProForma Customer API | ProForma Version | ||||
---|---|---|---|---|---|
v8.4.9 and later | |||||
| v8.4.0 and later | ||||
v8.2.0 and later |
Confluence open api | ||||
---|---|---|---|---|
| ||||
openapi: 3.0.0 info: version: v1.1.0 title: ProForma Customer API contact: name: ProForma Support url: 'https://support.thinktilt.com' license: name: Proprietary x-logo: url: '/images/proforma-logo.svg' tags: - name: Export API description: > The export APIs provide a way to export all data from ProForma forms. - name: Form API description: > The form APIs provide a way to interact with forms on an issue. security: - basicAuth: [] paths: /rest/proforma/1/export: post: x-permissions: ['ProForma: Export All Data'] operationId: postStartExport tags: - Export API summary: Start export description: > 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. requestBody: description: 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. content: application/json: schema: $ref: '#/components/schemas/ExportRequest' examples: example-1: value: type: responses-xlsx projectKey: ABC templateFormId: 1 fields: - summary - priority - customfield_10012 jql: (description ~ broken OR description ~ 'not working') AND created >= 2020-08-20 responses: '200': x-summary: Export started successfully description: > 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. content: application/json: schema: $ref: '#/components/schemas/ExportStartResponse' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' /rest/proforma/1/export/{exportId}: get: x-permissions: ['ProForma: Export All Data'] operationId: getExportStatus summary: Check status of export description: > 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. tags: - Export API parameters: - name: exportId in: path description: Export task ID, provided by the response to the 'Start export' API. required: true schema: type: string responses: '200': description: Export status loaded successfully content: application/json: schema: $ref: '#/components/schemas/ExportStatusResponse' examples: InProgress: summary: In progress description: An export which is currently being generated, and is approximately 25% through processing. value: type: responses-xlsx id: responses-xlsx-ABC-1-1234567890 complete: false failed: false progress: 25 Completed: summary: Completed description: An export which has completed successfully and is ready to download. value: type: responses-xlsx id: responses-xlsx-ABC-1-1234567890 complete: true failed: false progress: 100 downloadUrl: 'https://jira.example.com/jira/rest/proforma/1/export/responses-xlsx-ABC-1-1234567890/ProForma-ABC-form-1.xlsx' Failed: summary: Failed description: An export which has failed and has stopped processing. value: type: responses-xlsx id: responses-xlsx-ABC-1-1234567890 complete: true failed: true progress: 77 message: Error constructing JQL query '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /rest/proforma/1/export/{exportId}/{filename}: get: x-permissions: ['ProForma: Export All Data'] operationId: getExportDownload summary: Download export description: > 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. tags: - Export API parameters: - name: exportId in: path description: Export task ID, provided by the response to the 'Start export' and 'Check status of export' APIs. required: true schema: type: string - name: filename in: path description: Name of the export file. The filename be provided by the check status API. required: true schema: type: string responses: '200': description: File download content: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': example: "Spreadsheet file in Excel XLSX format" 'application/json': example: "JSON document" '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /rest/proforma/1/issue/{issueKey}/form: post: x-permissions: ['Edit Issues'] operationId: postAddFormToIssue tags: - Form API summary: Add form to issue description: > 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. parameters: - name: issueKey in: path description: Issue key for Jira issue required: true schema: type: string requestBody: description: The body of this POST request describes the form to add to an issue. content: application/json: schema: $ref: '#/components/schemas/AddFormRequest' examples: example-1: value: templateFormId: 1 visibility: external add: 2 responses: '200': x-summary: Form added successfully description: Indicates that the form has be added successfully. The body of this response will be empty. '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': x-summary: Forbidden description: The API was called by a user who does not have permission to make that request. Access to this API requires the user to have the "edit issue" permission on the issue that the form is being added to. content: application/json: schema: $ref: '#/components/schemas/ForbiddenApiError' examples: default: value: error: forbidden '404': x-summary: Not Found description: ProForma could not find the specified form. '500': $ref: '#/components/responses/500' /rest/proforma/1/issue/{issueKey}/form/{formId}/copy/{toIssueKey}: post: x-permissions: ['Browse Projects', 'Edit Issues'] operationId: copyForm summary: Copy a form from one issue to another description: > Copy a form from one issue to another tags: - Form API parameters: - name: issueKey in: path description: Issue key for Jira issue required: true schema: type: string - name: formId in: path description: ID for the ProForma form required: true schema: type: number - name: toIssueKey in: path description: Issue key for Jira issue required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CopyFormRequest' responses: '200': description: > Operation completed successfully '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' /rest/proforma/1/issue/{issueKey}/form/{formId}/submit: post: x-permissions: ['Edit Issues'] operationId: submitForm summary: Submit a form description: > Change the status of a form attached to an issue to submitted tags: - Form API parameters: - name: issueKey in: path description: Issue key for Jira issue required: true schema: type: string - name: formId in: path description: > 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). required: true schema: type: string responses: '200': description: The form has been successfully submitted content: application/json: schema: $ref: '#/components/schemas/FormStateChangeResult' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' /rest/proforma/1/issue/{issueKey}/form/{formId}/reopen: post: x-permissions: ['Edit Issues'] operationId: reopenForm summary: Reopen a form description: > Change the status of a submitted form to open tags: - Form API parameters: - name: issueKey in: path description: Issue key for Jira issue required: true schema: type: string - name: formId in: path description: > 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). required: true schema: type: string responses: '200': description: The form has been successfully reopened content: application/json: schema: $ref: '#/components/schemas/FormStateChangeResult' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' /rest/proforma/1/issue/{issueKey}/form/{formId}/unlock: post: x-permissions: ['Administer Projects', 'Edit Issues'] operationId: unlockForm summary: Unlock a form description: > Change the status of a locked form to unlocked, so it can then be reopened. tags: - Form API parameters: - name: issueKey in: path description: Issue key for Jira issue required: true schema: type: string - name: formId in: path description: > 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). required: true schema: type: string responses: '200': description: The form has been successfully unlocked content: application/json: schema: $ref: '#/components/schemas/FormStateChangeResult' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' /rest/proforma/1/issue/{issueKey}/form/{formId}/pdf: get: x-permissions: ['Browse Projects'] operationId: getPdf summary: Download a PDF of a form description: > 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. tags: - Form API parameters: - name: issueKey in: path description: Issue key for Jira issue required: true schema: type: string - name: formId in: path description: ID for the ProForma form required: true schema: type: number - name: plain in: query description: Query param to specify a plain formatted PDF required: false schema: type: boolean default: false responses: '200': description: File download content: application/pdf: example: "File in PDF format" '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' '/rest/proforma/1/issue/{issueKey}/form/{formId}/visibility/{visibility}': post: x-permissions: ['Edit Issues'] operationId: changeFormVisibility summary: Change the visibility for an issue form description: > 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. tags: - Form API parameters: - name: issueKey in: path description: Issue key for Jira issue required: true schema: type: string - name: formId in: path description: ID for the ProForma form required: true schema: type: number - name: visibility in: path description: Action to take for the issue form required: true schema: $ref: '#/components/schemas/FormVisibility' responses: '200': description: > Operation completed successfully content: application/json: schema: $ref: '#/components/schemas/VisibilityChangeResult' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' components: schemas: AddFormRequest: type: object required: - templateFormId properties: templateFormId: type: number format: int64 example: 1 description: 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: type: string example: external description: 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: - internal - external add: type: number format: int64 example: 2 description: A number specifying the number of times to add this form. One form will be added if no value is specified. ExportRequest: type: object required: - type - projectKey - templateFormId properties: type: type: string example: responses-xlsx description: The type of export. Currently `responses-json` and `responses-xlsx` are supported. projectKey: type: string example: ABC description: A string containing the project key to export data from. Only one project can be specified; multiple projects require multiple exports. templateFormId: type: number example: 1 description: 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: type: array description: 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. items: type: string example: - summary - priority - customfield_10012 jql: type: string description: > 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. example: (description ~ broken OR description ~ 'not working') AND created >= 2020-08-20 ExportStartResponse: type: object required: - type - id - statusUrl properties: type: type: string example: responses-xlsx description: A string identifying the export type. id: type: string example: responses-xlsx-ABC-1-1234567890 description: A string identifying the export task. Each export is given this unique ID to allow it to be retrieved later. statusUrl: type: string example: https://jira.example.com/jira/rest/proforma/1/export/responses-xlsx-ABC-1-1234567890 description: The URL of the check status API which you can call to check the progress of this export. ExportStatusResponse: type: object required: - type - id - complete - failed - progress properties: type: type: string example: responses-xlsx description: > A string identifying the type of export. The only possible values in this version of the API are: - `responses-json`. - `responses-xlsx` id: type: string example: responses-xlsx-ABC-1-1234567890 description: A string identifying the export task. Each export is given this unique ID to allow it to be retrieved later. complete: type: boolean example: true description: 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: type: boolean example: false description: 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: type: number example: 25 description: The estimated percentage complete of this export, expressed as an integer from 0 to 100. downloadUrl: type: string example: https://jira.example.com/jira/rest/proforma/1/export/responses-xlsx-ABC-1-1234567890/ProForma-ABC-form-1.xlsx description: 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: type: string example: Error constructing JQL query description: A text-based message providing more information about the status (whether completed or failed) of the export. CustomerApiError: type: object description: A general error type. More specific errors extend this type with additional information. required: - error properties: error: type: string description: The type of error that occurred message: type: string description: A more user-friendly description of the error in English, if available. ClientApiError: allOf: - $ref: '#/components/schemas/CustomerApiError' - type: object properties: error: enum: - client ForbiddenApiError: allOf: - $ref: '#/components/schemas/CustomerApiError' - type: object properties: error: enum: - forbidden NotFoundApiError: allOf: - $ref: '#/components/schemas/CustomerApiError' - type: object properties: error: enum: - notFound ServerApiError: allOf: - $ref: '#/components/schemas/CustomerApiError' - type: object properties: error: enum: - server InvalidJsonApiError: description: Error response specific to request JSON parsing errors. It may include further details on the cause of the parsing error. allOf: - $ref: '#/components/schemas/CustomerApiError' - type: object properties: error: type: string enum: - json details: type: object FormStatus: type: string description: > 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 CopyFormRequest: type: object properties: status: $ref: '#/components/schemas/FormStatusCustomer' visibility: $ref: '#/components/schemas/FormVisibility' FormStatusCustomer: type: string description: > 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: - "open" - "submitted" - "locked" FormVisibility: type: string description: > 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: - internal - external FormStateChangeResult: type: object description: 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. properties: status: $ref: '#/components/schemas/FormStatus' transitioned: type: boolean VisibilityChangeResult: type: object description: > The visibility of the issue form. properties: visibility: $ref: '#/components/schemas/FormVisibility' responses: '400': x-summary: Bad request description: 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. content: application/json: schema: $ref: '#/components/schemas/ClientApiError' examples: default: value: error: client '401': x-summary: Unauthorized description: > 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. '403': x-summary: Forbidden description: The API was called by a user who does not have permission to make that request. content: application/json: schema: $ref: '#/components/schemas/ForbiddenApiError' examples: default: value: error: forbidden message: "Access to this API requires a user with the 'ProForma: Export All Data' global permission" '404': x-summary: Not Found description: 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. content: application/json: schema: $ref: '#/components/schemas/NotFoundApiError' examples: default: value: error: notFound message: "Export responses-xlsx-ABC-1-1234567890 not found" '500': x-summary: Server error description: 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. If you encounter this error please [contact us](https://support.thinktilt.com/) for help. content: application/json: schema: $ref: '#/components/schemas/ServerApiError' securitySchemes: basicAuth: type: http scheme: basic description: The ProForma Customer API is a Jira REST API, which means it uses the same authentication methods as the Jira REST API. Required permissions differ per API. See the individual API **x-permissions** list for required permissions. |