Creating Form Definitions using trellispark UX Creator

Form Definitions provide a complete definition of the user experience that will be rendered by the trellispark dynamic page generation components. They are created in the UX Creator application, within a functionality.

Form Definitions are stored in the Forms tab of the functionality.

UX Creator > Functionality – Forms

Form Overview Tab

UX Creator > Functionality – Forms > Form Definitions – Overview

The form Overview tab is where the following form details are entered

• Form Name is a human readable identification label. We recommend naming your forms using a consistent naming convention that helps uniquely identify and organize your forms
• Form Type can be either a Concept, Portal, Application, or Wizard Form
  • Concepts are used to create and maintain records and are the most common type of form in the trellispark system. They also determine the life cycle (state transitions) of the records and control the actions or events that can affect them
  • Applications are a way to group specific functionality in the user experience. Users can be granted access to different applications from the User Administration app. They often consist of a set of child lists of the relevant concepts and allow the user to navigate and work on the concepts related to this application
  • Portals are used to provide selective access to functionality and data in the user experience. For example, you could use a Portal Form to define a Supplier Portal user experience. The Portal Form is used to restrict the visibility of data to only those records created under the portal context. For example, a user of the Supplier A portal can only see records created underneath Supplier A
  • Wizards are used to create a sequence of steps for the user to follow to accomplish a task such as data entry in a specific order, perform a multi-step action where all the steps are included in the wizard, etc.
• Page Layout is where you can specify the layout of the form, the default is Instance.
• Form Purpose is an optional field where you can specify a brief description of what the form will be used for, and what type of concept it describes. Best to describe the form in a way that your other team members will understand
• Tabs is where you can create and order the tabs you want to display on this form
• Conditional Filters is where you can define conditional filters that can be used by the fields on the form to determine field visibility.

Concept form types have the following additional fields:

• Form Display Name is a custom name that can be specified that will override the Form Name and display on the Left Navigation and in place of the form name.
• Allowed Generic Actions is where you can specify which generic actions (for example, export, import, move, etc.) can be performed on this form. By default, none of the generic actions will be allowed.
• Suppressed Command Bar Buttons allows you to specify which (if any) buttons located on the command bar will be hidden when this instance is loaded.
• Copy Instances determines if this form will be copied if the parent instance is copied. This is set to yes by default.
• Delete Prompt determines whether a confirmation window is displayed to the user if they attempt to delete the form. This is set to yes by default.
• Create instance TSQL is where you can specify a stored procedure to be called when an instance of this type is being created.
• Create Instance Target is where you can specify a target to make an API call when an instance of this type is being created.
• Create Instance Command is where you can specify a command to be executed when making an API call when an instance of this type is being created.
• Save instance TSQL is where you can specify a stored procedure to be called when an instance of this type is being saved.
• Save Instance Target is where you can specify a target to make an API call when an instance of this type is being saved.
• Save Instance Command is where you can specify a command to be executed when making an API call when an instance of this type is being saved.
• Enrich XML API is the API that will be called to enrich the XML on this instance.
• Enrich XML Command is the command that will be executed on the enrichment API.
• Suppress Breadcrumbs determines if the breadcrumbs will be suppressed on the instance.
• Build Instance Name is where you specify how the instance name of this form will be generated. This can be done by entering the data into a single field, or as a combination of several different fields. This allows the instance name to include a variety of useful data that a user may need to know when selecting which instance of the form to edit.
  The instance name can also include various separators either before or after each element that will make up the name, giving the user a degree of formatting control to ensure that the instance name will be human readable.
  In the case of the Application form, the instance name will be created from the Name field, followed by the Application Environment and Version fields, each separated within square brackets.
• Update Email determines the Email that will be used when the instance is updated.

Application form types have the following additional fields:

