Administrator Best Practices

There are many paths to Rome.... frevvo suggests the following best practices for managing your tenants, projects, forms and workflows.

Open

Multiple frevvo server installations are the most flexible and best practice for maintaining a production environment. In this scenario, you may have a development server, a test/staging server and a production server. Or you may have only a development server also used for testing and a production server for deployed forms/workflows.

1. Create roles and users in your development environment. If you are using the default security manager, simply create the users and roles in the tenant, otherwise refer to customers using the LDAP/SAML/Azure Security Manager.

   The role names in your development environment should be the same as the role names in your production environment. If they are different, modifications to your workflows will have to be made to users and workflows to reflect the production roles when they are moved to the production.

2. Multiple designer users can create and test forms/workflows in each of their user accounts.

3. These designer users will download a finished and tested project and check it in to a source code repository (a repository outside of a frevvo server) as the new version of the project. Ex: SVN, CVS, Google drive.

4. Create a generic production user account (ex: “production@<your tenant>”) in your production environment and give this user the frevvo.Designer role. All your production forms/workflows will be in this user account.

   If you are using a non-default security manager, this step and the next step would be done via your IDP software.

5. Assign the frevvo.Publisher role to one or more other users in your production environment.

6.  When a designer is ready to deploy a form/workflow to production or update one already in production, a frevvo.Publisher will check-out the new project from source code (a repository outside of a frevvo server) and upload/replace the project into the generic production user account in your production environment.

7. Step 6 can be performed by the tenant admin or your generic production user if you prefer not to create users with the frevvo.Publisher role.

We recommend that all in-house customers with a single server have two tenants: a development/test tenant and a production tenant. A separate development/test tenants is recommended for the following reasons:

• The roles in your development tenant will contains test users with test email addresses so that workflow notification emails will not impact/spam real company employees.

• Test submissions will not be mingled with production submissions.

• Test tasks will not appear on your real users' task list.

• Test tasks will not appear in production Task History Search

• Test submissions will not appear in production Shared Items / Submissions

Follow the setup steps above for In-house Test/Staging Server Installations. The only difference is that in your case your "test environment" is simply a dev/test tenant on the same server as your "production environment" and not a separate frevvo server.

Cloud customers have a single tenant. In this scenario, best practices are to create a set of test roles and test users. Your form/workflow designers will use test roles/users during the dev/test phase.

• Test roles & users allow your designers to test workflow email notifications and workflow task navigation without spamming real users' email inboxes and task lists.

•  When a form/workflow is in development you may consider:

  • Temporarily switch the form/workflow configuration to use your test roles and users.

  • Temporarily turn off Show in History to prevent test forms/workflows from cluttering production Task History Search.

  • Temporarily turn off Who can view and/or edit submissions ACL to prevent test forms/workflows from cluttering production Shared Items / Submissions, or switch the ACL to your test roles and users.

• When your form/workflow is ready to deploy to production switch the roles/users from your test roles/users back to your production roles/users, and if desired re-enable task history search and view/edit submissions ACL.

• Follow the detailed steps below for Publishing Forms/Workflows from Development to Production and Updating a Form or Workflow in Production noting that your generic production users account (ex: "production@<your tenant>") will be in the same tenant as your designer's user accounts.

Cloud customers may optionally purchase a 2nd tenant for development and testing.

