Skip to main content

Admin Guide

Installing TEAM frevvo eforms Integration​

Prerequisites:

  1. Vault Application *.mfappx file
  2. License *.lic file
  3. Installed M-Files admin with connection to vault

Please refer to the M-Files documentation for how to install and license a Vault Application.

M-Files Admin Configuration​

The application must be configured to function correctly. This configuration may be found in M-Files Admin:

  1. Open M-Files Admin and navigate to the vault on which the application is installed
  2. Select Configurations then expand Other Applications
  3. Select TEAM.FrevvoIntegration showing the Dashboard which includes useful troubleshooting information
  4. Select the Configuration tab

Required Configuration​

  • Frevvo URL is the domain at which the frevvo server exists. Everything before "/frevvo in the URL. This is only required for on-premise installations. The default/empty value is for cloud
  • Frevvo Tenant is the tenant to which the below user and configured forms belong.
  • Frevvo Tenant User is the designer user within the tenant who has access to all forms that will be ingested into M-Files. Include the "@tenant" suffix.
    • Important Note

    For ingestion to work, all of the configured forms must be created by this user - this is a limitation imposed by the frevvo API.
    If forms have been created as other users, then they may be exported and reimported as the designer user. Future submissions for this imported form will ingest into M-Files per configuration here

  • Frevvo User Password is the password for that tenant user.
  • Is Tenant using SSO? For tenants using SSO, the specified credentials must be for the non-SSO tenant admin usually named 'admin@tenant'
  • Database Time Zone If using frevvo cloud/web, this parameter is required. Format should be a Modern Time Zone String e.g. Chicago/America.

Optional Configuration​

  • Generate Required Properties if set to Yes, then the required Form Object properties that cannot be found will automatically be created during polling. Required properties include Embed URL (TI.eForms.Property.EmbedURL) of type Text (multiline) and Submission ID (TI.eForms.Property.SubmissionID) of type Text. Note that if set to No, then these properties must manually be created. Recommendation: use this
Important Note

The required properties CANNOT be generated via the "Poll Frevvo" button in the client. They must be generated via the background poller. Thus before using the "Poll Frevvo" button for the first time, you must let the poller run at least once. To do this go to the Dashboard in M-Files admin and click the "Run now" button next to "TaskType.FrevvoPoller"

  • Allowed Button Run Frequency is the frequency in minutes with which a user is allowed to use the run poller button in the UI. The restriction applies to all users. Set to 0 for no restriction
  • Submission Polling Frequency controls how frequently M-Files checks for new submissions in frevvo. A common interval could be every 10 minutes
  • Submission Time Query Filter is the timespan in minutes from which form submissions will be polled. E.g. if set to 60, only forms submitted in the last 60 minutes will be queried. If set to 0, all submissions are queried without any timespan restriction. Setting this slightly higher than the Polling Frequency is recommended for performance
  • Submit New Form Buttons each entry in this list will be shown in the M-Files UI as a button under the frevvo group in the left hand side menu
    • Command Name is the label for the command that will be added for submitting this form
    • Raw Flow Link is the share link for this form obtained in frevvo
      Raw Flow Link
    • User Groups with Access are the User Groups that should have access to this form. Empty implies all users
  • Show Poll Frevvo if set to No, then the Poll frevvo button in M-Files will no longer be shown. If set to Yes, then Poll Frevvo User Groups may be specified
  • Poll Frevvo User Groups are the User Groups that should have access to the Poll Frevvo button. Empty implies all users
  • Show eForm Tab If set to No, then the eForm tab in the M-Files desktop client will not be shown
  • Security Protocol In general leave set to the default TLS1.2. If experiencing errors when polling in on-premise environments, this may need to be adjusted.
  • Logging Configuration general logging information is always shown on the dashboard. Additional logging may be configured here. See M-Files documentation for details.

Form Mappings Configuration​

The next step is to configure how forms are ingested from frevvo. Each entry under "Frevvo Forms" maps onto a form or flow within frevvo.

  • Form Name custom string label
  • Frevvo Form ID this must be copied from frevvo in order to map the correct form. To find this ID:
    • Log in to frevvo as a designer user and navigate to the form or flow
    • Click Share and select Raw flow link
    • Copy the portion of the URL following formtype/ for forms or flowtype/ for flows. Make sure to not include the forward slash '/' nor question mark '?'. This is the Form ID.
      Form ID
  • Form Object Type select the M-Files Object Type that submissions of this form should be created as in M-Files. Note that for non-Documents, the object type must be configured to allow having files
  • Form Object Class select the Class that submissions of this form should be created as in M-Files. Must exist under the above Object Type
  • Automatically add Name or title if set to Yes, then the "Name or title" property will automatically be added to the form if it is not already set by the Form Field Property Mappings. This should be set to No if the Class of object being created does not use "Name or title" as its display name property
  • Date Format by default forms are named as "<Form Name> (Date Submitted)". This field customizes the format of that date for this form. Uses simple date format standard e.g. MM-dd-yy
  • Include All Attachments if set to Yes, all attachments are included as files for the resulting M-Files object (default). If No, you may specify which attachments to include below
  • Attachments
    • Include Snapshot? will include the PDF overview of the form if enabled in frevvo
    • Display Name custom string label
    • Attachment/File Name may be used to identify the file to be attached to this object by name whether that be the original file name or the name of the generated form. Note that this will take precedence over the next field.
    • Form Field Name may be used to identify the file(s) to be attached by the name of the form field through which this attachment is added to the form. If the field includes multiple attachments, then all will be added.