• Form Display Name is a custom name that can be specified that will override the Form Name and display on the Left Navigation and in place of the form name.
• Application Category is used to display the application form within a menu item group on the applications list on the left navigation menu
• Sequence is used to determine the order that the application will appear in the left navigation, the higher the number the lower the application will be on the list. If multiple applications have the same sequence number they will be also be sorted alphabetically.
• Icon URL is where you can specify the class name of the desired font awesome icon (An example for a trash can icon would be fa-light fa-trash-can)
  
• Allowed Generic Actions determines which generic actions are allowed on the instance.
• Suppressed Command Bar Buttons allows you to specify which (if any) buttons located on the command bar will be hidden when this instance is loaded.
• Which platforms can see this application? This field allows you to pick which platform the application is available on, if no platform is selected then it will be available on all platforms

Portal form types have the following additional fields:

• Form Display Name is a custom name that can be specified that will override the Form Name and display on the Left Navigation and in place of the form name.
• Icon URL is where you can specify the class name of the desired font awesome icon (An example for a trash can icon would be fa-light fa-trash-can)
• Suppressed Command Bar Buttons allows you to specify which (if any) buttons located on the command bar will be hidden when this instance is loaded.
• Portal/Read Concept is where you specify which concept form will provide the base of the portal user experience. To learn more about portal forms, go to Portal Form Definitions
• Portal Type determines if the portal form will be used for a single user or a group of users. Most of the time, this will be set to Group
• Build Instance Name is where you specify how the instance name of this form will be generated (like the concept form described above)

Wizard form types have the following additional fields:

• Finish TSQL is where you can specify the stored procedure that gets executed when a user has completed a wizard (selected the Done button). This procedure uses the standard parameter set containing:
  • SessionGUID
  • UserGUID
  • CurrentInstanceGUID
  • TargetInstanceGUID
• Height (%) is where you can specify the height of the popup window the wizard will appear in. the default is 90.
• Width (%) is where you can specify the width of the popup window the wizard will appear in. The default is 90.
• Finish Command Target is the target if calling an API when the Done button is selected.
• Finish Command Name is the command that will be executed on the API.
• Convert Wizard Data to Concept Form is the concept the wizard will convert into once complete.
• Apply Now determines if the wizard will be fully committed once complete or if another wizard will apply it later.
• Enable Exit Point determines if a custom exit point will be used to navigate the user using a non-default path.
• Exit Point Hierarchy determines where in the hierarchy to navigate to once the wizard is complete. This field is ignored if Exit Point Application/Portal is specified.
• Exit Point Application/Portal determines what application or portal to navigate to once the wizard is complete.

Organizing fields on forms using Tabs

Forms can have a set of tabs which will be used to sort the data fields within the form. If a form has no tabs, then a default tab (1) called the Overview tab is used to render any fields. All fields within the form should be created on tab 1. The generic form layout displays the tabs horizontally from left to right at the top of the form.

Tabs can be added to organize the Form Definition into multiple pages. Tabs are defined on the form’s Overview tab:

UX Creator > Functionality – Forms > Form Definitions – Overview > Tabs

You can specify the following attributes for each tab:

• Tab – number the tab from 1 to 40. The number determines the order that the tab will be displayed from left to right. Tab 1 is the first tab that will be displayed. For example, a tab 5 will be displayed to the left of a tab 10.
  • IMPORTANT NOTE: This tab number is referenced to determine which tab a field will be displayed. Please see Creating Fields using trellispark UX Creator
• Tab Name – the display name of the tab
• Number of Grid columns on form – Determines how many columns will be used to divide the form and field placements. The default value is 12. To learn more regarding how fields are mapped on forms refer to the Mapping fields on grid layout section lower in this article. This value will override the value specified at the form level.
• Override the name of the Tab with content? – This allows you to specify a target to call and the result it returns will be displayed as the name of the tab.
• Conditional Filters – this feature provides the ability to customize the visibility of the fields.
• Previous Step TSQL – This field is only applicable when the form type Wizard is selected. In this field you can specify a TSQL stored procedure to be called each time the user selects the Previous button while on this tab/step. This TSQL will be executed before the user returns to the previous tab/step in the wizard. This stored procedure uses the default standard parameters consisting of:
  • SessionGUID
  • UserGUID
  • CurrentInstanceGUID
  • TargetInstanceGUID
