Forms

Forms offer components that enable users to input information into a workflow, which can subsequently be collected and utilized throughout the workflow. Workflow Studio incorporates form data into a workflow through a compilation and publication process, creating a specific type of activity called a "Form activity." Upon publication, Form activities can be integrated into workflows, where Workflow Studio's drag-and-drop property binding capabilities facilitate the transfer of form data to and from other workflow objects during runtime.

Form Objects

Form Objects in Workflow Studio are divided into two categories: Primitives and RBAC Components. Primitives enable the inclusion of simple objects, such as drop-downs, calendar controls, and fields, on a form. Conversely, RBAC Components allow for the incorporation of properties from objects bound to EmpowerID-protected resources on a form. Each of these RBAC components can be employed to retrieve the properties of protected resources for use within a workflow.

For instance, if you need to capture data specific to a Person, you can add an RBAC Component for a Person object to a form. This allows you to integrate only the relevant properties (person attributes) into your form design, according to your data requirements.

Primitives

Rbac Components

Form Types

Workflow Studio offers two types of forms for workflow usage: User Input forms and User Decision forms. The choice of form depends on the desired functionality at a specific point in the workflow.

User Input forms – These forms allow users to input information and submit the data back to the workflow for use in subsequent activities. User Input forms appear to any user running the workflow at the point in the process where the form is placed. They can be used anywhere within a workflow and are often the first form encountered. For example, in a workflow that enables users to request resources or other actionable events, you can add a shape derived from a User Input form, allowing users to enter and submit their request details back to the workflow. The workflow then moves to the next step as dictated by the business requirements.
User Decision forms – These forms appear within a workflow when the process requires further user input or approval to proceed. User Decision forms should be used when a form needs to be routed to someone to provide information or make a decision. These forms offer routing options, create a workflow task for any "approvers" at that stage in the workflow, and send email notifications to the users when the form is routed to an approver for a decision.

Form Designer: The Form Designer enables you to visually design forms by dragging and dropping user interface components and controls onto the canvas. No coding is necessary, and you can create forms for various data types, from primitive types like strings to more complex types based on registered RBAC components. Once a form is published, a "Form activity" is generated and published to the EmpowerID Identity Warehouse, allowing you to use the form within a workflow.

Workflow Studio Form Designer Commands

Commands	Descriptions	Image

Commands	Descriptions	Image
New Tab	Adds a new tab to the form that is actively being edited.
New Section	Adds a new section to the form that is actively being edited.
Mask	Opens the Add New Mask dialog, which allows you to add a new Mask to the Components tree of the form that is actively being edited.
Validation	Opens the Add New Validation dialog, which allows you to add a new Validator to the Components tree of the form that is actively being edited. Validators force users to enter data in the format specified by the Validation Expression of the Validator.
Data Source	Opens the Add New Data Source dialog, which allows you to add a new Data Source object to the Components tree of the form that is actively being edited. Data Source objects allow you to bind form controls to objects in the EmpowerID Identity Warehouse.
Add Object	Opens the Add Object dialog, which allows you to add Primitives (Strings, Booleans, DateTime, etc) and Rbac Components (Account, AccountStore, Person, etc) to the Components tree of the form that is actively being edited. Once added to the Components tree, these objects can be dropped onto a form as properties for use in data binding.

Form Components

Form Data: Primitives (Other Objects) – primitive properties defined for use in a form. It allows you to place simple objects such as booleans, datetime controls, and string-based objects (i.e., fields, labels, etc.) on a form.

Form Data: RBAC Objects – EmpowerID component objects added to a form in order to drag their properties onto the designer.

Data Sources – EmpowerID objects and methods defined for use as data sources for form controls such as dropdown lists.

Validators – regex expressions that can be applied to form fields to validate data input – e.g., email format.

Masks – defined to allow masking values from view.

Approval Decisions – the decision buttons to enable for the form activity.

Adding Fields to the Form

You can place the Primitive or RBAC Objects onto the form by dragging them from the Components tree and dropping them onto the form within the Form Designer. By default, all the fields you place on a form will render as textbox field.

You can also move tabs, fields, and sections around on the form by dragging them.

