FX DataGuide Setup

Introduction

FX DataGuide allows you to create simple to complex forms. You can use advanced logic to determine questions that show to users based on answers given in the form or other criteria. Maintain multiple versions of a form and select the form that should display to users. You can connect forms to a job, to a ticket, or leave them independent from a specific record.

The module must be installed, setup, and configured in Back Office. Once that is completed, a form must be created to use in FX Mobile by a mobile user. DataGuide forms can also exist in the Back Office to be completed by a Back Office user.

Prerequisites

To setup and use FX DataGuide, you need to:

Have these user licenses Have these permissions Complete these tasks
and review these topics
before continuing

  • System Administrator permissions for Salesforce

FX DataGuide requires Lightning Managed Package version 1.135 or later.

User Roles

In FX DataGuide, users fit these types:

Users Form Designers Data Analysts

Select and complete forms in FieldFX Mobile or FieldFX Back Office

Create Forms and Form Versions in the Admin Portal’s DataGuide tool

Use their business intelligence solution to interpret or report on the data collected from users

Prepare Back Office and Install FX DataGuide

Perform these actions to in your org’s Back Office:

  1. Enable the background sync upload

  2. Install the FX DataGuide package

  3. Add FX DataGuide Lightning Component to Lightning Component Pages

  4. Assign user permissions

  5. Schedule the population of form results

  6. Define form AutoSync rules

Enable Background Sync Upload

FX Data Guide utilizes the new Background Sync Upload functionality in Sync V4.

You need to modify FX Settings, grant user permissions for the Background Sync Upload, and set up Attachments to use the Files API.

Modify FX Settings

  1. In Setup, enter Custom Settings in the Quick Find box, the select Custom Settings.

  2. Click FX Settings.

  3. In Custom Fields, click New button.

  4. Select Checkbox Data Type radial button, then click Next button.

  5. In Field Label, enter EnableAutoSync and select the Default Value as Checked, then click Next button.

    The Field Name autopopulates with EnableAutoSync. Keep the entry as the default.

    You can optionally add a Description and Help Text.

  6. Confirm the information, then click Save button.

  7. Click the Edit link next to Custom Setting Definition Detail.

  8. Click Edit button.

  9. Set Sync Packet Size to 60, then click Save button.

Grant User Permissions

  1. Add the Sync Events Permissions Permission Set to all Mobile users and system administrators.

  2. For direct system administrators, see the Admin Portal articles’s Sync Event Viewer and Sync Upload Errors tools for troubleshooting sync upload events.

  3. Continue with Set up Attachments to use the Files API.

Set up Attachments to use the Files API

FX DataGuide relies on the Files API to attach completed forms.

Follow the instructions to set up Attachments to use the Files API.

Make sure FieldFX Back Office users understand how to work with attachments using the Files API.

You can use the Salesforce App Exchange Magic Mover app to help move existing attachments to the Files API.

Install the FX DataGuide Package

  1. Contact Support and ask to install the FX DataGuide managed package.

  2. Wait for the confirmation email (if you, as the admin, are installing FX DataGuide yourself) that FX DataGuide has successfully installed.

  3. Continue with adding the DataGuide Lightning Component to Lightning Record Pages.

Add the FX DataGuide Lightning Component to Lightning Record Pages

If you’ll never complete forms in FieldFX Back Office, skip these steps.

  1. If users will complete forms in FieldFX Back Office, modify the Lightning Record Pages for Jobs and Tickets to include the FX DataGuide Lightning Component.

  2. Modify Lightning Record Pages for other objects where FX DataGuide forms should display.

  3. Assign the Lightning Record Pages to FX DataGuide users or as the Org Default.

    See the Salesforce documentation on Activating Lightning Experience Record Pages.

  4. Continue with Assign Permissions to Users.

Assign Permissions to Users

  1. In the FX DataGuide Minimum Permissions, to create permissions sets for FX DataGuide users.

  2. Consider creating at least three permission sets for:

    • Form designers that create and manage forms and form versions

    • Form users that fill out forms in FieldFX Mobile or FieldFX Back Office

    • Form analysts that report on the results completed forms

  3. Assign the permission sets to FX DataGuide users.

  4. Continue with Schedule the Population of Form Results.

Schedule the Population of Form Results

Data Analysts use the Form Response table to collate a report on data collected in FX DataGuide forms. An Apex class parses Form Data to populate the records on the Form Response object.

  1. From Setup, enter Apex in the Quick Find box.

  2. Select Apex Classes.

  3. Click Schedule Apex button above the list of classes.

  4. Make the following entries:

    Field Name Action / Description

    Job Name

    Form Data Normalizer

    Apex Class

    FormDataNormalizerSchedulableBatch

    Schedule Apex Execution

    Appropriate selections for the business requirements

    • The declarative tools in Salesforce only allow for scheduling Apex classes to run at most once per day.

    • To schedule the class to run more often, use the Developer Console.

    For example, to schedule the class to run hourly, run this command in the console:
    System.schedule('FormResultsHourly', '0 0 * * * ?', new FXDG.FormDataNormalizerSchedulableBatch() );

  5. Click Save button.

  6. Continue with Define AltSync Rules for Forms.