• Next Step TSQL – This field is only applicable when the form type Wizard is selected. In this field you can specify a TSQL stored procedure to be called each time the user selects the Next button while on this tab/step. This TSQL will be executed before the user is moved to the next tab/step in the wizard. This stored procedure uses the default standard parameters consisting of:
  • SessionGUID
  • UserGUID
  • CurrentInstanceGUID
  • TargetInstanceGUID
• Previous Command Target/Previous Command Name – This field is only applicable when the form type Wizard is selected. In this field you can specify an API call to be made each time the user selects the Previous button while on this tab/step.
• NextCommand Target/Next Command Name – This field is only applicable when the form type Wizard is selected. In this field you can specify an API call to be made each time the user selects the Nextbutton while on this tab/step.

• Tab Permissions – by default, a tab is visible to all users who can see the form. Each tab may also have explicitly defined Tab Permissions to determine whether a user may see the tab given the state of the record, the role of the user, and any custom business rules
  • As soon as a tab permission is created, by default the tab will be hidden unless the user is specifically allowed to view the tab
• Online Help – this is where you can enter helpful instructions or other information that a user will see when they are navigating to this tab and select the Help menu. The information can be formatted using the HTML editor and can include images and hyperlinks

IMPORTANT NOTE: When a user is navigating around a trellispark web application, the form will remember which tab was last displayed so that if the user moves off the form and then goes back to it, the last tab will automatically be selected.

IMPORTANT NOTE: When the Form Type is a Wizard the terms Tab(s) and Step(s) mean the same thing. To add steps to a wizard you simply add tabs.

Adding Field Definitions to a Form using the Data Model tab

The Data Model tab in a Concept or Portal Form (or Subform) is where you can define your fields and map them to locations on tabs in the form.

UX Creator > Functionality – Forms > Form Definitions – Data Model

Go to Creating Fields using trellispark UX Creator to learn more about the various fields that can be created and defined

An example data model table is shown below:

Fields are created under the Form Definition concept. They will be given a human readable name as a Label, an XML Element Name (if they store data), a Field Type, five fields (Tab, Row, R-Span, Column, C-Span) that determine where on the form the field will be displayed, and any Conditional Filters applied to the field.

Different field types will require different additional fields to be filled in that will appear after you select as you select the Field Type.

Mapping fields on gird layout

A form has a grid layout and fields are mapped to specific cells in the grid.

When creating a new field your options mapping its location are the following:

• Grid Row
  • Determines which row in the grid the field will be mapped to.
• Grid Row Span
  • Determines how many rows the field will span/extend.
• Grid Column
  • Determines which column in the grid the field will be mapped to.
• Grid Column Span
  • Determines how many columns the field will span/extend.

Using the diagram below as an example you can see how fields can be laid out in any orientation in the grid layout.

The shaded areas represent different fields, here are their position values depicted in the diagram:

• Yellow Field
  • Grid Row: 1
  • Grid Row Span: 2
  • Grid Column: 1
  • Grid Column Span: 5
• Red Field
  • Grid Row: 1
  • Grid Row Span: 2
  • Grid Column: 8
  • Grid Column Span: 5
• Green Field
  • Grid Row: 4
  • Grid Row Span: 1
  • Grid Column: 4
  • Grid Column Span: 6
• Cyan Field
  • Grid Row: 4
  • Grid Row Span: 4
  • Grid Column: 1
  • Grid Column Span: 3

If two fields occupy the same location on the grid or overlap then the fields will be rendered on top of each other. To avoid this make sure all fields have their own space.