Note

Invalid or missing property values will be automatically logged and skipped, but the form/object will still be created in M-Files.

  • Form Field Property Mappings each mapping will set a property on the M-Files Form Object to the value of some data from the form or statically. Make sure all of the required properties for the selected Class are populated.
    • M-Files Property
Tip

If the Property selects from a Value List or Object Type then the provided value, static or dynamic, must be the integer ID of an existing object/value list item. Multi-select value IDs should be delimited by spaces

  • Property Value Type selects from Static and Dynamic
    • Name of Field in Form if Property Value Type is Dynamic then this must exactly match the Name of the property as it appears in the frevvo form builder and its XML data
    • Static Property Value if Property Value Type is Static then this is the value to which this property should be set
  • Use for Unique Lookup is ignored. This parameter is only used for FormObjects
  • Form Objects optionally specify additional M-Files objects that should be created and related to the form. Descriptions for the form above apply to most of these settings with some noted exceptions
    • Object Name
    • M-Files Object Type
    • M-Files Object Class
    • Include All Attachments
    • Attachments
    • Object Field Mappings
      • M-Files Property: same details as above for Form Field Property Mappings.
        • Important Note: the Object Field Mappings must contain the designated "Name" property for the Class of object being created along with all other properties marked as required for the class. If any of these are not included, then the object will not be created.
      • Property Value Type
        • Name of Field in Form
        • Static Property Value
      • Use for Unique Lookup if any properties have this set to Yes, then a search is performed for existing objects with the specified Type, Class, and all enabled unique property values. If an object is returned, then this object is updated and referenced instead of creating a new object
        • Example a new employee must fill out a series of forms for the onboarding process. They fill out their I9 which is created in M-Files along with a linked object, Employee, which has their Name, Email, DoB, etc. from the form. The property mapping for Email has this parameter set to Yes. When the same employee then later submits their NDA, the search finds their employee object and links the form to that rather than creating a duplicate Employee

UIX Configuration​

Once forms have been successfully imported into M-Files, they may be viewed in a dashboard tab using the M-Files desktop client. If any of the form fields are configured to pass data into the form tab, then the form will be initialized with these values. Consider the following example use case:

  • A contractor is managing projects with various customers. Customers are tracked as objects. An Invoice form has been created in frevvo which will be sent to Customers. Step 1 of this form can be completed and issued directly in M-Files from a tab shown on selecting that customer.

M-Files only allows external content to be viewed in a dashboard tab if the domain from which that content is served has been added to a list of trusted sites in the UIX application definition file. If this step has not been taken, then an error will be seen when selecting the form and loading this tab, "The dashboard may not use untrusted content":

Domain

To fix this error, your frevvo domain must be added to this trusted sites list:

Note

These steps are only necessary if frevvo is being used In-House/On-Premise AND it will be embedded in an M-Files dashboard

  1. Locate the provided application TEAM.FrevvoIntegration.mfappx or export it from your vault
    1. Open M-Files admin and navigate to your vault.
    2. Right click and select Applications
    3. Select TEAM.FrevvoIntegration and click Export...
      Export
  2. Extract (unzip) all contents from the application
  3. Locate UIX.zip in these contents and extract (unzip) all contents from it
  4. Open the contained file, appdef.xml, in a text editor
    1. Note: make sure you open appdef.xml under the UIX zip, not the appdef for the vault application. There are two of them.
  5. Within <dashboard id="MyDashboard">, add an entry for:
    1. <trusted-content>http(s)://frevvo-domain:portIfPresent</trusted-content>
      Export
  6. First rezip the contents of UIX.zip
    1. Note: the contents must be at the root level of the zip. If they are inside of a folder, the application will fail to function.
  7. Then rezip the contents of the application making sure to include the new UIX.zip and not the old one. Also ensure the contents of the zip are at the root level
    1. Note: it is not important what the application file is named, and it may be either a ZIP or MFAPPX file. However UIX.zip must be named exactly as such.
  8. Reinstall the vault application, restart the vault, and relog in M-Files
  9. Done, the untrusted content error should no longer appear