Define form properties

The Properties tab allows you to create properties such as Boolean check boxes, option lists, and number selectors that can then be added to forms and messages, including the Subject line of email notifications. Properties can be used only within the workflow for which they were created.

When you insert a property into a message, its configured value replaces the property name when a form is initiated. For example, if you add a text property to your messages named tollFreeNumber and its default value is 1-800-555-5555, this value replaces the property name wherever it appears when the form is sent.

If the phone number later changes to 1-800-555-1212, you can simply change the default value of the text property, rather than changing every instance of the property name in your workflow. The message sender can also change this value if required when initiating the message, and this modified value is then inserted when the message is sent.

The workflow builder also includes special predefined properties that allow you to personalize your notifications.

Once a property is added to a form, it can also be used by steps in a flow built off that form. For example, you could use a Boolean "customer impacting" property to automatically decide which step to take next or use an "Issue details" property to populate a step that creates a ticket in your service desk application.

Only properties that have been added to the form in the Layout tab are available when sending a message in the Messaging tab. You also need to add properties to the Layout for them to be available to flows based on the form.

The following screenshot shows the key elements of the Properties tab:

Add properties to forms and messages

Once you have created a property, it will appear in the Properties area on the form designer and the message editors. Note that properties can be used only once on forms (but multiple times on messages).

 

Boolean properties

A Boolean property allows you to specify default values of True, False, and None. For example, you might create a Boolean property named Emergency with a default value of False, which you then add to a custom section on a form. This allows the message sender to indicate whether this situation is an emergency when initiating the form.

Here's how this example property appears to the message sender:

When you send a message, the value is sent behind the scenes in lowercase: true, false, none. This is important to keep in mind if the property is used in Flow Designer (for example, in a switch step or sent by a webhook step to another system that's particular about its capitalization).

List box properties

A list box allows a message sender to select one or more values from a list the form designer has defined. For example, a list named City might include the values Menlo Park, Palo Alto, Mountain View, and Redwood City.

If you set a default value or values for the list, the message sender sees them listed as shown below:

The message sender can select any or all of the defaults in the list, delete the default values, or click Edit Values to select values other than the defaults.

If you do not set a default value, the message sender can click Add Values and select values from the list of available options. The user can search for values, select and deselect all values, then save their choices.

Combo box (drop-down list) properties

A combo box (or drop-down list) allows a message sender to click the list or type to search, and then select one of the values that the form designer has defined. For example, a list named Server Type might include the values Outlook Email, Oracle DB, EC2, and POP1.

Here's how this example appears to the message sender when they search for a combo box property:

Hierarchy properties

You can use a hierarchy property to create a series of dependent drop-down lists. This means that the choices made in higher-level drop-down lists determine which options are presented in lower-level lists.

For example, you could create a property named Region that includes two drop-down lists, labeled Country and City. In this case, once a User selects a country, the City drop-down list would become available and would be populated by cities defined for the selected country (for a more detailed example, see Hierarchy Property Example: Office Location).

Number properties

When it appears on a form, a number property allows a message sender to specify an integer value. A form designer can optionally configure a default value, as well as maximum and minimum values and units. For example, a property named Shipping Weight might have no default value, a minimum value of 1, and units of Lbs.

Here's how this example property appears to the message sender:

When added to a message, a number property is replaced by its specified default value when the form is initiated. This can be useful when a number is subject to change over time. For example, a property named Karen Smith - Office Number might initially have a default value of 74. If she later moves to office number 77, only the property value need to be changed, rather than all of the instances of the property in the forms.

Text properties

Text properties allow designers to add text strings of up to 20,000 characters to messages. Designers can specify a default value and a minimum and maximum size for the field.

For example, a text property field named Additional Info might be added to a form and its related messages to allow the message sender to add any current information that will help notification recipients understand the situation.

When a text property is added to a message, its value replaces the property when the form is initiated. For example, if you add a text property to your messages named tollFreeNumber and its default value is 1-800-555-5555, this value will replace the property name wherever it appears when the form is sent. If the phone number later changes, you can simply modify the value of the text property, rather than changing every instance of the property name in your workflow (of course, message senders can also change this value when initiating a form).

Here's how the latter example property appears to the message sender:

A subset of HTML tags can be used to format text properties in email notifications. For more information, see HTML in text form properties.

Password properties

Password properties allow you to add encrypted passwords to forms. Designers can specify minimum and maximum character counts (up to 255 characters), as well as whether to use field validation.

For example, assume that a third-party system needs to be updated for integration purposes but requires a user's credentials (including password) to call the third-party web service. In such cases, the required password value can be stored as a password property within a form.

When a password property is added to a message, its value replaces the property when the form is initiated. For example, if you add a password property to your messages named Emergency Conference Password, the value specified for the property will replace the property name wherever it appears when the form is sent.

Here's how the latter example property will appear to the message sender:

Security Considerations

Password properties are intended only to obscure passwords from casual inspection. This means that they will:

  • Be masked on forms when entering a value.
  • Remain encrypted while in transit to and from the integration agent.

However, through configuration or administrative permissions, it is possible to:

  • Send passwords out as plaintext.
  • View plaintext password values on the Events > Properties report.
  • Manually log the contents of a password field.
  • Retrieve the plaintext password value using the xMatters REST API.

Technical Context

xMatters users' passwords are stored in the xMatters database and encrypted using a one-way hash. By contrast, password property values must be stored using a symmetric cipher so xMatters can submit plain-text passwords to third-party systems and include plain-text passwords in notifications. As a result, a determined attacker could potentially retrieve password values from password properties.