It is possible to assign multiple fields to the same location if they are mutually exclusive in the form based on the user experience permissions. For example, fields A and B can occupy the same location if field A is only visible to the user in state X and B is only visible in state Y. Since a record can only be in one state at a time, then only one of A or B can be visible.

The user experience permissions enable fine grained control of the functionality available on a form based on:

1. The state of the record being displayed (for example, a “draft” or “approved” state)
2. The roles assigned to the current user (for example, a “manager” or “customer support representative” user role)
3. Custom defined business rules implemented using a TSQL Stored Procedure

Default number of available rows on a tab

By default the first 19 rows are available to display generic fields on field definitions. Row 20 is where fields that contain conditional filters are applied and are only rendered when the conditional filter is met (e.g., A specific Field Type is selected).

Go to Using Conditional Filters to learn more about Conditional Filters.

IMPORTANT NOTE:

• Tab “0” is a special tab on Concept Forms that is always invisible to a user. Assigning fields to tab 0 can be used to add extra fields to the data model which will never be displayed directly to users. This is helpful in scenarios where the concept may need to track pre-calculated values.

Adding Commands to your form using the Workflow tab

Commands are defined in the form’s Workflow tab and are used to trigger the workflow. Commands can be used on Application, Portal, and Concept forms.

IMPORTANT NOTE: This section is not applicable when the Form Type is Wizard. Wizards do not allow the option to add commands.

UX Creator > Functionality – Forms > Form Definitions – Workflow > Commands

A Command is used to link a TSQL stored procedure or Web API call to the command list on the command bar, so that it can be used within the application.

Instructions on how to create custom TSQL and WebAPI calls

Commands can be run synchronously or asynchronously based on how long the task will take and how essential it is to the continuing workflow of the form. Short, simple tasks can be run synchronously within the user experience. However, for tasks that may take a while it should run asynchronously in the background and be added to a queue to be run during off hours.

Each Command will have its own visibility controls that determine who is able to see this command and when it should be visible. If no specific states or roles are selected the command will default to be visible for everyone.

Commands also have the option to enforce a confirmation prompt to ensure the user intended to execute this command. You can also set the text that will appear in the confirmation prompt if the default text is not enough. The default confirmation prompt text is Are you sure you want to execute the following Command: CommandName.

You can also specify a command icon, this will be the icon that will be displayed next to the command when it’s listed. If nothing is specified the default command icon will be used. This field expects the class name of a Font Awesome icon.

Commands can also have an exit point specified to navigate the user to a specific form after the command has been executed by populating the exit point fields.

How to create a state transition for a concept

You can define state transitions on the Workflow tab of a concept form:

UX Creator > Functionality – Forms > Form Definitions – Workflow

This tab controls the workflow that is triggered around this concept, from actions on Commands to available states of this field and what transitions and events can exist around them. Anything that would normally be included in a traditional state transition diagram is defined on this tab through a combination of allowed states, allowed events, and the transitions from one state to another that is triggered by each event.

All concepts must have a Default State set to allow them to be created. Some concepts may not require multiple state transitions and can be setup with a single Allowed State called “Active” which is also the Default State. We recommend creating a state transition diagram and upload it to any concept that involve workflow beyond an initial default state. This diagram may then be used to guide the implementation of the user experience controls to create the appropriate workflow events and states.

A list of Allowed Events is created in parallel to the Allowed States to allow the state of a record to be changed and trigger any necessary workflow. The connection between the Allowed States and the Events is maintained within the State Transition Table. This is where most of the complexity around workflow is defined.

Concepts that require a more complex series of state transitions, such as a contract, will have to set which allowed states the contract can exist in, what events and actions may be triggered around these states, and a series of state transitions that will connect states to the events that will cause them to change.

Create your different workflow states in the Allowed States:

Defining these states is a simple process, involving setting up the name of the state and defining what it will allow the concept to do within the workflow.

To transition from one state to another in your workflow, an event needs to be defined. Create your events in the Allowed Events:

