Creating Service Forms

Service forms in Service Panel are used for collecting data from users. Most commonly this is for creating and updating account data, but they may be used for virtually any triggered action.

Forms are managed in Settings -> Service Panel -> Service Forms.

Initialize a Form

Each form must have a unique Name which identifies it. The Label field gives the localized display name of the form. A form can optionally have an icon to give visual context.

The Virtual Silo for the form identifies what Virtual Identity Silo objects must be in to be bound to the form. The Virtual Silo is optional, but without it a form cannot be bound to an identity, and reference based audiences will not work without it.

The next few settings control return to a started form:

• Save for Later – Enables the save for later feature so a form can be started and resumed
• Enable Anonymous Link – If set, when a form is saved an anonymous cipher link will be generated. A user going to the link will be able to access the partially completed form even if they're not logged in. Once the form is saved in a partial state, the workflow engine can be used to send a message with the link. NOTE: when accessing a form with a cipher link, audiences for the form are disregarded. However, only users in the audience roles for the form can instantiate it.
  • Here is a sample trigger rule: And(Name == "ResetPassword", Not(Completed))
  • Here is a sample templated value: Use this link to launch the <a href="[AnonymousCipher]">Reset Password form</a>
  • If an anonymous form is instantiated with a MIM DevTest Fixture (as is commonly the case), it may be necessary to use the ReplaceString() method on the cipher link to switch the domain from the Identity Panel host to the Service Panel host.
• Saved Form Expiration – Indicates how long a Save for Later or Anonymous link form can be accessed before it expires. NOTE: on expiration the form is NOT removed from the Service Forms database, meaning it can still be viewed in reports. However it can no longer be loaded in Service Panel.

Form Audiences

Forms may have a list of Role and Reference based audience rules. If a form has a referenced based audience, the audience decision is based on the virtual identity bound to the form when it is instantiated. The form can only be bound to identities in the selected Virtual Silo. Identities are bound based on the activation URL for the form (or by the settings in the MIM DevTest fixture or API call used to activate the form). This is accomplished using the identity=<id> or self=true URL parameters.

Data Sources

Any form that uses selection based form controls will either have embedded data sources or used shared data sources. See the data sources article for details.

Customizing Form Results

Normally when a form is submitted successfully the user is presented a basic success message and a hyperlink to return to the home screen:

It is possible to customize (and localize) this text using the form success settings. This includes the page title, the success message and an optional hyperlink to another page. The provided text may NOT contain HTML. All markup will be escaped.

Form Pages

Form Pages provide a way to break a form up into multiple stages. All forms must have at least one page, and each page must have at least one input, even if that's only a hidden label. Pages are listed as steps across the top of the form view, and all forms have an implicit final Submit step.

Pages also allow data submitted on one step of a form to influence data sources, labels, default values, and other rule templated aspects of subsequent page steps.

a form page must have a Name and a Label. The Name is non-localized and determines how the data is referenced in workflows, fixtures, etc. For example, to access an accountName input on a page name General, you would use the rule: Data.General.accountName. Note that form Sections and Input Rows (see below) are purely presentational and do not appear in the form data model for accessing values in workflows.

Labels are localized and support rule templating. The label is used to identify the form in the user interface. The Form Label and the Page Label are combined to make the title of the form page. If you don't want to display both values, you can make the Form and Page labels match to show only a single title value.

Each page can have an optional description. It is also possible to customize the Next and Back buttons for navigating between pages, and typically you will want to customize the final Next button to say "Submit" or something similar.

You may optionally select the "Expander" checkbox to convert the sections on the form page from cards into an accordion expander list. This is best reserved for edit forms with a large number of optional inputs where the user may only need to change a few values.

Form Sections

The next organizing layer within a form page is form sections. A form section optional label, icon, and description elements. There is also an "Expanded" checkbox to indicate that a section could be pre-expanded when displayed as an accordion list.

Form sections may have their own audience list to allow the section to have a narrower audience than the form page. Form sections are the most granular level at which audiences may be customized. NOTE: supplying ANY form section audience will ALWAYS hide that section from users that are accessing the form via an anonymous cipher link.

Within a section are input rows containing the actual form inputs. An input row provides a way to put row-breaks between inputs, even when those inputs would fit on a single line because their size does not consume the whole 12-grid. The header of an input row in the settings interface will be populated with the name of the contained inputs, but is only updated after a page load/refresh.

