V4 Designing Flows

frevvo Live Forms™ v4

The frevvo Live Forms™ Flow Designer is the heart of frevvo's simple, quick, no-coding required workflow creation. The Flow Designer enables you to create both multi-page forms and workflows that route your form through an approval process collecting digital signatures along the way.

Flow Examples

You can find many example workflows in the Flow Examples chapter. This is a very good place to get a quick overview of how to design and use frevvo workflows.

Flow Designer

First navigate to the Flows Home Page inside one of your application. See the Flows home page for help navigating here.

We recommend that tenant admin users not create or edit flows, nor have roles assigned to them. These users should restrict themselves to administrative tasks.

Once you are in a flows home page, start by clicking New to add your first application. Then click the name of the application or the Edit icon and click New to create your first flow.

A unique and arbitrary flow name will be generated automatically--Flow 31 for example. You'll change this name when you begin working on your flow to something meaningful like Mortgage Application shown below.

The Flow Designer has several components. Each is described below.

Palette

The palette contains all of the forms in your application's form tab, a new form and a summary step. Click on the form you want and drag it into your flow. See adding steps to your flow for more information.

Properties Area

This is where you define workflow navigation, customize button labels, configure task information, pending messages and task notification emails seen by the flow users, and more flow customization. When you click on a step in your flow, the Properties area displays the step's properties so you can view and edit them. There are also flow properties; click the toolbar at the top of the flow work area to access these.

Flow Work Area

The right side of the Flow Designer is the work area for the flows you create. At the top of this area is the toolbar.

Toolbar

The toolbar at the top of the flow work area is visible when you are designing your flows but it is not visible to you when you test your flows or to your users when they access your flows. The toolbar includes the following buttons:

• Click Form Action to configure what users will see when they submit the final step of your flow
• Click Doc Action to configure what happens to the data when they submit the final step of your flow
• Click Finish to save the changes to your flow
• Click Cancel to discard changes you’ve made to your flow

Palette Controls

frevvo’s flow palette contains all of the forms you have already created in the Forms tab of the application you are currently editing. These forms are available for you to add as steps of the flow. The palette also contains a new form which lets you create a new form step directly within the flow designer and a summary step. The purpose of each is described below.

New Form

Consider going back to the Forms tab to create any new form steps required in your flow. Forms created in the Forms tab are reusable whereas forms create in the flow designer are not reusable.

The New Form palette control allows you to create a new form step in your workflow directly inside the flow designer. If you do not have an existing form for the step you require, drag & drop the New Form into your flow and create the step in place. This will launch the frevvo form designer where you can add controls to the form just as you would if you designed the form from the Forms Home page.

Drop the New Form from the palette into the flow. Click to select it. Then click the pencil icon to launch the form designer. A unique and arbitrary name will be generated automatically for the step--Form 29 for example. You'll change this name inside the form designer.

Existing Forms

Consider going back to the Forms tab to edit the form. Then delete old form from the flow designer canvas and add it back to the flow from the flow palette.

The palette contains all of the forms that you have already created and which are listed in your current application's forms home page. You can use any form as a step in the flow. Adding an existing form to the flow creates a copy of that form. If you later edit the form from the forms home page, those changes will not affect the step in the flow. It remains as it was at the time you copied it into the flow. If you want to update the flow to have a new copy of the form, delete the form from the flow and drag it in again. You can also edit the form directly in the flow. Conversely these changes to the form inside the flow do not affect the original form in the form home page.

Summary

Drag a Summary step anywhere in your flow. This will simply display a Summary view of all the data that has been entered into the various steps of the flow prior to the Summary step. The user can review the data and Continue or click on automatically generated Edit links in the Summary View to go back and edit the data.

Adding Steps to a Flow

A flow step is a form. Steps are added to the flow by dragging one of your existing form displayed in the palette, the New Form or the Summary and dropping it into the flow work area.

Designing Forms in a Flow

To design/modify a form in the flow first click it to select it; it turns light blue. Click the pencil icon to launch the Form Designer. For more information on designing forms, please see the Form Designer documentation. As a reminder, when a form is added to your flow it is added as a copy. When you edit it, your changes will be saved to the copy and will not affect the original form that was dragged in from the palette.