Events are used to trigger transitions from one state to another:

Like the states, the events consist of a simple name (which will be called when changing the states) and a purpose, letting the user know what this event will do in the concept.

Events also have the option to enforce a confirmation prompt to ensure the user intended to execute this event. You can also set the text that will appear in the confirmation prompt if the default text is not enough. The default confirmation prompt text is Are you sure you want to execute the following Event: EventName.

You can also specify an event icon, this will be the icon that will be displayed next to the event when it’s listed. If nothing is specified the default event icon will be used. This field expects the class name of a Font Awesome icon.

State transitions define the workflow around the event that changes a form from one state to another:

This defines the process that will allow events to be performed and the state of the concept to change; it is in the state transition that the visibility and code calls around this change will be set.

First, the initial state of the target record must be defined. This ensures that the events triggering a state change will only appear when the record is in the relevant state. For example, a Contract which has been Deleted cannot transition back to the Awarded state. The event which will trigger this change will need to be selected from the existing list of previously created events.

Allowed Roles are also used to determine whether this state change should be available to users; if a state change will affect the record in an important or irreversible way, it is best to ensure that only people with the correct level of authority can even see the event to trigger the state change. Leaving the list blank will allow any user to trigger the state change, regardless of their role.

If more complex calculations are required to determine if the concept can undergo this state transition, this calculation can be defined as a stored procedure and linked into the state transition in the Gate Stored Procedure field.

Some state transitions require other workflow actions or code to be triggered; there are several options to allow code changes to be tied to this state transition. This code may be called through an API, requiring the name of the API and the target that will be called, or through another stored procedure. If the change must be made before the state of the concept is changed, it can be linked as a stored procedure or a Web API call using the Before Change fields. Changes that should be made after the concept’s state has changed (possibly reflecting the current state of this concept) can be linked similarly by the After Change fields. This will also include a button to determine if the After Change command should be run synchronously or asynchronously.

The third vital piece of a state transition determines what state the concept will be changed to once the relevant event has been triggered. The available states in this list and the initial state list will be populated from the created list of possible states that were defined on the concept page. It is important that you have at least the Initial and Final states defined and have an Event that will be used to trigger the change in state.

State transitions can also be cascaded to children of the concept whose state has changed.

Cascading state transitions to child records is relatively straightforward; the child concepts that this will apply to are identified from a dropdown list of available concepts. Both Initial and Final State lists are populated by the Allowed States on the child concept.

The Initial State will be used to determine which child concepts will have their state changed. If blank, then all records of this concept under the parent will be affected.

The final state will define which state the child record ends up in.

IMPORTANT NOTE:

• Any workflow required by the state changes in the child record must be done by the parent as part of its Before/After Changes workflow. The state transitions of the child object are not referenced by cascading state changes. The child object may not have defined state transitions that map the cascading changes.

Workflow tab for Wizards

IMPORTANT NOTE: This section is only applicable when the Form Type Wizard is selected.

UX Creator > Functionality – Forms > Form Definitions – Workflow

When creating a wizard, the workflow tab has very few but crucial options to ensure functionality.

• Default State – This is the state wizards will be in when they’re first created. It’s crucial to ensure that this value is the first step/tab of the wizard.
• Allowed States – This is where all the states the wizard can be in are defined. It’s crucial to ensure that an allowed state for each step/tab defined in the Overview tab is created. There also needs to be an addition Allowed State created called “Complete”. This will be the state the wizard is put in once it’s been completed.

IMPORTANT NOTE: Failure to properly setup the workflow tab will result in your wizard not functioning correctly and could impact the ability to resume incomplete wizards.

Optimizing runtime performance using the Optimization tab

IMPORTANT NOTE: This section is not applicable when the Form Type is Wizard as wizards do not contain an Optimization tab.

UX Creator > Functionality – Forms > Form Definitions – Optimization

