From the Template Library 

ProForma includes a library with hundreds of ready-to-use form templates. These templates can be used as is, modified to meet your teams' practices or embedded in another form. 

To use a template from the library, open the form builder and select the Insert Form option.

A sidebar will be displayed.

To browse templates you can:

• Select All to see all available templates.

• Narrow your search by selecting the relevant team. Clicking the … will show additional teams.

• Use the search bar to find a specific template or process.

Click on a template to preview it.

Click Insert Template. The template will be open in the form builder. Make any desired modifications and click Save.

Note that if you are embedding a template into an existing form, the template will be added at the bottom of the form. You can then drag and drop the form elements to the desired location.

Adding, Copying, Moving and Deleting Form Elements

There are multiple ways to add, copy, move and delete elements (formatting options, section or questions) on your forms:

Adding Elements

To Add a form element (formatting options, section or questions):

To add a form element, select the desired item from the toolbar. Or type a / followed by the first letters of the item you wish to insert. 

Copying Elements

To copy a question, click on the question to see a blue outline. Then use keyboard short cuts to copy (Cmd/Ctrl C) and paste (Cmd/Ctrl+V) the question.

Moving Elements

To move a form element, click on the item to see a blue outline. Use the icon on the left to drag the item to its desired location.

Alternatively, you can relocate a question by cutting (Cmd/Ctrl X) and pasting ( Cmd/Ctrl V) it.

Deleting Elements

To delete an elemet, click on the item to see a blue outline, then click on the garbage can icon. Alternatively, you can use the delete/backspace buttons on your keyboard.

Question types and validation