Form Control Names and Schemas

When you create a flow, frevvo creates an XSD schema of the flow that combines all the fields in all the forms in the flow. For example, if you go to the Flows home page and click to download or open a flow's schema, you'll see that it contains elements for all the controls in each form in the flow.

When designing the forms you want to use in a flow, be aware that if controls in the different forms have the same name, their data will merge in the XML document that frevvo generates when the flow runs and is submitted. While the Form Designer automatically prevents you from giving two controls the same name within the same form, it doesn't prevent you from giving controls in different forms the same name.

For example, suppose one or more forms in a flow have a text control named FirstName. On one form, this might be an employee's first name; on another, it might be a manager's or customer's first name. When the flow runs and is submitted, the two first names will merge in the resulting XML file. To avoid this, you should give the fields unique names — such as EMPFirstName or MGRFirstName — so they'll be separate elements in the flow's XSD schema and separate pieces of data in the submitted flow's XML file.

Another way to avoid data merging is to "nest" controls with the same name within Section controls (which control nesting) that have different names in different forms. For example, suppose you have one form with a Section Control named Employee that contains a text field named FirstName. A second form has a Section control named Manager that also contains a text field named FirstName. If you use both of these forms in a flow, the FirstName data does not merge because the two controls are nested — at the same level — within Sections that have different names.

See Section Controls in Designing Forms for more information on using these controls. Be aware that Section controls can themselves contain Section controls, and that this affects the nesting level of the controls they contain.

The same data merge consideration is true for form data generated by schemas. For example, suppose you're designing an employee performance review flow that includes two forms. Form 1 contains past performance review data (perhaps read-only) from a database; Form 2 is the same but blank for the current review.

If both forms update the same database table, they may be generated from the same XSD created by a database connector. The issue is that data in Form 2 (current review) will merge with the Form 1 values (past review) if their schemas are the same.

One solution for this problem would be to write two different queries in the database connector so that the past review and current review schemas have different namespaces, which would prevent them from merging.

Linked Forms in a Flow

Many work flows often involve a number of people filling out different sections of a single form. So when you're designing this type of flow, you're most likely dragging the same form into the flow designer repeatedly to create the different steps or activities in the flow.

Another way to create this type of flow is to use the Linked Forms feature of the flow designer. In this method, you create a linked version of a form for each activity or step you want in your flow. One great advantage of this method is that if you need to make changes to the form after you've created your flow, you only have to edit the "parent" form — the editing changes are automatically propagated to its linked forms in the flow. Conversely, if you drag multiple copies of the same form into a flow to create activities, you'd have to make any changes to each copy of the form in each activity.

One circumstance in which you might not want to use linked forms is a flow in which each user is filling out a different form, or you want to show or hide different parts of a form depending on which user is filling it out (although you can do this to some extent with linked forms using the Security tab or Rules in the Form Designer when you create your form).

1. To create linked forms in a flow, first drag a form into the flow designer.
2. Click on the form, and then click to create a linked form.
3. Continue clicking to create as many of the linked forms as you want.

The example below shows the parent Lodging-Meal Selections form and its two linked forms. Notice that the parent form and its linked forms initially all have the same name, but the linked forms are outlined by dashed lines rather than solid lines. Note also that the form displays three icons when you click on it, while the linked forms display only the remove icon.

• Click to create a linked form.
• Click to open a form in the Form Designer to edit it.
• Click to remove a form or a linked form.

Linked Forms and Activities

Because the parent forms and its linked forms represent activities, you'll want to give them unique names. The parent form in this example has three tabs used for hotel check in, dinner selection, and hotel check out.

To rename the form and its linked forms, click on them and then use the Name setting in the Properties panel as shown below.

As with other forms you use to create activities, you can assign a linked-form activity to a Role, so that the activity is performed by someone with that role, or even by a specific user. In this example, we rename all three activities and assign each to a different role.

• CheckIn is assigned to the Reservations role.
• DiningRoom is assigned to the MaitreDHotel role.
• CheckOut is assigned to the Billing role.