We recommend that the forms/workflows be created & tested by one/multiple designers in their own accounts. After the forms are designed/tested, they can be downloaded from the individual designer user accounts and uploaded to a generic production user account (ex: “production@<your tenant>" where the forms can be published and used by your end users.

We recommend using a generic production user account to publish projects/forms/workflows into production for the following reasons:

• If designers publish production forms/workflows from their individual designer accounts and edit a production form/workflow, they will be editing a live form. This does not give any source code / QA control.

• If there are multiple designer publishing production forms/workflows from their own accounts, then your production forms/workflows will be scattered around between different user accounts and it will be more challenging to maintain them.

• The username of the user account where the form/workflow is published is used in the form/workflow URL and you might not want the username to be known to all other form users.

• Designer users have permission to view submissions. Publishing in a generic production account prevents the designer from viewing production submissions.

Open

Follow these best practices:

1. Create a generic production user (ex: “production@<your tenant>”) and give this user the frevvo.Designer role. All your production forms/workflows will be in this user account.

   If you are using a non-default security manager, this step and the next step would be done via your IDP software.

2. Assign the frevvo.Publisher role to one or more other users.

3. When a designer is ready to deploy a form/workflow/project for production or update one already in production, the designer will download the form/workflow/project zipfile and check it into a source code repository (outside of a frevvo server).

4. A user with the frevvo.Publisher role will check-out the new form/workflow/project from the source code repository (outside of a frevvo server) and upload/replace the form/workflow/project into the generic production user account.

   1. To deploy a form/workflow for the first time, you must then log in as the Production User, select the form/workflow, and click Deploy.

   2. To update a form/workflow that is already in production, check "replace" on the upload screen. The deployment state of the form/workflow being replaced will be maintained for the updated version.

If you need to update a form/workflow that has been deployed to production, there are specific steps to follow to avoid issues with submissions. Submissions are tied to a specific form/workflow. It is very important that you make your changes to the form/workflow that has the same typeId as the production version. This ensures that the production version of your form/workflow will be replaced by the updated version when you upload it to your production account and check the Replace checkbox on the Upload screen.

Let's say you have a form/workflow in production that requires some changes. Follow these steps:

1. Download the form from your production account.

   frevvo recommends that customers maintain backup .zip files of production forms and workflows in their own version repository. Each time you download a workflow from production, provide it with a unique filename (i.e. MyWorkflow_flow prod YYMMDD.zip) and maintain it in your directory as a backup. In case a later development version has incompatible changes, you will be able to revert to your latest backup version.

2. Upload the form to a new or existing project in your development environment.

3. Make the changes.

4. Download the updated form/workflow from your development account.

5. Upload it to your production account. Be sure to check the Replace checkbox on the Upload screen. The XML schema checkbox will automatically be checked.

6. The existing version in your production environment will be replaced with the modified version from the development environment. You will see it at the end of the form/workflow list.

The typeId of a form/workflow can be seen in the URL when you edit it in the form/workflow designer.

Some changes have little to no impact on your in-flight forms and tasks, but other changes can significantly affect, or even break, workflows that are in progress. 

Usually it is safe to:

• Move controls (except for moving controls into/out of sections, tables and repeats)

• Change control, form or workflow style properties.

• Change control Labels and selection control option Labels

• Edit Messages, email subjects and email messages (such as for task notifications and doc actions.)

These changes can impact the form's schema and routing, and thereby may impact forms and workflows that are in progress.

• Changing a control Name or a selection control Option Value when that control is referenced in business rules, preconditions, and/or task assignments.

  • For example, let's say you change a control name and then perform a pending task for that workflow from your task list. The data entered into the workflow on the prior form version will not display in the task with the renamed control.

• Move a control inside a section, repeat or table.

  • Similar to the above example, data from tasks performed before the change may not appear on tasks performed after the change.

• Adding, removing or changing controls inside a signed section - this will invalidate signatures on sections that have already been signed, including completed forms/workflows that are edited from the Submission repository.

• Making a control required that was previously optional.

• Adding steps with required fields.

• Update the database (or google sheet, or 3rd party system) supplying data for dynamic select control options on form.[load,activate]. Any task performed from the task list that had an option set that was deleted or changed (for example, to fix a typo) from the database displays the control as blank again and required if that was the default. If you're on a workflow step where these fields are now disabled, such as an approval step, you need to reject back to the user of that prior task to re-enter the data.

• This same behavior occurs if you change selection control option values.

• Adding or changing a precondition; for example, if a step is assigned and you add a precondition that resolves to false for that step (so it should be skipped) the user may not be able to perform it.

• Changing a single field to a repeat, or vice versa.

• PDF Mapping - if you update the template, field mapping may be impacted.