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 that 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}}.

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…

• 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:
  

Atlassian Marketplace External Plugin:

• Alternatively, you can use the external plugin Entity Property Tool for Jira, which allows you to access all the properties of forms within an issue, even if the form has been deleted:
  

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.