Legacy form data format

Legacy forms overview

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

Manipulating ProForma data directly via the Jira API is not supported

Although reading (or GETTING) form data via this API is safe, be very careful when writing (or PUTTING) data back into an issue's entity property, especially in a production environment. There are 2 big risks that are involved with this.

  1. The structure of the JSON output is not set in stone and is subject to change. In fact, it is likely to change in the near future as we make changes to the current form system.

  2. Corrupted forms. If a mistake is made, it is very easy to corrupt, alter or destroy data which has been entered into a form. Manipulating form state might even make it so forms attached to an issue won't load at all. If this happens, the Forms widget on the issue will show an endlessly spinning loader, and it will be unusable. 

Reading JSON Output

JSON output of from an individual ProForma form (accessed via the proforma.forms.i1 property) might look similar to the following:

Legacy Form JSON Example 
{
  "key": "proforma.forms.i1",
  "value": {
    "schemaVersion": 5,
    "id": 1,
    "projectFormId": 5,
    "internal": true,
    "submitted": true,
    "name": "Every Field Type Form",
    "updated": "2019-10-24T09:40:57.400811Z",
    "questions": [
      {
        "id": 1,
        "t": "h1",
        "q": "Questions Below"
      },
      {
        "id": 2,
        "t": "tl",
        "q": "Wide Text",
        "v": {
          "rq": true
        },
        "text": "Wide"
      },
      {
        "id": 3,
        "t": "ts",
        "q": "Short Text",
        "v": {},
        "text": "Short"
      },
      {
        "id": 4,
        "t": "tl",
        "q": "Regex Text",
        "v": {
          "mnw": 19,
          "mxw": 66,
          "rgx": {
            "p": "w+",
            "m": "Invalid pattern"
          }
        },
        "text": "Must be between 19 and 66 word(s). Must be between 19 and 66 word(s). Must be between 19 and 66 word(s). "
      },
      {
        "id": 5,
        "t": "pg",
        "q": "Paragraph",
        "d": "Paragraph field",
        "v": {},
        "text": "Paragraph"
      },
      {
        "id": 6,
        "t": "no",
        "q": "Number",
        "v": {
          "wh": true
        },
        "text": "18"
      },
      {
        "id": 7,
        "t": "cs",
        "q": "Single Choice",
        "choices": [
          {
            "id": 8,
            "label": "1",
            "selected": true
          },
          {
            "id": 9,
            "label": "2"
          },
          {
            "id": 10,
            "label": "3"
          }
        ],
        "v": {
          "ch": 8
        }
      },
      {
        "id": 11,
        "t": "cm",
        "q": "Multiple Choice",
        "choices": [
          {
            "id": 12,
            "label": "1",
            "selected": true
          },
          {
            "id": 13,
            "label": "2",
            "selected": true
          },
          {
            "id": 14,
            "label": "3"
          }
        ],
        "v": {
          "mns": 1,
          "mxs": 3
        }
      },
      {
        "id": 15,
        "t": "cd",
        "q": "Dropdown",
        "choices": [
          {
            "id": 16,
            "label": "1"
          },
          {
            "id": 17,
            "label": "2",
            "selected": true
          },
          {
            "id": 18,
            "label": "3"
          }
        ],
        "v": {}
      },
      {
        "id": 19,
        "t": "da",
        "q": "Date",
        "v": {},
        "date": "2019-10-25"
      },
      {
        "id": 20,
        "t": "ti",
        "q": "Time",
        "v": {},
        "time": "10:00"
      },
      {
        "id": 21,
        "t": "dt",
        "q": "Date/Time",
        "v": {},
        "date": "2019-10-25",
        "time": "12:00"
      },
      {
        "id": 22,
        "t": "te",
        "q": "Email",
        "v": {},
        "text": "example@example.com"
      },
      {
        "id": 23,
        "t": "tu",
        "q": "URL",
        "v": {},
        "text": "https://google.com"
      },
      {
        "id": 24,
        "t": "us",
        "q": "Single User",
        "v": {},
        "users": [
          {
            "id": "557058:b7e249c2-0297-4685-a991-becdc1d76ad3",
            "name": "ProFormaJ"
          }
        ]
      },
      {
        "id": 25,
        "t": "um",
        "q": "Multiple Users",
        "v": {},
        "users": [
          {
            "id": "557058:b7e249c2-0297-4685-a991-becdc1d76ad3",
            "name": "ProFormaJ"
          },
          {
            "id": "557058:bc2b4479-7303-499f-8602-c737d21d9031",
            "name": "ProForma Support"
          }
        ]
      },
      {
        "id": 26,
        "t": "in",
        "q": "<h1> This info section has a h1 tag </h1>",
        "v": {}
      }
    ],
    "formHash": "b61af30f4c7612062bc49e08c79d5f0d46b2ef9cf987d6b4fac47474a19f5fe0"
  }
}

Here are some points to remember when looking at the JSON output. 

  • The data schema version is stored in the '{{schemaVersion}}' property.

  • Any form created with recent versions of ProForma should have the number 5 in this property.

  • Questions are stored in order in the '{{questions}}' property.

  • Each question has an ID in its '{{id}}' property which is unique within the form and does not change. All copies of the same form will share the same set of IDs.

  • Each question has a type stored in its '{{t}}' property. See below for a list of the types.

  • Text questions store their answer in the question '{{text}}' property.

  • Date questions store their answer in the question '{{date}}' property.

  • Time questions store their answer in the question '{{time}}' property.

  • Choice questions store their answer in the choices listed on the question '{{choices}}' property. Choices which have been selected will have their property {{selected}} set to true. If the property {{selected}} is not present or is false then that choice is not selected. The question types are:

Question Types

This is how each question type is represented.

  • h1: section heading (read-only heading)

  • in: information (read-only HTML)

  • ts: short text

  • tl: long text

  • pg: paragraph text

  • da: date

  • dt: date and time

  • ti: time

  • cd: choice dropdown (select)

  • cs: choice single (radio)

  • cm: choice multiple (checkbox)

  • no: number

  • um: user picker (multiple)

  • us: user picker (single)

Writing Data To A Form

It is possible to use a HTTP PUT request to write information back to the that same REST endpoint. This can allow users to alter the data entered into form fields (however not the form structure), or manipulate the state of a form. For example, a script to reopen a form can be achieved by removing the "submitted' : "true" entry in the form JSON and writing the result back to the issue.

However, as mentioned in the warning above, be very careful when doing this an employ proper error handling and anticipate edge cases. Writing data back to an issue in the wrong way can corrupt data or make forms not work at all on a specific Jira issue. 

Last modified on Jun 18, 2024

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.