Change Form visibility using Automation and API

Bruno Altenhofen

Work has already started on the new Forms API functionality and we now have some experimental APIs available for use. So now Marketplace Partners can already integrate forms into their products.

For more information, please refer to the features below:

•  JSDCLOUD-10671 - REST API for ProForma/Forms in Jira

 

As a workaround to the feature request "Forms Automation: Automation to control the forms visibility", this article is meant to help users who want to use the new experimental features of the Forms API to automatically change the form visibility between internal and external.

 

Workaround steps:

• Create an Automation rule:
  • First, it will be needed to create an API token for the Web Request process. The Web Request needs your credentials and an API token encoded with base64.  For more information about this procedure, please refer to the documentation below:
    -    - Automation for Jira - Send web request using Jira REST API
    
    
  • We need to use the new API functionality of "Change visibility to external" or "Change visibility to internal" in a Put web request. For example:

    • To change the form visibility to external when an issue is transitioned:
      
      - The web method will be a PUT:
      

      PUT /jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form/{formId}/action/external

      - The cloudId will be your Cloud ID and not your Org ID. The easy way to get the cloud id is to go to https://<instance>.atlassian.net/admin/jira-service-desk/portal-only-customers. You will get the Cloud id in the URL (e.g.: https://admin.atlassian.com/s/<cloud_id>/jira-service-desk/portal-only-customers)

      - The issue ID or issue Key that you are using. To add the issueId or issueKey dynamically, you can use the smart value {{issue.id}} or {{issue.key}}

      - The formId will be in the universally unique identifier "uuid" format. To get it you can use the Forms properties structure below:

      https://<yourCloudURL>.atlassian.net/rest/api/2/issue/<issueId>/properties/proforma.forms

      

      - To add the formId dynamically, you can use the smart value below:

      {{issue.properties."proforma.forms".forms.uuid}}

      - The automation rule will be as shown in the screenshot below:

    • To change the form visibility to internal when an issue is transitioned:
      
      

      - The web method will be a PUT:
      

      PUT /jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form/{formId}/action/internal

      
      - The steps will be the same as above and the automation rule will be as shown in the screenshot below:

 Note: To call experimental methods the "X-ExperimentalApi" and "opt-in" header must be provided on the web request headers.

This workaround will work as shown in the screen recording below:

https://www.youtube.com/watch?v=IThVV-3nMgg

Kalin U

Very detailed and well written step-by-step tutorial, @Bruno Altenhofen Thanks for sharing! Recently I created an automation very similar to the one you have suggested, though with a twist.

I wanted to select and attach a form to a service ticket depending on a field selected by a customer. As the number of customers and field cases is large, I used the action "Create a lookup table" so that the table can hold the form template IDs (up to 20 key-value pairs). The custom field values are the keys, whereas the template IDs are the values in our lookup table.

When the custom field value matches a form template ID, the rule executes two "Send web request" actions one after the other:

1. attach a form to the Jira issue: POST request https://api.atlassian.com/jira/forms/cloud/<cloud ID>/issue/{{issue.key}}/form

{
"formTemplate": {
"id": "{{<uuid of the form>}}"
}
}

One needs to select the option in the action "Delay execution of subsequent rule actions until we've received a response for this web request" so that the next action can process the form instance ID (not the UUID of the form template).

2. change the visibility of the newly attached form: PUT request https://api.atlassian.com/jira/forms/cloud/<cloud ID>/issue/{{issue.key}}/form/{{webResponse.body.id}}/action/external

Without the second action, the form's visibility is set to internal by default, thus not visible to the customer in the portal.

Maybe the Forms API team can consider adding parameters to the "Add form" method by allowing setting the visibility in a single call. @Simon Herd 

---

(i) <value> - without the brackets <, >

(i) By the way, one doesn't need the header Accept:application/json for a successful request.