Administrator Best Practices

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

Live Forms In-house Test/Staging Server Installations

Multiple Live Forms 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.

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.
Multiple designer users can create and test forms/workflows in each of their user accounts.
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.
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.
Assign the frevvo.Publisher role to one or more other users in your production environment.
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.
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.

The tenants in your development and production environments may have the same name although this is not required.

Live Forms In-house Single Server Installations

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 server.

Cloud Tenants

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.

Details

Publishing Forms/Workflows from Development to Production

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.

Follow these best practices:

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.
Assign the frevvo.Publisher role to one or more other users.
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).
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.

Updating a Form or Workflow in Production

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.

When uploading a form/workflow with the same ID as an existing form/workflow, without checking Replace, a copy will be created and the designer will see an error message: "The form/workflow that was uploaded matches the id of one that already existed so a copy was made. If you intended to replace the existing form/workflow, delete the form/workflow you just uploaded and upload it again but check off the ‘Replace’ option."

When uploading a form/workflow with Replace checked that is currently being edited by another user, the designer will see this error message: "This form/workflow is currently being edited by <user@tenant>. Please try again later."

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

Download the form from your production account.
Upload the form to a NEW or Existing project in your development environment.
Make the changes.
Download the updated form/workflow from your development account.
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.
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.

Editing Forms & Workflows In Use

When a production workflow that has pending tasks associated with it is edited and replaced with an updated version, pending tasks will contain the changes the next time they are "performed" from the task list. For example, let's say you

Add or delete controls in a signed section and there are workflows pending in flight that have already been signed.
Add/remove a field that was used in a business rule; ex: Add/remove a column from a table that was used in a calculation.
Change a spreadsheet that you are reading from or writing to using the Google connector.

When you edit a workflow and change business rule or add/remove fields, all the pending tasks pick up the latest version of the workflow. Pending tasks for a form/workflow that integrates with a Google sheet reflects any changes made to the Google sheet while the tasks are in-flight.

There are some restrictions if you want to update a production workflow without causing problems in existing workflows that are in-process:

If you add new controls, and make them required/mandatory, then the workflows which are already in-process might get stuck. This can happen if the controls that you added are visible in prior steps of workflow, but they are hidden (via rules) in later steps. If an existing workflow has already reached later steps when you add these required controls, then there won’t be any value in these hidden controls when user loads his step. As these required controls are empty, won’t allow the user to submit his step. A work-around could be to use a business rule to make these control not required if the workflow was started before certain date.
When you edit existing controls in the workflow, you will have to make certain that underlying schema does not change. For example, if you have some controls in a Section, and you edit the workflow and move these controls outside that section or to a different section, this will change the underlying schema, and will cause the existing in-process workflows to not work correctly. We recommend that you do not change the base structure/schema of your workflows once they are in production

The best approach is to finish all existing workflows before uploading/replacing with the edited version. You can prevent users from starting new workflows (while you are waiting for existing workflows to finish) by temporarily changing the Access Control for Who can start the form/workflow? to "Designer/Owner only" that no one else can access it.

Form/Workflow designer edit ACL

The Access Control feature in allows the designer to assign other users permission to make changes to forms and workflows.

The ability to edit a form/workflow should not be given to other users if the form/workflow is in production. Giving this permission would enable those users to edit your production forms directly thereby subverting the best practices described in this guide.

Multi-Tenant Scenario

Development Tenant

It is best to have the roles in your test tenant match the roles in your production tenant. This enables testing of forms/workflow in development for ACL and navigation without having to edit your form/workflow before deploying the updated form/workflow to production.

Create test users in your development tenant. If you are using the default security manager, simply create the test users in the tenant. Refer to Customers using the LDAP/SAML/Azure Security Manager if you are not using the default security manager.

The role names in your development tenant should be the same as the role names in your production tenant. If they are different, modifications to your workflows will have to be made to users and workflows to reflect the production roles.
Multiple designer users can create and test forms/workflows in each of their user accounts using the test users and roles.
The designer users will download a finished and tested project and check it in to a source code repository (versioning) as the new version of the project. Ex: SVN, CVS, Google drive.
When further updates/modifications are required, the forms/workflows should again be edited in the designer user accounts and then upload/replaced in the generic production user account.

Production Tenant

Create a generic production user account that has the frevvo.designer role (ex: “production@<your tenant>") on your production tenant to which you publish all forms/workflows.
Assign the frevvo.publisher role to one or more users. These users have permission to upload new versions of your projects to your production user account.
One of the users with the frevvo.Publisher role 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

Customers using the LDAP/SAML/Azure Security Manager

If you are testing in a multiple tenant scenario, we recommend that both your dev/test and production tenants are configured with the same security manger. This is recommended for the following reasons:

The only way to guarantee the same behavior for both tenants is to configure both with the same security manager.
Each tenant should point to its own instance of your security manager.
For example if you are using LDAP, a development LDAP domain with a set of LDAP groups that are EXACTLY the same as your production LDAP domain is suggested. This way workflows can be moved from your development tenant to your production tenant and workflow navigation w/roles is guaranteed to work correctly.
The generic production user account (ex: "production") must be created in your IDP (LDAP, Azure, SAML).