You may also want only certain sections of the form to be visible in an specific activity so that only users in a certain role see those sections. For example, in this flow, perhaps only the dining room staff needs to see the form's Guest Information tab.

To do this, you can edit the the form via the Flow Designer and use the Security Tab in the Forms Designer to assign a role to sections of the form. Click the form, and then click to open the form in the Form Designer.

In this example, we assign the Guest Information tab to the MaitreDHotel role.

When the flow runs, the first activity, CheckIn, is performed by a user with the Reservations role, so that user does not see the form's Guest Information tab, which is only visible to a user with the MaitreDHotel role.

The next activity in the flow, DiningRoom, is assigned to the MaitreDHotel role, so that user sees the Guest Information tab.

You can also use rules to show or hide parts of a form in an activity. For example you could use the rule below to show the Guest Information tab only when a MaitreDHotel role is using the form.

This rule is useful in a workflow where you want to make a the tab named Review visible only for the workflow activity named Manager Review.

if (form.load) {
  if (_data.getParameter('flow.activity.name') == 'MaitreDHotel') {
    GuestInformation.visible = true;
  } 
}

For more information about using rules this way, see the Security Subject topic in the Rules Examples section.

Form & Doc Action Wizards

The flow wizards provide the same functionality as the same wizards in the Form Designer. View the Form Wizards documentation for detailed information on using them. Note that some wizards are only available for forms and not for flows.

Wizards make it easier to configure what happens to the data when a user submits your flow and what the users see after submitting the flow. The wizards are accessible from the flow designer toolbar via the one button labeled Form Action and another labeled Doc Action. The action settings are summarized in the flow properties flow info tab.

When you drag/drop a form into a flow the form's Doc Action does not get carried along. A flow's Doc Action happens once all steps of the flow have been performed and not between individual steps. In concept even though a flow is multiple steps, a flow is in the end one single form submission.

Editing Flow Properties

At the top of the Flows Work Area click the toolbar (where you see the Finish and Cancel buttons) to access the flow’s properties, which are shown in the lower-left portion of the Flow Designer. The properties section has tabs for Settings, Style and Flow Info.

Flow Properties

Each flow property setting is described below.

Name

This is the name you see on the Flows home page where your flows are listed. We recommend changing the name to make it more meaningful than the arbitrary name assigned when you create it, but keep in mind it is a working name only, so users will not see it.

Description

By default all flow descriptions say, “Edit the flow to change this description,” but you can change this if you wish. The description appears as a tooltip when you mouse over the area just to the right of the flow's share icon on Flows home page. You also see this description when you view individual submission documents.

Navigation

frevvo can automatically generate and display a navigation toolbar for your flow using which users can navigate back and forth in the flow. There are four available options:

• None: This option displays no navigation toolbar. This is useful for situations where the same form is being passed between users for signatures e.g. Vacation Request workflow filled in by an Employee and signed by a Manager.
• Navigation Toolbar: this displays a standard navigation toolbar with links for each step.
• Percent: This displays progress through the flow as a percentage.
• Step 1 of 4: This option displays progress through the flow as a counter.

Visibility

This field provides access control for the flow and has the same meaning as Visibility for forms.

Task Info

When you save a partially filled flow to continue it later or when frevvo puts a task on your task list as part of a workflow, the task is accessed via your task list. This field controls the name that gets displayed in the user's task list. For more details, see the Tasks documentation. This field can use templatized strings for dynamic content, e.g. the Task Info can contain "Vacation Request for {FirstName} {LastName}" where FirstName and LastName are the names of fields in a form from a prior step in the flow. Before putting the task on a user's task list, frevvo will resolve the Task Info string using the actual values of the FirstName and LastName fields e.g. "Vacation Request for Tom Smith".

You access your Task list from your applications home page. You use the Task list to perform tasks assigned to you, to view a task's history, or search for tasks you've participated in — a tenant admin can also search for other users' tasks.

Pending Msg