Define AltSync Rules for Forms

Carefully consider what forms should sync to mobile users.

  1. Set up AltSync and add an AltSync flag to the Form Data object.

  2. Some possible AltSync rules to implement:

    Desired Sync outcome AltSync Formula

    Users sync only the forms they created

    $User.Id == CreatedById

  3. Continue with Set up FieldFX Back Office for FX DataGuide.

Set up FieldFX Back Office for FX DataGuide

This is a general flow on how to set up FX DataGuide in the FieldFX Back Office:

  • Set up DataGuide components for Jobs, Tickets, and Forms.

  • Set up the FX DataGuide custom Lightning Experience components:

    • FXL DataGuide: an all-in-one component that combines buttons and a grid list of forms into one component

    • FXL DataGuide Buttons: displays action buttons applicable for a form selected in a linked FXL DataGuide Grid component

    • FXL DataGuide Grid: displays a list of Forms relevant the user and the user’s current context as defined in the component’s setup and the various forms' Form Subject and IsAvailable criteria

  • Enable Lightning Experience to use FX DataGuide in FieldFX Back Office.

Job, Ticket, and Forms FX DataGuide Components

  1. From Setup, click on Object Manager.

  2. In the Quick Find search box, enter Job, then select the Job object.

  3. Select Lightning Record Pages.

  4. Select a Lighting Record Page to use as a template.

  5. Click Clone.

    This is optional. You can modify the Lightning Record Page directly, but that is not recommended for pages in active use.

  6. Select on the screen where the DataGuide component(s) should go.

    Consider creating a separate Tab for Forms.

  7. In the Search box on the left side of the screen, type Data, then drag the desired DataGuide component to the desired location.

  8. Configure the component per your business requirements (see details below).

  9. Save the Lighting Page and activate it.

  10. Repeat the above steps for the Ticket and Forms FX DataGuide component.

  11. Continue with FXL DataGuide Components.

FXL DataGuide Components

FXL DataGuide

The FXL DataGuide component is an all-in-one component that combines both the button options available in the FXL DataGuide Buttons component and the grid available in the new FXL DataGuide Grid component.

Table 1. FXL DataGuide component options
Option Notes

Show 'Start a new form' Button

Show 'Complete a saved form' Button

Show 'View results' Button

Form status to fetch:

Select the forms to display:

Option Description

All:

Displays all forms in the system, limited by the other filters for the component and user.

New:

Displays only forms available to the component and user with no results.

Forms To Complete:

Displays only forms available to the component and that have been started but not yet marked complete.

Results:

Displays forms available to the component and the user that have been marked complete.

Form Subject Type:

Select Independent, Ticket, or Job.

Columns:

Fields to display on the grid.

Defaults to ID, Name

Initial Sort Column:

Specify the field to use for sorting the list of items in the grid when it first loads.

Defaults to Name

Initial Sort Direction:

Direction to sort the listed forms, either asc (ending) or desc (ending).

Defaults to abc

UID for this control (required):

A custom identifier for this component.

Sub-Title for this control:

Custom text to display below the FXL DataGuide component heading.

FXL DataGuide Buttons

Use these buttons in conjunction with the FXL DataGuide Grid component.

Table 2. FXL DataGuide Buttons component options
Option Notes

Show 'Start a new form' Button:

Displays a button to allow the user to begin a new Form Data record for the selected form.

Show 'Complete a saved form' Button:

When the form selected in the related grid has a form that is saved but not marked complete, allows the user to return to the saved form and continue working on it.

Show 'View Results' Button:

When the form selected in the related grid has a completed form available, displays options to either download the form or show the completed form on screen.

UID of Item Grid:

The unique identifier configured for the FXL DataGuide Grid component where the user will select the form to interact with.

Show the Title and Sub-Title:

Adds the heading and subheading from the related grid to the button component.

FXL DataGuide Grid

The FXL DataGuide Grid displays a list of forms based on the criteria defined in the component and the availability of forms for the logged-in user.

The DataGuide Grid can be used in conjunction with the FXL DataGuide Buttons component.

The DataGuide Grid includes the following options:

+

Option Notes

Form Subject Type

Select Independent, Ticket, or Job

Item Type

Select the type of data the grid should display, either a list of Forms or the Results of forms.

UID

A unique identifier for this particular instance of the component.

Columns

Fields from the to display in the grid.

The defaults are ID and Name

Show Title and Sub-Title

Custom text to display below the FXL DataGuide component heading.

Filter Type

Select from all, nodata, results, or unfinished.

The defaults is all.

Initial Sort Column

Specify the field to use for sorting the items on the grid when it loads.

The default is Name.

Initial Sort Direction

Select asc (ending) or desc (ending).

The default is asc.

Recommended Reading