Enterprise Dispatch Module (EDM) User Guide

Enterprise Dispatch Module (EDM) User Guide

Overview

The Field2Base Enterprise Dispatch Module (EDM) allows you to automatically upload Work Orders to the F2B Server for dispatch to your Company's Users. The EDM Sample Project Walkthrough Guide is a good way to get started using the EDM.

EDM Features and Definitions

Basic Features

  1. Automatically Upload Work Order Data to the F2B Server
  2. Provides an easy to learn Utility for creating Projects to upload Work Order data
  3. Provides a comprehensive Utility for managing the EDM Service and other administrative functions

Advanced Features

  1. Provides a method on a Backend Server to track processed Work Order data using Database Keys
  2. Provides an easy method to make User Assignments in the Field2Base System

EDM Project Manager Utility

The Enterprise Dispatch Module Project Manager is the Utility used to create and edit Projects that configure how you upload Work Order Data to the Field2Base server.

Administrator Utility

The Enterprise Dispatch Module Administrator is the Utility used to manage the Projects for uploading Work Order Data and the Enterprise Dispatch Module Service itself as well as providing easy access to Logs for troubleshooting.

Definition of a Project

A Project is the entity that contains the base information for your Company, the meta information for a Field2Base eForm, and the definitions of how you want Work Order Data uploaded to the server. The Enterprise Dispatch Module service will use a properly setup Project and convert Data from a Company’s backend server and upload it to the Field2Base Server as a Work Order document.

Definition of a Dispatch

In the Enterprise Dispatch Module, a Dispatch is the actual Data used by the application to package and create the Work Order on the Field2Base Server. There will be a queue of Dispatches that can be viewed and managed with the Administrator Utility.

Requirements to Create a Dispatch

  1. The EDM is installed on a PC on the Company’s network with access to the location where Dispatch data will be placed
  2. Access to the Field2Base Dispatch Service on the Server has been granted
  3. The PC with the EDM is installed has access to the external Internet and can connect to the F2B server
  4. A Project in the EDM has been setup and is Enabled
  5. The Form for the EDM Project has been published to the F2B Server
  6. F2B User Keys or F2B User Keys to Backend Mapping is defined

Dispatch Creation Process Overview

The EDM will take the following steps to create Dispatches based on an enabled Project. This assumes a Project has already been setup and the Dispatch service is running.
  1. The EDM will check the source location for the Dispatch data and prepare them to be uploaded
  2. The EDM will contact the F2B Server and attempt to upload the Dispatch
  3. The EDM will confirm with the F2B Server that the upload was successful and update the queue on the local machine

Data Dispatch Process Overview

The EDM will take the following steps to prepare Dispatches into the proper format and then upload the files to the Field2Base Server. 
      
Using CSV Files
  1. The EDM Service will monitor the Dispatch Source location defined in the Project
  2. When a new CSV file is placed in the folder, it will be opened
  3. A Dispatch is created for each row in the CSV file
  4. Based on the Project definition, column-region mapping pairs will be created in the Dispatch
  5. The Work Order Title and User Assignment will be included in each Dispatch
  6. The EDM Service will then attempt upload to the F2B Server as each Dispatch is prepared
  7. Once all rows in the CSV file has been parsed, then the CSV file will be closed and moved to the archive
  8. The EDM Service will then return to monitoring the Dispatch source location for new files
Using SQL 
  1. The EDM Service will run the SQL based on the interval defined in the Project (the default interval is every 10 minutes)
  2. The Pre and Dispatch Queries are run at this time
  3. If there are Rows in the Result Set from the Dispatch Query, then Dispatches will be created each one for upload
  4. No Local Files on the file system are created for this type of Dispatch
  5. Based on the Project definition, column-region mapping pairs will be created in the Dispatch
  6. The Work Order Title and User Assignment will be included in each Dispatch
  7. The EDM Service will then attempt upload to the F2B Server as each Dispatch is prepared
  8. Once all rows in the Result Set have been parsed, then the Post Query will be run
  9. The EDM Service will then wait until the next interval to run the SQL again
 

Project Manager Overview

The EDM Project Manager allows you to easily create a Dispatch Project from a Field2Base eForm for use with the processing service to send data to a Company’s backend system.


The File Menu includes basic functions of the Project Manager.
  1. New - allows you to create New Projects from Forms loaded into the Project Manager.
  2. Open - allows you to open an existing Project.
  3. Save - allows you to save a Project. There are no options to “Save As” because there can only be a single Project per loaded Form in the current system and the Project file generation is internal to the Utility. All Project files are saved to C:\Program Files\F2B Enterprise Dispatch Module\Projects.
  4. Close - allows you to close any existing Project without exiting the application.
  5. Load Forms - allows you to load Forms for use within the Project Manager.
  6. Exit - closes any existing Project and exits the Project Manager.


