Using Forms Smart Values

[#1]

This article is designed to assist users in utilizing the new Forms Smart Values. With these, you can now manipulate form information effectively using smart values.

For more information, please refer to the features below:

•  JSDCLOUD-10697 - Forms Automation: Access form fields with smart values (smartvalues)

These smart values allow you to access and manipulate data from forms and fields, providing enhanced automation and reporting capabilities.

Retrieve Submitted Form Data

 Note: Only smart values on forms that use the form submitted trigger can be accessed in this topic.

Accessing Forms with Smart Values

When employing the "Forms Submitted" automation trigger, you can retrieve forms associated with an issue using {{forms}}. This formats the forms into a list, which can be utilized within an automation rule. To target a specific form within this list, use automation list smart values.

Example: If the most recently submitted form is named "Purchase Order Request", utilizing {{forms.last}} will yield the formTemplateID associated with the "Purchase Order Request" form, for example “d6d3a06b-44c4-46aa-b58c-9a46743898dc".

Accessing Form Fields with Smart Values

To extract a smart value from a form field, you must know both the field type and its unique field key. This key can be customized within the form's configuration panel and is case-sensitive, including any spaces.

Example Automation Rule: John wants to automate a comment addition with purchasing total each time an "Purchase Order Request" form is submitted. First, he ensures the "Total" field has the field key total. He sets up an automation rule using the "Form Submitted" trigger for "Purchase Order Request" and includes the action "Comment on Issue", inputting {{forms.last.formFieldKey}}. For example:

Dear valued customer, the total amount is: {{forms.last.total}}

This ensures that the total value are added as a comment upon form submission.

Field Types and Their Smart Values

• Text Fields: Supports Short Text, Long Text, Paragraph, Email, and URL. Use text string formatting {{forms.last.Text Field}}.

  • Example: If a field with the key Summary contains "Jane Doe", {{forms.last.Summary}} returns "Jane Doe".

• Choice Fields: Includes Radio Buttons, Checkboxes, Dropdown, Multiselect Dropdown, Cascading Dropdown, and Assets. Use list formatting for these fields.

  • {{forms.last.Choice Field.last}}: give you the last selected item
  • {{forms.last.Choice Field.id}}: give the comma-separated list of the selected item ids
  • {{forms.last.Choice Field.label}}: give you the comma-seperated list of the selected item labels

  • Example: If the selected choice in a field with key Location is "Sydney", {{forms.last.Location.label}} returns "Sydney".

• Date Fields: Applicable to Date, Date & Time, and Time fields. Format as text.

  • Example: If a date field with key Due date is set to "10/01/24", {{forms.last.Due date.fullDate}} returns "Wednesday, October 1, 2024".

• Number Fields: Use for Number field types and format as numerical values.

  • Example: If a number field with key Invoice has "100", ${{forms.last.Invoice}} returns "$100".
     Please be aware that, unfortunately, the {{.asCurrency}} feature is not currently supported in Forms.

• User Fields: Includes Single User and Multiple Users fields, formatted as user data.

  • {{forms.last.User Field.accountId}}
  • {{forms.last.User Field.displayName}}

  • Example: If a user field with key Manager has "John Doe", {{forms.last.Manager.displayName}} returns "John Doe".

• Attachment Field: Use list formatting for Attachment fields.

  • {{forms.last.Attachment Field.id}}
  • {{forms.last.Attachment Field.name}}

  • Example: If an attachment field with key Upload resume has the file "Jane Doe CV", {{forms.last.Upload resume.name}} returns "Jane Doe CV".

• Accessing asset objects:

  • {{forms.last.Asset Field.id}}
  • {{forms.last.Asset Field.label}}
  • Same as choice fields, a list of the selected asset objects:
    

    [
      {
        "id": String, // Asset object id
        "label": String // Asset object name
      }
    ]

This will work as I demonstrate on the screen recording below:

Retrieve Form Data

Accessing Smart Values Without the "Forms Submitted" Trigger

Use {{issue.forms}} to access the forms in an issue when using any Issue Automation triggers (issue commented, issue updated, etc).

Therefore, forms can be accessed using {{issue.forms.formTemplateID}}, utilizing automation list smart values. These forms are organized by their formTemplateID (akin to Universally Unique Identifiers, or UUIDs), which can be retrieved through the Forms REST API or via the Forms smart value {{issue.forms}}.

---

What should I do if I'm using the {{issue.forms}} syntax and no formTemplateID is being returned?

It’s likely that the form you’re using is an older version that hasn’t been updated in a while, which means it still uses the Proforma data structure format. For instance, I have a form that was last updated in 2022:

• In this structure, the form template ID is not present:
  
• To resolve this issue, you can simply update the form by accessing its edit screen and clicking the 'Save changes' button. You don’t need to make any modifications to the form itself:
  
  
• This action will automatically update the form’s structure and generate a template ID for it:
  
  

---

Example Automation Rule: John aims to add an total of a order purchase from a specific form as a comment on an issue. He ensures the "Total" field in the "Purchase Order Request" form has the field key total. He sets up a manual trigger automation rule, using {{issue.forms.formTemplateID.formFieldKey}} to comment with the total value of the order "Purchase Order Request" forms exist on an issue. For example:

Dear valued customer, the total amount was updated to: {{issue.forms.d6d3a06b-44c4-46aa-b58c-9a46743898dc.total}}

This ensures that the total value is added as a comment upon the form update.

Access a particular form or manage multiple forms

• Since {{issue.forms.formTemplateID}} gives you a list, you can access a specific form using:

  • {{issue.forms.formTemplateID.get(0)}} - First form

  • {{issue.forms.formTemplateID.get(1)}} - Second form
  • {{issue.forms.formTemplateID.get(2)}} - Third form
  • etc…
    

     Tip! To retrieve data from a form field on a specific form, consider using one of the following approaches:
     - {{issue.forms.formTemplateID.get(0).formFieldKey}}
     - {{issue.forms.formTemplateID.formFieldKey.get(0)}}

• The template form ID can be retrieved from either:

  • The public API Get project form index

  • Or by simply adding a log action to your automation rule using the smart value: {{issue.forms}}

Accessing form statuses

• Currently, you can check the form statuses using the {{submitted}} property, which returns either true or false:

  • {{issue.forms.f7142b07-d3a4-4522-a7e4-8799d526e0a6.get(0).submitted}}

  • {{issue.forms.f7142b07-d3a4-4522-a7e4-8799d526e0a6.last.submitted}}

The glad tidings is that we already have an item in our development backlog aimed at improving this as well:

•  Forms Smart Values: Improve the access of forms core attributes

Please refer to the screen recording below for a demonstration of how this works:

Access field values using question IDs instead of Field keys

When a field key is added to a form template, only new forms created after the addition will include this new field key in their properties. To access fields in existing forms that lack the new field keys, you can use their IDs instead using:

• {{issue.forms.formTemplateID.get(x).questionID}}.

IDs are always available; they are generated when a new field is added to a form, are unique, and can be used even if field keys are present.

Regarding form functionality, each issue form retains a snapshot of the project form (template form) at the time it is added to an issue. Therefore, modifications to a project form will not affect issue forms created from that project form before the changes were made.

For instance, consider a “Purchase Order Request” project form with a “Total” field. If you add this form to an issue and then update the “Purchase Order Request” project form to assign a unique field key “total” to the “Total” field, this field key will not be available in the existing issue form added before the update. Consequently, you cannot use 'total' to access the field value in that issue form.

In these situations, you can access the "Total” field using its question ID in various ways, utilizing the Form smart value mentioned above (where the question ID for "Total” is “88”):"

