We are thrilled to announce the release of the first set of new APIs for Forms (previously known as ProForma) in Jira Service Management Cloud (see docs). We welcome your thoughts on the APIs we’re launching and any suggestions for enhancements or additional integrations.
RFCs are a way for Atlassian to share what we’re working on with our valued developer community.
It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.
Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!
Summary of Project:
Our aim with this RFC is to:
- Introduce the available APIs and their potential applications;
- Gather your feedback on the possibility of developing a native Connect version of the API;
- Share our plans for the second stage of API development and solicit your input on whether our proposals align with your needs.
Here are the milestones for you to provide feedback directly here on the RFC.
- Publish: May 9, 2023
- Discussion open until: May 30, 2023
- Resolve and shareback: June 7, 2023
Problem
Two years ago, we acquired the ProForma marketplace app and have since been working to integrate its features natively into JSM Cloud. Until now, there were no public APIs for our customers, Solution Partners, or Marketplace Partners to work with. The demand for an API has been overwhelming (JSDCLOUD-10671) and ranks as the second most voted-for feature on JAC, just behind attachment fields (which are also under development). This initial API release for Forms in JSM Cloud matches the functionality found in the Data Center version and signifies the first of two development milestones.
The lack of APIs meant that marketplace apps, scripting tools, and advanced customers could not automate or seamlessly integrate forms into their custom processes or applications. The only alternatives were to use Automation for Jira with its limited set of triggers/filters/actions, or to interact with forms via the UI.
Parity first
We have received significant feedback on how Data Center APIs enable our customers and partners to build powerful solutions with Forms. As part of our Forms integration efforts, we have aimed to establish parity between forms in Cloud and Data Center. In particular, we see offering APIs for forms as essential, which is why we have prioritized creating parity between forms and Jira instead of developing numerous new features within forms.
Upcoming APIs:
The second milestone, currently underway, will allow Marketplace Partners to integrate Forms directly into their apps. For example, partners like Refined will be able to display and save forms within their apps. We also recognize that many of our customers, especially our largest ones, are unable to migrate to Cloud because Marketplace Partners cannot integrate with forms. Therefore, our priority is to remove obstacles for our partners, enabling our customers to transition to cloud solutions more easily.
Tip: Although we do not yet support partners creating and saving forms, partners can start working on rendering forms now, as the full data structure is accessible through Get Form endpoint.
Solution
This initial API release focuses on providing access to form controls, such as reopening and copying via the API, as well as granting access to form content in various formats, enabling the data to be utilized in other systems.
Authentication & Access
In this initial release, there are two supported authentication methods: basic auth with API tokens, and OAuth 2.
App developers should be choosing OAuth 2 rather than basic auth. OAuth 2 allows an app to act both as an app or as a user (in Forge), and is more secure than basic auth. OAuth 2 is automatically supported by Forge as well as Connect-on-Forge apps, and you can also use it to create three-legged OAuth integrations. Note however OAuth 2 won’t work with traditional Connect JWT apps. We are looking at adding support for Connect apps in a future release but would like your feedback on how important Connect support would be to you.
If you’re a Jira customer implementing scripts or custom tools you may prefer basic auth with API tokens. This is easier to implement but means your script or tool will always run as your own user, which makes it less suitable for apps.
Accessing Form Data
When working with individual forms attached to an issue, we now offer three different endpoints to access the form contents.
Forms Index (docs)
When interacting with forms on an issue, the first step is to access the index to determine which forms are available for that issue. The index endpoint returns a list of forms and their current states, allowing you to access the subsequent endpoints to extract the actual form.
XLSX and PDF (docs and docs))
You can now download form contents as either a PDF document or an XLSX document, replicating the formats available through the user interface.
Simplified Answers Array (docs)
This format returns the question keys and response values in a single JSON array. It is an excellent way to extract responses to fields within a form, and many of our Data Center customers have successfully used this endpoint to integrate form data into other systems as needed.
If a question key has been specified for a given field via the property within the question, the key will be provided in the output. Using the question key can make it much easier to identify a specific field and its corresponding response within the answers array.
RAW JSON (doc)
We have also enabled the extraction of the entire form as a raw JSON object. This feature is primarily intended to support marketplace partners who wish to integrate forms into other apps or systems. This format is generally not intended for users who want to extract or interact with the contents of a particular form.
This format contains all elements within the Atlassian document format, including questions, validation, and conditional logic, so that you can understand how we structure form data. If desired, you can render the content of this form using Atlassian Document Format renderers.
Form actions
These endpoints are designed to let you control the state of forms attached to an issue. They largely replicate the form controls available within the UI.
Reopen a form (docs)
Automating the process of reopening a form can be beneficial, such as when you want to reopen the form upon a specific status change.
Submit a form (docs)
Please exercise caution when using this action, as it will force the submission of an open form, regardless of its completion status or whether it meets all validation requirements. If a form is configured to lock upon submission, it will become locked, and only a project administrator or system administrator will be able to reopen the form.
Set form to internal/external (docs)
These endpoints allow control over a form’s visibility to help seekers via the request portal. Internal forms are visible only to agents or users who can access the issue within Jira Service Management, while external forms are visible to both help seekers and agents.
Copy form (docs)
This endpoint enables you to copy an existing form from one issue to another. This feature can be particularly helpful when coordinating with multiple teams working in different projects. For example, during the HR onboarding process, you can copy the original request form from the HR project to other projects, such as Facilities or IT, enabling them to work on it.
Limitations
Forms must have UUIDs
The Forms API works only with forms that have UUIDs assigned to them. Before 2023, forms were allocated simple incremental numeric IDs, but these have been deprecated in favor of UUIDs. To avoid changing the Forms API as we remove numeric IDs, we decided to hide them from the API entirely. The downside of this decision is that any form without a UUID cannot be accessed by the Forms API.
Form UUIDs were rolled out to all Jira Cloud instances in December 2022, so you can essentially assume that forms created from 2023 onwards will work with the API, while those created before that will not. In the coming months, we plan to run migrations to apply UUIDs to every form, but we have not committed to a specific date for this.
If you use the “get form index” endpoint on an issue that lacks form UUIDs, it will return a 412 error code. Please refer to our Error Codes documentation for an example of the expected format.
No Validation When Submitting a Form
In this initial release the “submit form” API does not perform a validation check before submitting the form; it will submit even if the form contains invalid answers. Users need to ensure the form is filled with valid answers.
Connect Apps Not Supported
Apps built using Connect JWT cannot access the Forms API because this initial release only supports basic auth and OAuth 2. We plan to add support for Connect in a future release but would appreciate your feedback on the importance of Connect support for your needs.
Note that if you migrate your Connect app to a Connect-on-Forge app, you may be able to use the Forms API now. Connect-on-Forge uses OAuth 2 authentication, which is supported by the API. However, it currently only supports app authentication and does not support user impersonation (see FRGE-686).
Asks
As we continue to improve and expand our Forms API, we greatly value the insights and experiences of our partners. While we appreciate any feedback you have on this release (even if it’s simply expressing agreement with no serious flaws), we’re particularly interested in learning more about the following aspects:
- What do you think about the current limitations of the Forms API, such as the requirement for UUIDs and the absence of validation checks upon form submission? Are these limitations significantly affecting your ability to integrate forms into your processes or applications?
- Are there other potential use cases or impacts of the Forms API that we haven’t anticipated? Are there any additional features or improvements you’d like to see in future releases to better support your needs? Are we missing any actions you need to work with forms?
- For those using Connect apps, is migrating to Connect-on-Forge a practical option for accessing the Forms API? Are there any major obstacles or concerns you have regarding this migration, such as the lack of user impersonation or other potential issues?
We encourage you to express your thoughts and share your experiences, as your feedback will help shape the future development of the Forms API. Our goal is to ensure we’re providing the most effective solutions for our partners and customers, and your input is invaluable in guiding our efforts.
Please don’t hesitate to share your opinions, ask questions, or suggest new ideas. We’re excited to learn from you and work together to make the Forms API even better.
Our commitment
This is not a set-and-forget post; we want to want to have a conversation with you and listen to your feedback. But we all have other work to do, so at a minimum, we commit to reviewing the comments and feedback we receive on this post every Monday. At the end of this process, we will do our best to reconcile the feedback and our own thinking and share back with you where we are likely to head.
Thank you,
Simon Herd (PM) & Charlie Gutjahr (Architect), on behalf of the 13 members of the PerFORMers team who are working on these initiatives.