Form Field Options

EmpowerID ships an ever-growing list of control types.
Each control type has different settings / standard properties.
Many control types support data sources such as dropdown lists and auto-completes.
Forms fields can apply complex logic to determine the conditions when they should be shown or hidden.

As a matter of default, the fields integrated within a form are initially set as text fields. To transform these fields into alternative controls, such as dropdown menus or radio buttons, follow these steps: right-click on the designated text field and proceed to select the Edit option. This action will prompt the emergence of the Field Configuration dialog box. Within this dialog box, navigate to the Control Types tab, whereupon you can opt for the desired control type. Certain controls are compatible with external data sources, exemplified by the dropdown control. When binding the dropdown control with a data source, it is imperative to establish its Standard Properties, which can be accomplished by accessing the Standard Properties tab.

Likewise, if you'd like to connect your control to a datasource, you can achieve this by heading to the Datasources tab. If you wish to put validation on your control, you can accomplish that by going to the Validators tab.

Type Of Data Sources

There are three types of data sources that Form supports.

Custom List
Generated
Static

1) Custom List

Utilize a custom list datasource when you are certain that the data within the custom list will remain unchanged over time or across different environments. For example, consider the number of months in a year or the count of days in a week. The Custom List datasource option is the most straightforward to implement. Assign a meaningful name to your Data Source Name, then select 'Custom List' from the DataSource Type dropdown and click the Add button. Input the value you wish to display to the user in the 'Name' column, and in the 'Value' column, insert the value destined for utilization within the code editor or saving it in the database.

2) Generated

We use Generated type of datasource when our intention is to retrieve data from a centralized location and link it to the controls on our form. Within the EmpowerID Web UI, we have the capability to create lists and associate these lists with our datasource, subsequently connecting the datasource to dropdown controls. Consider, for instance, a scenario where we have a department dropdown containing IT, Finance, and Marketing departments. If a future requirement arises to include an additional department, such as HR, into this dropdown control, we can seamlessly achieve this by directly accessing the List in EmpowerID Web UI and appending the new department (HR). Consequently, this alteration will seamlessly propagate to our dropdown control. Conversely, if we were utilizing a Custom List type of datasource, incorporating the new department would necessitate opening the form within the workflow studio, editing it, and subsequently publishing the changes—a comparatively more extensive process.

Now let’s understand how we can create a generated datasource.

Log in to EmpowerID Web UI. Then, navigate to the side menu and follow this path.

Admin → Miscellaneous → Lists

Click on the + button to create a new list.
Give your list a name, for example, DemoDepartment and in the Display Name field, type Demo Department. In the Set Type dropdown, select Department. You can choose any value from the dropdown; it's just a tag. Finally, click the Save button.
Now, navigate to the Find List page and search for the list you've just created. Once you find it, click on it.
Navigate to the Items tab, then click the + button to add the values one by one.
Now, access your Form within the Workflow Studio. Right-click on Data Sources in the components tree and select Add Data Source.
Add New Data Source dialog box will appear. Select the Create New Data Source option and click on the Next button.
In the 'Data Source Name' textbox, enter dsDepartment. From the 'DataSource Type' dropdown, choose the Generated option. For the 'Component Name' dropdown, select 'ListDataItemView,' and for the 'Method To Execute' dropdown, choose GetByListDataItemSetTypeNameListDataItemSetName(string listDataItemSetTypeName, string listDataItemSetName, string columnsToSearch, string textToSearch).
Now under the Expects Parameters select the string ListDataItemSetTypeName and from the Parameter Type dropdown select the ActivityPrimitive option. Repeat the same thing with the string listDataItemSetName and click on the Finish button.

Activity Primitive: What happens when we select an activity primitive? It will create two properties on the Form which you can access at the workflow level (When you place your form on a Workflow), and the name goes like this: DataSource_DatasourceName_listDataItemSetTypeName and DataSource_DatasourceName_listDataItemSetNameName. So, in our case it will look like this.