Question type	Form question and validation options
Short Text	Validation: Response required. Minimum and Maximum: character and words limits. Format: Regex pattern and validation message. Linked Fields: Can be linked to Jira single or multi-line text fields.
Long Text	Validation: Response required. Minimum and Maximum: character and words limits. Format: Regex pattern and validation message. Linked Fields: Can be linked to Jira single or multi-line text fields.
Paragraph	Validation: Response required. Minimum and Maximum: character and words limits. Format: Regex pattern and validation message. Linked Fields: Can be linked to Jira single or multi-line text fields.
Email	Validation: Response required. Minimum and Maximum: character and words limits. Linked Fields: Can be linked to Jira single or multi-line text fields. The ProForma email field functions as a text field that automatically validates for an @ character.
URL	Validation: Response required. Linked Fields: Can be linked to Jira URL fields. If the Jira administrator has enabled the URL Questions on the configuration page, responses to URL fields will be rendered as clickable links when the form is in view mode.
Radio Buttons	Validation: Response required. Required choice: An option users are required to chose. Linked Fields: Can be linked to Jira radio buttons fields or single select lists. The ProForma field will inherit the choice list options from the linked Jira field.
Checkboxes	Validation: Response required. Required choice: An option users are required to chose Minimum and Maximum number of choices: Limits how many choices may be selected. Linked Fields: Can be linked to Jira multiple choice (check box) fields or multiple choice select lists. The ProForma field will inherit the choice list options from the linked Jira field.
Dropdown	Validation: Response required. Required choice: An option users are required to choose. Linked Fields: Can be linked to Jira single choice (radio buttons) fields or single choice select lists. The ProForma field will inherit the choice list options from the linked Jira field.
Multi-Select Dropdown	Validation: Response required. Required choice: An option users are required to choose. Linked Fields: Can be linked to Jira multi-select dropdown fields or checkboxes. The ProForma field will inherit the choice list options from the linked Jira field.
Date	Validation: Response required Earliest and Latest date: Limits on date selection Linked Fields: Can be linked to Jira date fields. Note that currently, ProForma fields cannot be linked to the Due Date field. ProForma forms use a calendar-picker widget. Alternatively, users may choose to manually type a properly formatted date. Dates are displayed in correspondence with the locale the user has selected in their language settings. For example, select English (US) to see dates in the mm/dd/yyyy format. How ProForma handles timezones ProForma date and time questions do not adjust for timezones, unless they are linked to Jira fields.  An unlinked date/time question on a ProForma form will show the data that was entered by the users, regardless of whether the user and the agent are in the same timezone. If a customer in New York submits a form and answers 5pm, the agent in Houston would see 5pm as well. The behavior is different for date & time questions linked to a Jira field. When linked to a Jira field, the time is shown in the local time of the user. o In this case, the form field that shows 5pm in New York will show 4pm in Houston. You may wish to use the Description property to provide explanatory text/instructions to your users.
Date and Time	Validation: Response required. Earliest and Latest date/time: Limits on date/time selection. Linked Fields: Can be linked to Jira date/time fields. Note that currently, ProForma fields cannot be linked to the Due Date field. ProForma forms use date and time-picker widgets. A user may choose to manually enter properly formatted date or time. Manually entered times must be formatted HH:MMam or HH:MMpm. Dates are displayed in correspondence with the locale the user has selected in their language settings. For example, select English (US) to see dates in the mm/dd/yyyy format. How ProForma handles timezones ProForma date and time questions do not adjust for timezones, unless they are linked to Jira fields.  An unlinked date/time question on a ProForma form will show the data that was entered by the users, regardless of whether the user and the agent are in the same timezone. If a customer in New York submits a form and answers 5pm, the agent in Houston would see 5pm as well. The behavior is different for date & time questions linked to a Jira field. When linked to a Jira field, the time is shown in the local time of the user. o In this case, the form field that shows 5pm in New York will show 4pm in Houston. You may wish to use the Description property to provide explanatory text/instructions to your users.
Time	Validation: Response required. Earliest and Latest time: Limits on time selection Linked Fields: Can be linked to Jira date/time fields. ProForma forms use a time-picker widget that displays half hour increments. Alternatively,  a user may choose to manually enter a time. Manually entered times must be formatted HH:MMam or HH:MMpm. How ProForma handles timezones ProForma date and time questions do not adjust for timezones, unless they are linked to Jira fields.  An unlinked date/time question on a ProForma form will show the data that was entered by the users, regardless of whether the user and the agent are in the same timezone. If a customer in New York submits a form and answers 5pm, the agent in Houston would see 5pm as well. The behavior is different for date & time questions linked to a Jira field. When linked to a Jira field, the time is shown in the local time of the user. o In this case, the form field that shows 5pm in New York will show 4pm in Houston. You may wish to use the Description property to provide explanatory text/instructions to your users.
Number	Validation: Response required. Minimum and Maximum: minimum and maximum number values. Whole numbers only: Do not allow decimal numbers.  Linked Fields: Can be linked to Jira number fields.
Single User	Type: Two types of user search options are available: Default Jira user search – This option is selected by default and means that only logged-in Jira users can search for users. This search will not work for customers and anonymous users on the JSM portal. Users with Browse Project permission – Both Jira and Portal users can lookup Jira users who have the Browse project permission for this project. Validation: Response required. Linked Fields: Can be linked to Jira single user picker fields. To search for a user, begin typing the user's name in the field. The field will match the username (not the email address). Editing of user lookup fields is not supported in ProForma Lite. Also note that a ProForma user picker field that is linked to a Jira user picker field, will not reflect any constraints (filtering to specific groups) that exist on the Jira field). This limitation will be addressed in future development.
Multiple Users	Type: Two types of user search options are available: Default Jira user search – This option is selected by default and means that only logged-in Jira users can search for users. This search will not work for customers and anonymous users on the JSM portal. Users with Browse Project permission – Both Jira and Portal users can lookup Jira users who have the Browse project permission for this project. Validation: Response required. Linked Fields: Can be linked to Jira multiple user picker fields. To search for a user, begin typing the user's name in the field. The field will match the username (not the email address). Editing of user lookup fields is not supported in ProForma Lite. Also note that a ProForma user picker field that is linked to a Jira user picker field, will not reflect any constraints (filtering to specific groups) that exist on the Jira field). This limitation will be addressed in future development.

Question Properties 

When you create a question in the form builder, a sidebar will display allowing you to set the question properties:

• Label – The text of the question that will appear to the user.

• Description – A place to provide the user with supplementary information such as examples, recommended formatting or field level instructions.