This is the message that is displayed on the screen during a workflow when the next step must be performed by a different user/role and frevvo puts it on that user's task list. For example, in an Vacation Request workflow, the first step may be filled in by an Employee but the second step (approval) must be signed by a Manager. When the Employee clicks Continue, frevvo will put the task on the Manager's task list and display this message on the Employee's screen. This message can use templatized strings for dynamic content, e.g. the message can be set to "Thank You {FirstName} {LastName}. Your request has been submitted to your manager for approval." where FirstName and LastName are the names of fields in a form from a prior step in the flow. Before putting the task on a user's task list, frevvo will resolve the pending message using the actual values of the FirstName and LastName fields e.g. "Thank You Tom Smith. Your request has been submitted to your manager for approval.".

Tracking Id

See Tracking Id described in designing forms.

Setup Key/Saved/Summary Fields

This setting controls which fields are saved to the built-in submissions repository. By default, all your data is saved as an XML document. This is the most efficient way to store/access your data both in terms of speed as well as storage. However, if you prefer to view your data via the submissions user interface, you can choose which fields are saved in addition to the XML data. Note that this could incur significant performance overhead and will also consume additional storage in the repository.

Clicking on the link displays a wizard. The wizard will display the fields from your flow. Key and Saved fields have the same meaning for flows as for forms. Please refer to the Setup Key/Saved Fields documentation for forms for details on these fields.

Summary Fields
You may select the fields you want to appear in the Summary view if you have a Summary step in your flow. Only checked fields will appear in the Summary.

Printable

If you check a flow's printable checkbox a Print button will be displayed in Summary steps of the flow. If you don’t want users to print your flow, uncheck the checkbox so users will not see the Print button. You can control which fields are printed by setting up which fields are displayed in the Summary View as described above.

Flows do not current support a print icon as is available on forms. This will be added in an up coming release. One solution is to add your own print link as discussed in the chapter Printing Forms.

Each activity also has a printable property which controls whether or not that activity appears in the PDF document view. See activity printable for full details.

Save PDF

When checked a PDF image of the flow is saved in frevvo's submission repository. See the documentation for the submissions repository for details on viewing the PDFs saved there.

Since flows are a combination of multiple forms or a single form visible in multiple activities or a combination of the two, it is important to understand what controls will be printed with the PDF is generated. See the topic discussing the activity printable property.

Show Logo

This property is checked by default and causes the “powered by frevvo” logo to appear on your flow. Uncheck the checkbox to remove the logo from your flow.

Save/Load

If you check this checkbox a Save button will be displayed for each step in your flow. If you don’t want users to be able to save partially completed flows and continue them later, uncheck the checkbox so users will not see this button.

This feature is useful for flows containing lengthy forms where your users may not have all the information required to complete the form in a single session. By clicking on the Save button, a copy of the flow with all the current values is saved by frevvo. frevvo will also generate an entry in the user's task list from where the user can continue working on the flow at a later time.

If you are not authenticated, clicking the Save button will display an authentication dialog that requires you to login. See the documentation on using forms and flows for more details.

Users can repeat the save/load steps as many times as they wish.

Saved flows are not the same as submitted flows. Saved flows do not appear in the Submissions Repository. Saved flows can contain invalid data and can also contain required fields with no values yet entered. When such a flow is re-loaded the missing and invalid values are again flagged as such by frevvo. And the flow cannot be continued/finished until corrections are made to those fields.

Show in History

If this checkbox is unchecked, tasks for the form or flow will not appear in Task History searches. If you want them to appear, make sure this box is checked. Checking or Un-checking it affects all tasks including ones that were created prior to the action.

Task for First Step

If this checkbox is unchecked and the flow requires a specific role or user to execute the 1st activity then a person who tries to use the flow and does not have the required role or is the specific user will get an error message:

Error
Access Denied. Either you are not authenticated or you do not have the proper permissions/role.

If this checkbox is checked, and a person without the correct user or role tries to use the flow, the flow will be auto-started and sent to the task list of the person(s) specified in the user property or the roles list. The user who tried to access the flow will see the Pending Message setup for the first step or the default pending message "Your Request is being processed".

This feature is useful for auto-starting flows programmatically. For example if you need to process a batch of invoice whose metadata is a row in a .csv file. You can programmatically process the .csv file and auto-start a new flow for each row in the .csv initializing the form fields with data from the .csv.

