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 |
|---|
v1.1.0 | v8.4.0 and later |
v1.0.0 | v8.2.0 and later |
The ProForma Customer API uses semantic versioning. This means that we strive to maintain backwards compatibility, and new features will be added to the API without breaking existing functionality. All changes to the API will require a new version.
Bug fixes are treated a 'patch' version. This is indicated by the third digit of the version number, eg 1.0.0 → 1.0.1
New features which do not change existing functionality are treated as a 'minor' version. This is indicated by the second digit of the version number, eg 1.0.0 → 1.1.0
New features which do change existing functionality are treated as a 'major' version. This is indicated by the first digit of the version number, eg 1.0.0 → 2.0.0. If we release a new major version it is our intention that the previous version will still be available and be maintained until customers can migrate to the new one.
Export Data API
In order to access the ProForma Export API, a user must have the ProForma: Export All Data global permission (Jira Settings > Systems > Global Permissions). No groups are assigned to this permission by default. Once this permission is given, members of the group will be able to call export APIs in ProForma with full access to all form and issue data.
Customer API
Any user with permission to edit an issue can call the ProForma Customer API.
The ProForma Customer API is a Jira REST API, which means it uses the same authentication methods as the Jira REST API. Accessing the API requires a Jira user with the permission "ProForma: Export All Data". This is a global permission which a Jira administrator can add to any user. By default no users are granted this permission (not even Jira administrators) so the API is effectively off by default.
A user with the ProForma: Export All Data permission can use either of the two methods Jira provides to authenticate for APIs:
Atlassian recommends that you use OAuth 1.0a rather than basic authentication, and we do too. Refer to Atlassian OAuth documentation for how to authenticate using OAuth.
If you just want to try out the API quickly before making more formal use of it then you may wish to use basic authentication. Refer to Atlassian basic authentication documentation for how to do this.
In order to access the ProForma API, a user must have the ProForma: Export All Data global permission (Jira Settings > Systems > Global Permissions). No groups are assigned to this permission by default. Once this permission is given, members of the group will be able to call export APIs in ProForma with full access to all form and issue data.
| Confluence open api |
|---|
| defaultModelRendering | model |
|---|
|
openapi: 3.0.0
info:
version: v1.0.0
title: ProForma Customer API
contact:
name: ProForma Support
url: 'https://support.thinktilt.com'
license:
name: Proprietary
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.
paths:
/rest/proforma/1/export:
post:
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.
security: []
requestBody:
description: 'The body of this POST request describes what to export: all form responses on the specified project with the specified template form ID.'
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:
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
security: []
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:
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
security: []
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:
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 what to export: all form responses on the specified project with the specified template form ID.'
content:
application/json:
schema:
$ref: '#/components/schemas/AddFormRequest'
examples:
example-1:
value:
templateFormId: 1
visibility: e
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}/submit':
post:
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
security: []
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:
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
security: []
responses:
'200':
description: The form has been successfully reopen
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:
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
security: []
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'
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: e
description: 'Optional parameter specifying whether the form is visible externally (on the Jira Service Desk portal). Use `e` to indicate an external form, use `i` to indicate an internal form. Only applicable to Service Desk projects. The form will be an internal form if no value is specified.'
enum:
- i
- e
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
FormVisibility:
type: string
description: |-
The visibility of the form, which is only applicable for Service Desk projects.
- e - for forms which are set to External and accessible via the Portal
- i - for forms which are set to Internal and only accessible via the Agent view
enum:
- i
- e
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
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: # <-- arbitrary name for the security scheme
type: http
scheme: basic
security:
- basicAuth: []
servers:
- url: 'https://{jiraServer}'
variables:
jiraServer:
default: localhost
description: 'The URL of your jira server, using http'
- url: 'http://{jiraServerInsecure}'
variables:
jiraServerInsecure:
default: localhost
description: 'The URL of your jira server, using http'