• Default Values – The form builder lets you set a default value for any field. Note that default values are not available in the Legacy form builder.

• Linked Jira Field – A list of Jira Fields that can be linked to the ProForma field. Check out how to link ProForma fields to Jira fields

• Validation Options  – Validation options vary by question type. See the table below for details.

• Question Key – The form builder includes question keys which allow form you to set an identifier for the question, making it easier to find the question in the JSON data structure.

Text questions have two additional properties:

• Regex: Pattern – This allows you to define a pattern of characters for your text fields. Learn more about regex

• Regex: Message if input is invalid –  The message users will see if their input does not match the defined regex pattern.

Choice questions also have two additional properties:

• Choices – The options a user will be able to choose from

• Data Connections –   A link to an external data source that will populate the choice list. Learn more about data connections

In the Legacy form builder, some question types are grouped together. Use the Style dropdown to select the desired option. This includes:

• Text  – Narrow or wide

• Choice – Single Choice, Multiple Choice, Dropdown

• Date – Date, Time, Date and Time

• User Lookup – Single User, Multiple Users

Making a Field Available for Linking

• Attachment

• Custom cascading choice lists (single or multiple)

• Custom next-gen people fields

• Due date

• Labels

• **Field created by other apps

Using Conditional Logic

1. Create a choice (radio button, checkbox or dropdown) question on your form. (Note that currently multi-select dropdown questions cannot be used to trigger conditional logic.)

2. Add a section anywhere below the choice question.

3. Click on the section divider. The properties panel will give you the option to have the section shown Always, or Conditionally.

   After selecting Conditionally you’ll be given a list of all the choice questions in the form (including questions that are part of previous conditional sections) which precede the conditional section.

   Select the appropriate question. A list of the choice options will be shown and you can select the choices that will trigger the section to be shown.

   Add the relevant questions and content to the section.

Data Lookups

1. Open the relevant form in the form builder.

2. Add a choice question to the form.

3. Enter the question label, description and validation as desired.

4. Use the Data Connection dropdown menu to select the appropriate connection. You will see data from the external source populate the choice list.

5. Click Save.
   
   

   

Form Settings

• Name  – Set the name of the form.

• Language –  The ProForma form builder supports 25 different languages. Use the dropdown box to select the language.

• When issue is created  – This setting lets you indicate if you would like to:

  • Lock the form to prevent changes after the form has been submitted

  • Automatically generate a PDF of the form and attach it to the issue when the form is submitted

• Recommended Form – You can also associate the form with a specific issue type. When an agent clicks Add Form on an issue of that type, this form will be listed as a recommended option.

• Jira Service Management Portal – For Service projects, use this setting to associate the form with a request type, making the form appear on the customer portal.

• Create Issue – If the Issue Forms feature has been enabled, you can associate the form with a request type or issue type. This will allow users to access the form directly from the Jira navigation bar. When the users submits the form a Jira issue will automatically be generated.

• Leave form open – If this options is selected, then the form will stay in an open state, allowing the customer to continue to add to and edit their responses after the request is created. Validation will be enforced when the request is created.

• Ignore validation – If you choose to leave the form open, then two more options will become available. Checking the Ignore validation option means the customer will be able to create the request even if required fields are left blank or their responses do not meet validation criteria. Validation rules will not be enforced until the the form is submitted.

• Hide submit button – If you would like a form to stay perpetually open, or to only allow a Service Management Agent to determine when the form is complete, you can choose to hide the Submit button. The form will remain in an open state and will be editable from the portal. Only an agent will be able to submit the form.

Form Automation

• Automatically add a ProForma form when an issue is transitioned to a new status

• Automatically transition an issue when a form is submitted

• Prevent an issue from being transitioned if a form is not attached to the issue, or if the forms on the issue are not submitted

1. Go to the Settings tab of the form builder and click Add Rule.

2. Give your rule a name.

3. You will see a series of dropdown boxes. Use the first dropdown box to indicate when the action should take place. An automated action can be triggered by the submission of a form, a workflow transition or a Jira workflow validator.