Another use case may be for a person in the HR department to auto-start a employee performance review by placing new review forms on each manager's task list for each of their reporting employees.

Force Auth

See Force Auth described in designing forms.

Flow Style Properties

Each property is described below.

Width

This specifies how wide forms in your flow will be. The default “regular” width is 600px, but the dropdown also includes thin (400px) and wide (800px). You also may pick the custom option; this will enable the box to the right of the Width dropdown and let you specify your own width.

Theme

You can choose a theme to alter the appearance of your form. frevvo provides two global themes : Clear or Professional Blue. The Clear theme gives your form a clear (white) background and the Professional Blue gives your form a soft blue background.

Of course, you may create a custom theme instead of using the default themes. After you have added the customized them it will appear in the dropdown list along with the pre-defined options.

Flow Info

The Flow Info tab summarizes the settings selected and configured via the form and doc action wizards.

• What users will see? depends on the form action wizard configuration
• What happens to my data? depends on the doc action wizard configurations
• Doc URI settings depends on the doc URI wizard configurations

Editing Step (Activity) Properties

When you click on any step in the flow, the Properties panel displays properties (settings) for that step. The Properties panel is displayed in the lower-left portion of the Flow Designer.

Activity Properties

Each activity property setting is described below.

Role List

This area displays a list of available roles. Roles are created by your tenant administrator or automatically imported from your LDAP or Active Directory server. You may select one or more roles here. When a role is selected, the step in question can only be performed by users belonging to that role. For example, if you have a Purchase Request workflow where the first step is to be completed by any employee but the second (approval) step must be performed by someone with the "Manager" role, you can select the Manager role for the second step. When an employee uses the workflow, completes the first step and clicks Continue, frevvo will first check if the logged in user (the employee) belongs to the Manager role. If yes, then the second step is displayed. If not, frevvo will suspend the workflow, generate a task and place it on the task list for users with the Manager role and display the Pending Msg to the employee.

Use the Role property instead if you want to dynamically select a role at runtime.

If the 1st activity has an assigned role and the flow is used by a person who does not have that role, the flow will be auto-started and automatically put on the task list of the users who have that role. The person who auto-started the flow will see the pending message configured for the 1st activity. By default they will see the message "Your request is being processed". This is a useful way to start a workflow by an automated service.

Role

This field causes workflows to behave similar to role list except that the target role of the workflow is determined at run-time. For example, you may have a workflow where the first step is a Purchase Order or a Loan Request and the second step is an approval; however the approval must be performed by a Manager if the amount is less than $1000 and a Supervisor otherwise. You can enter a value in this field. This field can use templatized strings for dynamic content, e.g. it can contain "{ManagerId}" where ManagerId is the name of a field in a form. frevvo will resolve the ManagerId string using the actual value of the ManagerId control and generate a task targeted at that specific user.

See the workflow example topic determining the role at run-time.

User

This field causes workflows to behave similar to roles except that the target of the workflow is a specific user rather than all users with a specific role. For example, in a Vacation Request workflow, the first step is to be completed by an employee but the second (approval) step must be performed by a specific manager (person) rather than anyone with the "Manager" role. You can enter a value in this field. This field can use templatized strings for dynamic content, e.g. it can contain "{ManagerId}" where ManagerId is the name of a field in a form from a prior step. frevvo will resolve the ManagerId string using the actual value of the ManagerId control and generate a task targeted at that specific user.

See the workflow example topic sending a workflow step to a specific user.

CSS Class

This CSS class name will be added to the XHTML markup generated for this step in the flow. You can use this CSS class in any CSS when customizing themes.

Task Info

This setting overrides the default Task Info for the flow for this step only. It is similar to the Task Info for a flow described above.

Pending Msg

This setting overrides the default Pending Msg for the flow for this step only. It is similar to the Pending Msg for a flow described above.

Button Label

This is the label of the button that is displayed at the bottom of every step in the flow. The default label is Finish or Continue depending on whether or not the step is the last step in the flow.

Precondition