{{issue.forms.d6d3a06b-44c4-46aa-b58c-9a46743898dc.get(0).88}}

Browser's network tab:

• To find the question ID, open the issue form in the issue and inspect the browser's network tab:
  

Forms REST API:

• To find the question ID, use the Get form method:
  

For any enhancements or future updates, stay connected with the Jira development community and keep an eye on the development backlog for ongoing improvements.

Thank you for reading, and we hope this guide assists you in maximizing the potential of Forms Smart Values in your projects.

[YY Brother]

Wow, our days of using {{#issue.properties."proforma.forms.i1".design.questions.21.choices}} have finally come to an end!

Thanks @Bruno Altenhofen 

[Tomislav Tobijas _Koios_]

Our team was quite relieved when this was announced 😅

Thanks for the great article @Bruno Altenhofen !

[Yichi Zhang]

Thanks a lot @Bruno Altenhofen We've been expecting the solution for a long time.

[Dimitrios Kouroumichakis]

THANK YOU :) 

[Stefan Froehlich]

Hi @Bruno Altenhofen

thanks for this solution. Quick question on conditional fields, is there a way to display those only when there are values assigned to it (within the automation maybe?) or is this not possible at all?

Thank you,

Stefan

[Vydrathi Hegde]

Hi @Bruno Altenhofen , Great solution . I have a question do we have the option extract the attachment file itself from the form?  or is it just the Id & name ?

[Bruno Altenhofen]

Hey @Stefan Froehlich 

Currently, Jira Forms allows you to create conditional logic to display or hide fields based on the values of other fields. However, displaying a field only when it is populated is not a feature that is available directly within the form settings.

You can use the built-in conditional logic in Jira Forms to show fields based on the values of other fields. While this approach doesn't directly support showing a field only when it contains a value, it can respond to changes in other fields.

For more advanced needs, you might consider using Jira Automation to perform actions based on field values. While it's challenging to "hide" fields using automation directly—since automation typically involves modifying issue data rather than the form's presentation—it can still be a useful tool for certain scenarios. Therefore, considering this a complex requirement, you might explore options like using a scripting app such as ScriptRunner with the Jira API to tailor the form behavior to your needs.

Thanks!

[Bruno Altenhofen]

Hi @Vydrathi Hegde 

When working with forms and attachments, the typical interaction through the user interface or automation rules allows you to access metadata about the attachments, such as their IDs and names. However, directly extracting or downloading the attachment files themselves programmatically from a form or through automation isn't directly supported in the same way.

Therefore, if you need to programmatically access the attachments, you can use the Jira REST API. With the API, you can retrieve attachment details using the attachment ID and then download the actual file. This requires scripting or programming to handle the API requests.

Thanks!

[Stefan Froehlich]

Thank you @Bruno Altenhofen for your response!

[Dan W]

Are we able to use these smart values to prefill a form field from a portal link?