4. If the actions is triggered by a form being submitted, or by the issue transitioning to a new status, another dropdown box will ask you to indicate the issue/request type you would like the rule to apply to.

5. The next dropdown lets you place conditions such as specifying the issue’s current status, or if all of the forms on the issue have been submitted.

6. The final step is to indicate the action to be taken. This step may include the option to allow duplicate forms on the same issue, and to set the form that is being added to internal or external.

• At least one form is attached to the issue – configured in the Jira workflow

• All forms on the issue are submitted – configured in the Jira workflow

• A specific form is attached and submitted on the issue – configured in the form setting and in the Jira workflow

1. Go to a  Jira Settings > Issues > Workflows   

2. Click  Edit  next to the name of the indicated workflow

3. Click on the indicated transition and select the  Validators  tab

4. Click Add validator and select the appropriate ProForma validator from the list.

5. Click  Add.

Using ProForma Forms on Jira Issues/Requests

Viewing Forms

Form States

• Open  – Open forms have not yet been submitted or have been reopened to make edits. A user can fill out or edit open forms.

• Submitted   – A user can submit a form upon completion. Submitted forms will need to be reopened in order to be edited.

• Locked  –  Locked forms can only be reopened and edited by a user with Administer Project permissions.

Add a Form to an Issue or Request

1. When viewing an issue, expand the  Forms  section if necessary.

2. Click  Add Form.

3. A dropdown menu will show a list of available forms. Forms that have been recommended for the particular issue type will be shown at the top of the list.  Select the desired form. 

4. Click  Add.  The form will now be included on the issue. 

Submit a Form

1. When viewing the issue, expand the Forms section if necessary.

2. Click on the name of the indicated form.

3. Click  Submit, or if the form has been edited, click Save and Submit .

4. A dialogue box will open to confirm the that you want to submit the form.

Reopen a Form

1. When viewing an issue, expand the  Forms  section if necessary.

2. Click on the name of the indicated form. The form will open in the viewer.

3. Click on  Reopen button at the top of the viewer.

4. A dialogue box will open to confirm that you want to reopen the form.

Edit the Contents of a Form

To edit an open form:

1. When viewing an issue, expand the  Forms  section if necessary.

2. Click on the name of the indicated form. The form will open in the viewer.

3. Click on the  Edit  button.

4. A blue banner across the top of the form will indicate that you are in Edit Mode. Make the necessary changes.

5. Click  Save and Submit .

6. Alternatively, you can  Save  your work in progress and submit the form at a later time.

To edit a submitted form:

1. When viewing an issue, expand the  Forms  section if necessary.

2. Click on the name of the indicated form, The form will open in the viewer.

3. Click on the Reopen button and confirm that you want to reopen the form.

4. Click on the  Edit  button.

5. A blue banner across the top of the form will indicate that you are in Edit Mode. Make the necessary changes.

6. Click  Save and Submit .

7. Alternatively, you can  Save  your work in progress and submit the form at a later time.

Download a PDF or a XLSX of a Form

1. When viewing an issue, expand the Forms section if necessary.

2. Click on the  ... button for the indicated form.

3. Click on  Download PDF (vertical listing of field responses), Download Rich PDF (Formatted PDF of form responses) or Download XLSX.

Create a Jira Issue from a Form

1. Go to the Jira navigation bar.

2. Click on  Issue Forms .

3. Use the  Change  link to select the relevant project.

4. Select the relevant form from the form list, or search for the form using the search bar.

5. Fill out the form.

6. Click  Create . A Jira issue will be created.

Linking to a Form

1. Ensure the Issue Forms configuration is enabled.

2. On the Settings tab of the form, use the toggle to enable the form as an Issue Form.

3. Select the appropriate Issue Type.

4. Click on the Copy button to copy a link to your clipboard.

Reporting

Linked Jira Fields

Form Responses Spreadsheet

1. Navigate to Project Settings.

2. Click on Forms from the left hand navigation bar.

3. You will see a list of all forms in the project. Click on the … button to the right of the form name and select Responses. A spreadsheet rendering all of the responses to each from field will be downloaded.