Preconditions are used to add logic to your flow to skip or perform a step based on the data entered into prior flow steps. For example imagine a mortgage application in which a Supervisor had to perform a step for all mortgages over 500,000.00. To do this imagine the flow has a 1st step where the applicant enters the loan amount into a field named LoanAmount. Step 2 is performed by a bank Employee and Step 3 is performed by the Supervisor only for mortgages over 500k.

To do this add a precondition to Step 3

LoanAmount.value >= 500000

You can also set preconditions based on values in dropdowns and radios. For example imagine also the 2nd Step contained a dropdown control named SendToSupervisor with the values yes/no so the Employee could override the logic in the flow to send for Supervisor approval even for loan amounts under 500,000.00. Add the following precondition to Step 3

LoanAmount.value >= 500000 || SendToSupervisor.value == 'yes'

Either way Step 3 would be skipped for loans less then 500,000.00 or if the Employee set SendToSupervisor to 'no'.

The precondition logic is the same used when writing business rules. See the chapter on Business Rules. Make sure the controls used in preconditions are required controls. Controls without values used in preconditions will cause an error in the flow. Test for this when you are creating flows with preconditions to ensure that when the flow designer shares the flow with other that it will not display an error.

To skip an activity if a control already contains a value. In this example if the Supervisor was the one to fill the first step of the flow then they were required to enter their SupervisorTitle, and that field is thus guaranteed to have a value. In this case to skip the next step by adding this to the second activity's precondition.

SupervisorTitle.value != ''

Setup Task Notification Email

Email notification is optional. Each user can configure their own email notification preference in their User Profile using the My Account link on their applications page.

When frevvo generates a task and places it on a user's task list, a notification email is generated. Click on a task in your flow, and then click the Setup Task Notification Email link in the Properties panel to configure the email notification message for that task. A wizard is displayed.

The email wizard lets you set your own email subject and message. The message body can contain HTML and CSS, giving you the ability to generate nicely formatted emails. Form data values can be added to the message subject and body using control template names. Two dropdowns in the wizard make it easy to add control templates.

The special template {task.list.url} can be used in the email body to generate a clickable link to the user's task list. See the Email Integration topic for information setting up email notifications for form and flow submissions. This function uses a similar notification wizard.

The tenant admin can configure the from email address for task notification emails on the admin's Edit Tenant page.

Printable

If this is unchecked, then this activity will not appear in the Print View for the flow.

This is commonly used when you add the same form to the flow multiple times or use the linked activity feature to duplicate the same form for multiple activity steps such as is common when the same form is passed among multiple people for approval. In this type of workflow you should uncheck the printable property for all but one of the activities. It does not matter which you choose to leave printable in the case of linked activities since they are all the same form.

You can also have fine grained control over which controls appear in the print view by editing the activity step and setting the control's printable property.

Save/Load

This setting overrides the default Save/Load for the flow described above for this step only. If Save/Load is enabled for the flow as a whole, you can uncheck this property to disable it for specific steps.

Save to Role

Normally, when you click Save to save a partially completed flow, the saved flow will only appear on your own task list. If you check this box, then the saved flow is assigned to all users in the Role that is specified for the current step. For example, you may have an Issue Tracking workflow where an employee submits an Issue and the Issue can be acted upon by multiple users in the "Admin" role before it is resolved. The first step is filled in by any employee. When the employee clicks Continue, a task is generated for an "Admin" user. Any user with the "Admin" role can perform the task. The user can enter some data and click Save. The flow goes back into a pending state and is placed on the task list for any "Admin" user. A different "Admin" user can pick it up and continue working on the issue. In this manner, you can create a step in a flow that loops several times before continuing.

Printing Flows

Workflows do not currently support a print feature. However, the summary activity does support a print button. To print the summary activity, first drag a summary activity into your flow from the palette and then setup summary fields to indicate which form fields to display in the printable summary activity.

It is also possible to add your own print button to any workflow step by adding a message control with &print=true&format=PDF. This custom print button will print the current activity step and not the entire workflow. See printing forms for more details on how to add a print message control. Note that this will enable the user to print the current step even if this activity's print property is unchecked.