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.

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

v1.2.0

v8.4.9 and later

v1.1.0

v8.4.0 and later

v1.0.0

v8.2.0 and later


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.