Create a workflow and give it any meaningful name and save it.
Now, go to properties tab of it and there create two properties of type string SetListName and SetListType
Go to EmpowerID Web UI navigate to Low Code/No Code Workflows → Low Code Workflows
Now select your workflow on which you have placed your form and click on your workflow name under the Display Name column. In my case workflow is HS_DisplayPeopleWF
Navigate to Request Workflow Parameters menu and click on the + icon and add two workflow parameters SetListName and SetListType make sure the name you assign to the properties in your workflow matche exactly with your workflow parameter name. In the SetListName give the name of your list which was DemoDepartment and in the SetListType enter the value Department.
Now your Generated Datasource is ready to use.
Suppose you have already added Rbac Component of type person into your form.
Drag and drop the department field on your form.
Right click on the department field and click on the Edit option. From the Control Types tab select the DropDownList
Now, navigate to the DataSources tab and select dsDepartment.
Now, proceed to the Standard Properties tab. In the 'Display Field' dropdown, choose FriendlyName and in the 'Selected Value Path' dropdown, select ListItemValue and click on Ok button.
This is how it will look like on the Form.
This is how your Department dropdown will appear in the EmpowerID Web UI, retrieving data from the List and populating the dropdown using a Generated Datasource.

Parameter Type

There are three Parameter types that are supported.

LinkedControl
Custom Text
Activity Primitive

LinkedControl

We utilize this parameter type to transfer data from any control within our form. In the image below, we are configuring the method parameter using a FirstName text box control on your form. Thus, any value entered in the FirstName text box will be assigned to the selected parameter.

Custom Text

When this option is selected, you can directly set the parameter from within the dialog box. Enter your value in the Custom Value textbox, as shown in the image below.

Activity Primitive

Activity Primitive → Will generate two properties on the Form which can be access from the Form’s properties tab after you place your form in a workflow and the naming convention goes like this DataSource_DatasourceName_SelectedParameterName. We have seen this above in Generated Datasource Demo.

3) Static

Static data sources are meant for showing a statis or un-changing list of objects.

Now let’s understand how we can create and use static datasource.

To demonstrate the static datasource, we require a Lookup control and a Form control. For this example, I will create a multi-select lookup control that displays all users in EmpowerID. Using the lookup control, I will select one or multiple records (Persons) and then display them on my Form using the Static DataSource.
Let's consider that we've created a lookup control to display users in EmpowerID. If you're unfamiliar with the process of creating a lookup control, please refer to the Lookup Control Lab. This is how my lookup control will appear in the Lookup Designer, as shown in the image below.
Now, in your form's components tree, right-click on 'Data Sources.' The 'Add New Data Source' dialog box will appear. Click the 'Next' button. In the 'Data Source Name' textbox, enter the name for your datasource, for example, DsPerson. From the 'DataSource Type' dropdown, select Static. In the 'Static Type' field, input the following code: List<'TheDotNetFactory.Framework.People.Components.PersonView>.
We use the above code because this datasource is intended to display a list of people in EmpowerID.
Now right click on data source name (dsPerson) and select the Create List Object for this DataSource option.
Note: I am using this “Create List Object for this DataSource” option because if I want to bind something dynamically than I will have to use this property.
It will add ListObject1 double click on it and rename it to ListPersons
Now drag and drop this ListPersons on to your form and it will look like this see below image.
Now, right-click on it and select the 'Edit' option. This action will open the Field Configuration dialog box. Next, navigate to the 'Control Types' tab within the dialog box, and then choose the 'DataGrid' control.
Navigate to Standard Properties tab and click on Set To GridType button and from the drop down select Person and it will add the commonly used columns for Person Object. Leave the rest of the configuration as is and click on the OK button. see below image.
After publishing your Form and Lookup Control, now drag and drop your Lookup control and Form on the workflow and connect it with lines.
Now write this code in the BeforeExecute event of your Form.
CurrentWorkflow.hS_UserInputFrmActivity1.dsPersonDataSource_Static = CurrentWorkflow.hS_DisplayPeopleLKActivity1.SelectedValuesAsVList.ToList();
Run your workflow in the Web UI and select multiple people from your lookup control and click on the Next button on your Lookup.
It will take you to your Form, where the DataGrid will display the users, you selected from the previous screen or Lookup.