A. Dispatch Properties

The Dispatch Properties button opens the window with all the generic information for the Project. This includes the Form information used in the Project and the F2B Dispatch Service Access information.
NOTE: This is the window that appears when a Form is initially created and is required to begin working on a Project.

B. Dispatch Type Options

There are two types of Dispatches available for use with the Enterprise Dispatch Module:
CSV
Creates dispatches from CSV files placed in a source location on the local file system or on a location on the Company’s Backend Environment.

The required elements for a CSV Dispatch Type are:
  1. File Input Directory – Folder location where the CSV files will be placed when ready to be processed
  2. First Row Contains Headers – If First Row Contains Headers is Enabled, the first line in each CSV file will be the Column Header
  3. Columns – List of columns expected to be in the CSV file. These are the columns used for the Regionm-> Column Mapping. If the CSV file used contains headers, it is recommended that the columns use the same names as the headers. You can use the Load Sample button to load the CSV file headers automatically.
SQL
Creates dispatches using SQL from tables in a Database on the Company’s Backend Environment.

The required elements for a SQL Dispatch Type are:
  1. Database Connection String – Standard Connection String to connect to a Database. See the article on Common Database Connection Strings for more information.
  2. Transaction Level – Defines what type of transaction the SQL Queries will use when creating the result set. The Transaction Level is set to Serializable by default but can be adjusted to fit the needs of your Database’s security and transaction requirements.
  3. Schedule – Interval (in minutes) that the EDM will run the SQL
  4. Queries (Pre, Dispatch, Post) – Queries that will be used to create a result set that is used for the dispatch. A Dispatch Query is required. Pre and Post Queries are optional.
  5. Columns – List of Columns that will be returned from the SQL query result set. These are the columns used for the Region->Column mapping. You can use the Detect button to identify the columns. The Project Manager will automatically run the Queries specified for Pre and Dispatch and auto-fill in the Columns section.

C. Page Selection

Allows you to navigate through the Form pages using the arrow buttons. Alternatively, you can use the drop-down to skip directly to the page of your choosing. 

D. Zoom Options

The Zoom Options allows you to zoom in or out on the Form view.

E. Form Viewing Window

Allows you to actively work with the Form loaded for this Project. This is where you can select Regions to drag and drop when mapping Regions to columns. 
Note: The drag and drop functionality in the EDM Project Manager is slightly different from the DIM Project Manager. Columns can be dragged directly on to Regions or vice versa.

F. Mapping Window

Allows you to work with the columns . This is where you can select columns to drag and drop when mapping columns to Regions.

G. User Assignment

To make a User assignment, drag a column from the Mapping Window onto the User Assignment icon. Only one column can be used for this mapping.
Once a User assignment has been mapped, a checkmark will appear on the icon and when scrolled over, the assigned mapping will be displayed.

As with Region to column mappings, User assignments can be deleted by clicking on the “X” next to the association.
Check Map value to user guid if you plan on using the backend User to F2B User Keys method for User Assignments. See the section on the Users Manager for details.

H. Work Order Title

To specify the Work Order Title, drag and drop a column from the Mapping Window onto the Work Order Title icon. Multiple columns can be used as part of the title, but only one can be dragged and dropped in; additional columns need to be typed into the textbox using the format: {PageX@RegionName}
Once a Work Order Title has been defined, a checkmark will appear on the icon. The Work Order Title textbox will show the title for the dispatched Work Orders.

To edit or delete a Work Order Title, just click the text box of the Work Order Title and edit as needed.
NOTE: For Work Order Title Assignments, text can be included with or without Region values in it. It is important to note that any text entered like this is interpreted as a single string with any Region values mapped.
NOTE: There is a 500 character limit for Work Order titles so you should not include any region values in your title that could surpass that limit.

I. Address Mapping

The Address Mapping button resembles a house and allows you to add address details to your dispatched Work Orders. These details will appear below your Work Orders and allow your Users to access turn-by-turn directions. You can either use a street address or GPS coordinates (Latitude and Longitude) to enter Address Mapping information.

Using a street address
1. Click on the Address Mapping button.
2. Enter address information from your columns into the Address Mapping field using the "{ColumnName}" format. 


Using coordinates
The second option is to use GPS coordinates (latitude and longitude) to set a location. Enter the column name for your GPS coordinates using the "{ColumnName}" format in the Address Line 1 field of the Address Mapping window.

Creating a New Project

Loading eForm Files

The first step when creating a project using the EDM Project Manager is to load the eForm file that you need to dispatch. The Project Manager Utility uses the template information residing in the eForm and translates that information for use with the Enterprise Dispatch Module Service for processing Jobs.
.
1. Open the File Menu of the Project Manager.
2. Click on Load Forms.