The Optimization tab is used to improve performance and responsiveness in the user experience. The options distinguish the fields that will control access and if a lookup table should be created and rebuilt when changes are made to the concept. There are four optimization features available:

1. Add Lookup Table
2. Rebuild Lookup Table
3. Check Access
4. Retain For Days

Using Add Lookup Table option

Lookup tables are used to create an efficient way to search the table and can be created with all the concept’s fields, or a selected few that will frequently be used to search, or filter lists of this concept type. Not all concepts are searched often enough to require having their own lookup table. Selecting No or Tagged Fields for selective forms allows trellispark to slim down the data model for faster run times.

Using Rebuild Lookup Table option

Many lookup tables will not need to be regenerated every time the SQL Code Generation is executed. Select No for lookup tables that contain many thousands of rows and do not need to be regenerated to speed up the SQL Code Generation runtime.

Using Check Access Ancestor or Instance option

The Check Access control determines at what level this form will check the user’s access permissions. Every time a form is rendered, a check is made to determine whether the current user has access to the record.

All data records (or “instances”) are stored in a hierarchical tree structure. Access control to a record can be defined at any instance level in the hierarchy.

For many concepts, the records will be visible to the current user if the user can view one of the record’s direct ancestors (parent record). The Check Access field is set to Ancestor in this scenario.

By default, the Check Access is set to Ancestor. This is the most efficient setting for performance.

If the security of the concept’s records requires a direct check of the access rights of the current user against the specific record, then the Check Access field should be set to Instance. This is always the case for concepts that serve as the basis for a Portal Form.

This access control design enables direct row-level access control of any user to any record. Either the user has direct access to the record itself or inherits access from one of the record’s ancestors. The level of access required being determined at design time and maintained within the application data.

Using Retain for Days option

The Retain For Days feature determines how long the old versions of concept records will be kept in the version history table. By default, a value of -1 will ensure that records are never automatically deleted.

Example Video – Lookup Tables

Form Permissions tab

UX Creator > Functionality – Forms > Form Definitions – Permissions

The form Permissions tab is where you can define special conditions that the user must meet to be able to view, save, and delete the form. By default, all users have full permissions to the form. Each form can have specific Form Permissions to determine whether a user may see the form given the state of the record, the role of the user, and any custom business rules.

As soon as a form permission is created, by default the form will be hidden unless the user is specifically allowed to view the form.

Form Data Migration tab

IMPORTANT NOTE: This section is not applicable when the Form Type is Wizard as wizards do not contain a Data Migration tab.

UX Creator > Functionality – Forms > Form Definitions – Data Migration

Go to the article Migrating Functionality Between trellispark Environments to learn about how to use the data migration features in trellispark

Form Online Help tab

UX Creator > Functionality – Forms > Form Definitions – Online Help

The Online Help tab on a form is where you can enter helpful general instructions or other information that a user will see when they are navigating to this form and select the Help menu. The information can be formatted using the HTML editor and can include images and hyperlinks.

Form Styling

UX Creator > Functionality – Forms > Form Definitions – Styling

The styling tab on a form is where you can adjust how various items on the form will display.

• CSS Classes
  • Allows you to specify CSS Classes and styles for those classes that will be available to all fields on this form type.
• Display Breadcrumbs
  • Various options that determine how the breadcrumbs will be displayed on the form.
• Tab Bar Location
  • Determines where the Tab Bar will be rendered on the form.
• Footer Location
  • Determines where the Footer will be displayed on the form.
• Number of Grid Columns on form
  • Determines how many columns will be used to divide the form and field placements. The default value is 12. To learn more regarding how fields are mapped on forms refer to the Mapping fields on grid layout section higher up in this article.
• Display Form Name
  • Determines whether the form name will be displayed when this form is loaded.
• Window Height Percentage
  • Determines the height percentage of the instance window when this concept is opened in a popup window.
• Window Width Percentage
  • Determines the width percentage of the instance window when this concept is opened in a popup window.