General Input Settings

There are some basic settings shared by all input types:

• Name – Required, non-localized, lists the name of the input that the data is bound to and accessed by with the rule engine. Supported characters are A-Za-z0-9 -
• Size – Required, space used by the input on a 12 grid scale. May be any number from 1-12.
• Label – Required, supports Rule templating. This is the user displayed name of the input element. This value is localized. NOTE: an actual Label Input uses the DefaultValue property to display text. The Label property is hidden, and always initialized to "NA". DefaultValue is used instead of Label because the value produced is often needed in the submitted form data.
• Hint - Optional, supports Rule templating. This is displayed underneath the input. For most input types it is only displayed when the input receives focus. It allows additional help or prompt text to be attached to the input.
• Enabled – Optional, if blank true is assumed. This is treated as a Rule value NOT a templated value. Can be used to present the input in a disabled/readonly state.
• Visible – Optional, if blank true is assumed. Used to hide the input, commonly based on data entered on a previous page. (e.g. Data.General.employeeType == "Contractor")
• Default Value – Optional, if specified will pre-initialize the input. Commonly set to a value from an identity bound to the form. May be used for account Edit forms, and to capture values on hidden inputs that may be needed in workflows. NOTE: The Default Value may be just a string value, or it may be templated. However, unlike other template values which may have rules inserted anywhere in their text, with Default Value the entire value must be a rule wrapped in square braces. This limitation allows values produced by the rule to carry a datatype matching the return value of the rule, rather than always being a string value.
  Examples:
  Return a virtual attribute from the bound virtual identity: Identity.Attributes.Account Name
  Return an attribute from the Parent Silo object of the bound virtual identity: Identity.Parent.Attributes.sAMAccountName
• Prepend Icon and Append Icon – Optional, supports templating, display a Material Design icon attached before or after the input
• Color – Optional change the input focus color (e.g. text box outlines, active label color, datetime calendar color etc.) from the default of Primary to something else. May be one of the theme colors or a named Material Design color.
• Encrypt – Optional checkbox, when selected the value of the input will be encrypted prior to being saved in the database, and prior to triggering workflows. To access an encrypted value from a workflow, use the Decipher(value) function (defined in Special Value functions).
  NOTE: Decipher does NOT simply return a plaintext version of the value. Instead it makes a placeholder wrapper around the value like this: [ec:<value>]. This value is then replace with the plaintext version of the value by the workflow engine when the workflow is executed by the Panel Service agent. This behavior allows the value to be redacted in the saved workflow history. It also means that when passing encrypted values to MIM Test Fixtures via the workflow engine you must explicitly create a separate Memo for each encrypted value, rather than simply passing the entire form [Data] structure.
• Rule Validation – Allows providing a rule engine rule that considers the entire form state. If the rule returns a string this will be treated as a validation error message. For localization, the entire validation rule is localized. NOTE: rule engine validation is only performed server side, so the error message will not be displayed until the user attempts to advance to the next page. One example of rule engine validation is to assert that two password input fields have the same value:
  If(Data.Change.Password == Data.Change.PasswordConfirm, null, "The two passwords must match")

Available Input Types

• Autocomplete – Filtered selection box, supports single and multi-select
• Label – Simple textual display for prompts, previewing data, and capturing hidden values for workflows
• Checkbox – Simple boolean input
• Checkbox List – Bind to a datasource to allow multi select with checkboxes
• Combobox – Filtered selection box with user extensible input, supports single and multi-select
• Date Picker – Choose a date, supports range constraints and either full calendar or text-box triggered views
• Identity Select – Choose single or multi-value identity references from a select picker
• Identity Table – Table and search based input for working with larger numbers of references
• Password – Password input text box. Encrypt flag is always selected
• Phone Input – Special case text box for inputting and validating international phone numbers
• Radio – Bind to a datasource to allow selecting one of a range of options. Works best with relatively small data sources
• Select – Simple select dropdown, supports single and multi-select
• Text – Basic text box input
• Textarea – Multi-line text box input
• Time Picker – Supports choosing a time from a clock face. Allows range constraints, 24 and 12 hour mode, and either a full clock, or text-box triggered views
• Toggle Switch – Alternative UI option to checkbox