3. A File Browser window will appear and allow you to browse to the folder of your choosing and select the eForm file(s) you want to create EDM Project(s) for.

Note: Alternatively, you can manually load the eForm file(s) into the Forms folder found in the Program Files folder for the Project Manager Utility instead of loading them through the Project Manager. The location of this folder is: Local (C:) Drive (or other designated Drive Letter for your PC) > Program Files (or “Program Files (x86)” for 64 Bit OS) > F2B Enterprise Dispatch > Forms

Creating a Project

  1. Open the F2B Enterprise Module Project Manager. The Project Manager will open with No Project Loaded.
  2. Go to the File menu and select New.
  3. The Open Form screen will appear. These are the available eForms that have previously been loaded into your EDM Project Manager as described in the Loading eForm Files in the section above.
  4. Select the .eform for this Project and click Open.
  5. The Dispatch Properties window will open. Fill in the Login Credentials for your Company’s F2B Account.
  6. Click the OK button.
Please see the Sample Project Setup Walkthrough Guide for a step by step guide to setting up a sample project.

Mapping Values in a Project

Before starting to map values in a Project, you need to plan which Region values should match up with which columns in your output.  It is highly recommended that you work with your Company’s back-end Server Administrator and the Form Designer to establish these Mappings prior to starting a Project in the EDM.
  1. Click on a column in the Mapping Window and hold your mouse down to select the column.
  2. Drag and drop the column on to the Region in the Form Viewing Window.
  3. The Region will becomes highlighted to show the mapping is complete.
Once a mapping in complete, scrolling over the Region or the column will display the current mapping and allows the mapping to be removed using the “X” next to the association.

Enabling a Project

Once all Mappings are complete on a Project, click on the Project Disabled button to enable your Project. The button will now display Project Enabled. This button toggles to disable/enable the Project. To disable a Project, click on the Project Enabled button.

Note: Remember to save the Project after clicking the disable/enable button. Additionally, the service needs to be started/restarted for this new Project setting to be applied.
Note: Once a Project is enabled, the default process for the EDM Service is to prepare a dispatch and process it immediately while the next dispatch is still being prepared.

Auto-Backup of Projects

The EDM Project Manager will automatically backup each version of a Project to a folder in the Field2Base Program Files folder. This backup will occur whenever the Project is saved in the Project Manager. The backed up Project will have a filename based on the Date and Timestamp with the following format: 
[Form Name].[Date of Backup].[Time of Backup].xml
The backups files are located in the following folder:
  1. 32 Bit OS: C:\Program Files\F2B Enterprise Dispatch Module\Backup
  2. 64 Bit OS: C:\Program Files (x86)\F2B Enterprise Dispatch Module\Backup
Note: If you edit a Project XML file outside of the Project Manager, backup snapshots will not be taken.
To Restore a Backup Project
  1. Go to the Backup Folder.
  2. Copy the Project (XML file) you want to restore.
  3. Go to C:\Program Files\F2B Enterprise Dispatch Module\Projects.
  4. Paste the Project (XML file) to this folder.
  5. Delete the existing Project in order to avoid conflicts.

Testing a Project

The Enterprise Dispatch Module was created to be a flexible piece of software that works in various backend scenarios. We cannot provide a standard set of Testing Steps due to the fact every Company’s Testing will be different. Since Work Orders in Field2Base are easily cleaned up, you can push them out without many restrictions in the live environment.

Recommendations to Minimize Cleanup
  1. Append “TEST” or some other Text Identifier to the Work Order Title.
  2. Push out Dispatches to a single Test User first. You can then assign to multiple Users once initial tests are successful.
  3. Keep the number of rows in the CSV or in the SQL result set to only a few Dispatches when starting. Increase that number after initial tests are successful.
Once testing is completed, you can remove all test Work Orders through the Work Orders page in the Portal. See the article on Cancelling Work Orders for more details.
Note: For cases where the number of Work Orders created during testing reach 20 or more, contact f2bsupport@field2base.com and request a bulk Work Order cancellation.

Testing Task List
  1. Test the Server Login Info to confirm there are no “Invalid Login” Exception in the Logs Viewer of the EDM Administrator Utility.
  2. Confirm the dispatches have been completely processed using the "Processed" Job Status Filter of the Queue Monitor in the EDM Administrator Utility.
  3. Confirm that your Work orders are showing up with the correct User Assignment and Title on the Work Orders page of the Portal.
  4. Confirm that the Work Order Data on a Device matches what the contents of the Dispatch on the backend were.

Using the EDM Administrator

The EDM Administrator allows you to view and manage the various aspects of the processing of Dispatch Data. The Administrator Utility is the main method to see how enabled Projects are currently processing. 

The Queue Monitor

