A form defines the information that can be included in messages or incidents when a person uses the form. Messaging forms also let you design the message so key details are presented to a recipient in a way that best suits their device and configure which response options recipients can choose from. The Forms tab of the workflow editor allows you to create forms, build out form content, configure message delivery options, and define who has permission to use it. Once you have created a form, you must deploy it before it can be used to send notifications or initiate incidents.
There are two types of forms:
- Messaging forms: Used send notifications to targeted recipients and any subscribers. They give you the ability to craft the messages that are sent and configure responses. They also create an associated canvas in Flow Designer. Once created, message senders can access the form from the Messaging page or from a dashboard widget. You can also configure a Create Event step in a flow to use the form.
- Flow trigger forms: Used in conjunction with a Form trigger on a flow canvas, these forms give you the ability to initiate flows by submitting the form (for example, from the Initiate Incident button or widget).
The Forms tab allows you to create an empty form and add it to the workflow.
- On the Forms tab, click Create Form.
- In the Create a New Form dialog box, specify a Name and optional Description.
- The name you give the form also becomes the default name of the Flow Designer canvas associated with the form.
- Select the type of form you want to create.
- Messaging form: Intended to send notifications, it also creates a canvas to house related flows.
- Flow trigger form: Intended to initiate flows, such as an incident resolution flow, by linking to the form in a Form trigger.
- Click Create.
Once you have created an empty form, you can build out the form content, configure delivery options and permissions, create flows, and deploy the form. For an overview of the steps required to build out your form, see Building and deploying forms.
When you delete a form, any flows, subscription forms or subscriptions that are based off the form are also deleted. If the form is associated with an active event then you will no longer be able to view the message content from the xMatters web user interface or mobile apps.
To delete a form:
- Locate the form on the Forms tab.
- Click the X icon next to the form name.
By giving forms accurate names and descriptions you can easily locate and manage them. The order of forms within each workflow on the Messaging tab is the same as their order on the Forms tab.
- To rename a form, click the form name and then type a new name when the cursor appears.
- To edit the form description, click the description and then type a new description when the cursor appears.
- To reorder the forms on the page, click the form's handle icon and drag it to a new position.
Once you've created an empty form, you still have some work to do. The following sections provide an overview of the steps you'll need to take to create the message content, define who has permission to send messages using the form, and configure advanced notification and handling options.
Create form content and delivery options
Once you have created an empty form, you can create the content of the messages and define message delivery options using the following tabs:
- Layout: The form's Layout tab allows you to configure the default recipients and handling options and specify which properties are available to be included in messages, incidents, or in the associate flow. Form elements and properties can be added and rearranged using drag-and-drop, and sections can be removed with one click. This tab also defines whether sending the form initiates a conference bridge (for messaging forms). For more information about working with the form layout, see Design the form layout.
- Messages (messaging forms only): The Messages tab is where you define the content of the email, SMS (text), and voice notifications. You can include properties in the messages if the properties are included on the form's Layout tab. For more information about creating message content for email, SMS (text) and voice notifications, see Define message content.
- Responses (messaging forms only): The Responses tab lets you define the response choices that are presented to message recipients and set the action xMatters takes when each response is selected. These actions may include escalating the event, terminating the event, or connecting the recipient to a conference bridge. For more information about defining response choices, see Define response options.
Each messaging form creates an associated flow canvas where you can use Flow Designer to build drag-and-drop flows, connecting the tools you use into orchestrated, fully automated toolchains to help you reduce the complexity of your incident management workflows.
Each flow trigger form can be associated with a Form trigger to initiate the connected flow whenever the form is submitted.
For the form and its scenarios to be accessible to other users, you must configure permissions.
Initially, only the user who created the form can use it (whether it's a messaging form used to sent notifications or a flow trigger form used to initiate incidents). You can give other users permission to use the form, either individually or to all users with certain roles (for example, Developers, Full Access Users). Note that the form must also be enabled before it can be used.
The Form Permission page also allows you to grant form senders the ability to create, edit, delete, and set scenario permissions for all scenarios associated with a form (to learn more about scenarios, see Define scenarios).
- On the Forms tab of the Workflows details page, click the menu beside the form name and select Sender Permissions.
- For flow trigger forms, you can also configure sender permissions on the associated form trigger.
- Start typing the name of a user or role in the search field and then click the user or role when it appears in the drop-down results list.
- Repeat this step until you have added all of the users and roles that should have permission to send this form.
- If you want to remove a user or role, click its red X icon.
- If you want the sender to have the ability to create, edit, and delete scenarios, select the associated check box in the Manage Scenarios column.
- Click Save Changes.
You can make it easier for message senders to quickly send notifications by creating pre-populated forms called scenarios. By anticipating common situations and creating scenarios that are already filled in with the appropriate values, you can reduce the number of choices a message sender must make when sending an urgent notification. For more information about creating scenarios, see Define scenarios.
If you would like to allow users to voluntarily receive notifications even when they aren't targeted by the event, you can create a subscription form. Subscription notifications can be configured so that they are "information-only" and do not include the ability to respond or take ownership of the event. Then can also be configures so that they are generated after an event has been open for a certain length of time.
For more information about creating subscription forms, see Subscription forms.
For messaging forms, you can notify specific users, groups, or dynamic teams when an event based off the form is initiated or concluded.
The following types of recipients can be added:
- Dynamic teams
Additionally, granular settings are available to configure which devices recipients receive notifications on. For example, you could specify that users in the system who have the Group Supervisor role should be notified on their Work Email devices when a given form is initiated.
- On the Forms tab of the Workflow Details page, click Edit beside the messaging form, and select Activity Updates.
- Start typing in the All Recipients search field and press Enter or click a result to add it to the list.
- If you want to narrow down your search results, click All Recipients and specify the category you want to search.
- After you have added the required recipients, select Initiation or Conclusion or both to specify when to notify the recipient.
- In the Devices to Notify area, do one of the following:
- Select All Devices to notify recipients on all of their available devices.
- Select specific device types on which to notify recipients (click the arrows to display additional device names within each type).
- Click Save Changes.
Before you can send notifications with your form, you must deploy it. Deploying a form makes it available for use. Depending on how you deploy a form, it may be available from the web user interface, xMatters mobile apps, the REST API, or a combination of those. If a form is not deployed, it cannot be used to send notifications and any associated flows won't run.
It is a best practice to deploy forms only to the locations where message senders need to access them; for example, deploy forms to the mobile app if message senders need to use them when they are on the go. Deploy a form to web services only when you want to initiate that form from another application.
- Click the drop-down list beside the form name. (The label for this list varies depending on the options selected.)
- For flow trigger forms, you can also set the deployment on the associated form trigger.
- Select the deployment options that you want to enable:
- Enable in Web UI: displays the form on the Messaging tab of the web user interface
- Enable in Mobile App: enables the form in mobile apps.
- Enable for Web Service: allows the form to be accessed by the REST API. For more information about using the REST API to initiate events, see the Events endpoint.