The Queue Monitor allows you to monitor the current Job queue. You can filter your Queue based on and provides filters based on Form (Project), Date, and Job Status.

              

The Log Viewer

The Log Viewer allows you to view and filter the EDM Logs. Logs can be filtered by Form (Project), Date, and Job Status.


The Service Manager

The Service Manager displays the current status of the EDM service. It also provides the basic administrative functions to Start, Stop, and Restart the DIM Service. 


Note: The Service Manager in the EDM Administrator provides quick interactions with basic service functionality for troubleshooting instead of having to work with the Window Service Control Manager (SCM). If you ever need to directly access the service in Windows Service Control Manager (SCM), the name of the Module’s service is "F2BDispatcherService”

Users Manager

The Users Manager allows you to manage the mapping of Users from your back end for use with the EDM Service.


Note: The EDM requires your Users are set up in your Company before the Service can be put to full use because the Field2Base system assigns a unique identifier to each User when they are created on the server. This key is then used to associate the Work Order Dispatch with the User. If the Users are not set up, then there is no way to assign the Dispatches in the Enterprise Dispatch Module.

Setting Up Users

There are two methods that can be taken to setup Users for the Enterprise Dispatch Module.

1st Method: Setup User Key to Backend Mapping in the Users Manager of the EDM Administrator Utility (Most Common)
The mapping between the User information in your Backend Server and the Field2Base User Keys from the server is setup in the Administrator Utility.
In this scenario, the User identified in the Dispatch will be mapped during the processing of the Dispatch data in the EDM.
If this method is used, the Project file must have the User Assignment option for “Map values to user guids” checked. Additionally, you will need to request access to the EDM Service on the Field2Base server. 
  1. Click on the Sync button to download your Company’s list of Users from the Field2Base Server. It should take a few moments for the User download to complete. When the screen returns to the Users Managers, the previously blank list should now be filled with your Company’s Users loaded in the Field2Base system.
  2. To map the Field2Base User with the User ID for each User in your Company’s Backend Database, select an entry in the list of Users and type (or Copy and Paste) the User’s ID from your system in the entry box.
  3.  Click the Save button to update the value. The Mapping will then be stored in the EDM.
  4. Repeat this procedure for all other Users that will be receiving Work Orders.
Note: You do not have to put every User’s ID into the EDM; only the ones that will be receiving Work Orders are required.

Note: As new Users get added to your Company, you will need to run the Sync and complete this update process as they are added.

2nd Method: Add Field2Base User Keys to the Company’s Backend Database
Field2Base will provide the Company with a list of Users and their associated User Keys. Your Database Administrator will need to setup a Table with this association. This means that the User management is completely done before the Dispatch data is sent to the EDM. If new Users are added, the User Table in your Database will need to be updated with their User Key. User Keys can be requested by contacting f2bsupport@field2base.com. 

The Configuration Tab

The Configuration Tab is typically the first thing you will need to interact with when setting up the EDM post-install. In order to activate the software, you will need to provide your F2B Login Credentials. A unique activation ID will be created for the product and the EDM can be used. Post activation, the Configuration tab will display your Company ID and EDM Activation ID.


You can refresh the contents of each section by using the Refresh button. Clicking the Refresh button will make the Utility refresh the Queue Data, Log Data, or Service Status with the most recent information while still retaining any selected filters.
Note: The Enterprise Dispatch Module Service does not actively delete any of the Logs, Jobs, or Dispatch files associated with the Enterprise Dispatch Module. If storage is an issue on the PC running the application, it is recommended that a process is setup to regularly perform maintenance on these files. 


    • Popular Articles

    • Forms Designer Quick Start Guide

      Overview Field2Base Forms Designer is the proprietary software application that allows your existing paper forms to be quickly converted to a smart E-form available to your end users via our mobile and web-based Mobile Forms applications. This ...

    • Portal 11.28.2023 Release Notes

      Overview Our release notes offer brief descriptions of product enhancements and bug fixes. We include links to the current articles for any affected features. Those articles will be updated shortly after the Portal release to include new ...

    • Integration Service Configuration Guide

      How To Configure Integration Services To Allow Read/Write Access on a Network Path All of our Integration Products, including the DIM, DUU, and EDM have respective Windows Services responsible for communicating with our server. Occassionally, ...

    • Data Integration Module (DIM) Migration Guide

      Overview This article provides the information necessary to migrate the Field2Base Data Integration Module (DIM) over from one server to another. Please refer to the DIM Install Guide for the initial installation of the Field2Base DIM. Once that's ...

    • How to Check the Version of Integration Products Running on a Windows 10 Machine

      Right-click on the Start menu button. Click on Apps & Features. In the Apps & Features search bar type in the Integration Product you are looking for, eg. F2B Data Integration Module, F2B Data Upload, or F2B Enterprise Dispatch Module. Click to ...