Getting Started: TerraFlex Offline Workflow with Trimble Positions

Document created by Matt Morris on Sep 6, 2019
Version 1Show Document
  • View in full screen mode


When used with TerraFlex v4.4, Trimble Positions Desktop add-in v10.7.1.1 opens up a new workflow - TerraFlex with Offline Data Transfer and Post-Processing. While we work to provide all-new Trimble Positions Desktop add-in documentation on the Trimble Geospatial Help Portal, we hope that this Getting Started document will get you up and running. For detailed information on installation, the Administration Guide from v10.5.0.1 can still be used. For more information on post-processing, the User Guide from v10.3.0.1 can still be used. We have also recently added a FAQ document on Trimble Community that is accessible to our distribution channel.

This guide presumes you have performed the following steps, all of which are required for full operation:

  1. Installed the v4.4 version of TerraFlex on your Android or Windows device.
  2. Procured a subscription (license) for TerraFlex.
  3. Installed the v10.7.1.1 version of the Trimble Positions Desktop add-in on your desktop machine (release notes) where ArcGIS Desktop (10.1 - 10.7.1) is installed.
  4. Licensed Trimble Positions Desktop add-in using the Trimble Positions License Administrator application.
  5. Configured an office database for Trimble Positions using the Desktop Configuration application.
  6. Enabled the “extension” portion of the Trimble Positions Desktop add-in by using ArcMap’s Customize...Extensions… menu.

Creating a Project

The workflow in Trimble Positions Desktop add-in always starts with creating a project from your map document. Your map document should be authored with the layers you want to use for data collection and maintenance. All “constraints” such as data type, required/not-required, domains, default values and subtypes defined in the underlying feature classes will be respected in the project. Display settings such as layer and field names (aliases) and display fields set through the layer properties of the map document will also be used. If you want to collect photos with your features, enable the appropriate feature class(es) for attachments. All layers to be used for data collection in the project must be in the same underlying workspace (geodatabase).

To create a project:

  1. From the Trimble Positions toolbar in ArcMap, click the “Trimble icon” button - this is the Show Trimble Positions Desktop Administration Window button.
  2. In the Desktop Administration window, click the Projects button. This will open the list of projects stored in your Trimble Positions database. Projects highlighted in blue can be opened with the current map document (i.e., they reference the same workspace). A project highlighted in green is currently loaded in the Dockable Window for current work.
  3. In the Projects screen, click the Create... button. This will launch the Project Wizard.
  4. In the Project Type (first) page of the Project Wizard, select the type of project to create: TerraFlex Offline
    The screen will display any errors or warnings based on the current map document. Click Start to continue.
  5. In the Layers page of the Project Wizard, select the layers you want to use for data collection and maintenance. Click Next to continue.
  6. In the Layer Settings page of the Project Wizard, click a layer to specify which existing attributes should be used for TerraFlex autofields. For file and personal geodatabases, you also have the option to specify “new” fields that will be created in the geodatabase when the project is saved. Scroll to the bottom to see metadata fields that only get populated in the office after check-in (e.g., they won’t be included in the field data collection form). To set all of the “common” autofields for a layer, click the Add all autofields link at the top of the section. Use the Accuracy Threshold section to specify the required accuracy for the feature. This can be set for multiple layers at the same time. Click Next to continue.
  7. In the Correction Settings page of the Project Wizard, select one or more field configurations to include with the project. These are the settings for the correction sources. They will be the ones available in the Settings...Real-time Configuration select list in TerraFlex. To create a new field configuration, click the Create… button.
    1. In the General page of the Field Configuration Wizard, provide a name and description for the field configuration. Only the name will be visible from within TerraFlex.
    2. In the Real-time Settings page of the Field Configuration Wizard, specify the first and second choices for the correction source. Use the “wrench icon” button to configure Internet (NTRIP or direct) sources - type, address (IP or URL), port, mountpoint (use the “...” icon to populate and select), username, password, and correction datum (use the “...” icon to select).
    3. In the Logging Settings page of the Field Configuration Wizard, provide information about the base station(s) you intend to use for post-processing data collected in this project - distance to the base station from data collection and GNSS constellations supported by the base station. These are only used to help calculate the estimated post-processed accuracy (PPA) in the field and are not used during actual post-processing. If you are unsure of what to use here, the default selections are appropriate in most cases. Click Finish to store the field configuration.
  8. In the Project Settings page of the Project Wizard, provide a project name (must be unique within the Trimble Positions database), select the accuracy reporting setting (default is RMS - 68%), and specify how you want feature heights handled - use ellipsoidal heights, apply fixed geoid separation, or calculate heights (typically orthometric) using one of the installed geoid grid files. The project will also be associated with the current map document. Click Finish to store the project.

You should now have a TerraFlex Offline project created and set for use.

Checking Out Data 

Once you’ve created the project, all day-to-day work of managing data going to and from the field is done using the Trimble Positions Dockable Window in the add-in (typically docked at the bottom of the ArcMap window). The Dockable Window only works with the currently open project. By default, the last used project (for the current map document) will be opened when you start ArcMap and open a map document but you can use the Projects area of the Desktop Administration window to open a different project (select and click Set Current).

To check-out the project for sending to TerraFlex:

  1. Confirm that the desired TerraFlex Offline project is open and visible in the Dockable Window. If the Dockable Window is not visible, click the “Geo icon” button in the toolbar - this is the Toggle Trimble Positions Desktop Dockable Window Visibility button and can be used to hide or show the window.
  2. If you only need to take empty schema to the field for new data collection, clear the feature selections in ArcMap and click the Handle Sessions button and select the Check-out to a TerraFlex database context menu item. To check-out existing features for data maintenance (the layers must be included in the project), use your choice of ArcMap selection tools (spatial, by attribute, etc.) to first select the desired features prior to clicking the button.
  3. In the Check-out Window, select an existing TerraFlex database (.tfin) or specify a filename to create a new one. This is the file that you will need to transfer to the field. If you had selected features prior to check-out, a task will be created - provide the name and notes for this task. You can check-out multiple projects and tasks into a single file by repeating this step. Use the Show contents… link to see what’s already in an existing database. It is recommended to use a descriptive name for the database file - it will default to the name of the current project (minus spaces and illegal characters). The name is not visible within the TerraFlex field application. Click Check-Out to complete the this step.
  4. Locate the .tfin file you created or used and transfer it to the TerraFlex field device. This can be done by any variety of methods such as USB transfer, email, mobile device management software, or cloud sharing (e.g., Google Drive, Microsoft OneDrive, Dropbox, etc.). Although users are likely already comfortable transferring files to and from Windows computers, it may require a few new skills to do the same with Android devices where the operating system typically hides some of that experience. With some Android devices, directories do not refresh their contents until the USB is disconnected and reconnected.
  5. From the Android or Windows device running TerraFlex v4.4, use the appropriate mechanism (matching whatever you used in the office) to locate the .tfin file. Both Android and Windows have the concept of a “downloads” (technically \Download on Android) folder which is used by default when downloading files from email or cloud sharing apps. Various file manager applications are available through the Google Play store including Google’s own Files application.
  6. The most important step in the process: The .tfin file must be placed into a sub-folder of the common TerraFlex folder based on the username of the TerraFlex user with the “-offline” suffix, as below:
    On Android: (Internal Storage)\TerraFlex\
    On Windows: (Windows Drive)\Users\<windowsuser>\Document\TerraFlex\
    ...where is the email address of the TerraFlex user who will be logging in.

You are now ready to login to TerraFlex. If you performed step 6) while TerraFlex was open, you should logout, close it, re-open it, and sign-in again.

Field Data Collection & Maintenance

Once the check-out data (.tfin file) has been put into the appropriate offline user folder on the TerraFlex device, you are ready to begin using TerraFlex for data collection and maintenance activities. After logging in to TerraFlex using the Internet (login can be cached for up to 30 days), the operation of TerraFlex is nearly identical to the traditional, cloud workflow with a few differences:

  • If you stored multiple projects in the check-out file, you will be able to switch between them the same way you would with the traditional TerraFlex cloud workflow.
  • If you checked-out existing features as tasks, you can use them the same way you would with the traditional TerraFlex workflow.
  • To select a real-time correction source, use the Settings...Real-time Configuration application menu item to select one of the configurations you stored with the project.
  • To view the predicted post-processed values (PPA) alongside the real-time estimated accuracy (CEA), use the Location Status application menu item. These will be reported based on the accuracy reporting setting of the project (68% or 95%) and the best of CEA/PPA will be used to drive accuracy based logging.
  • During feature geometry collection, all point and line/polygon vertex geometries will log 10 positions and calculate a weighted average (based on the accuracy of each position).
  • When you are done collecting data, use the Extract Forms project menu item (in lieu of the Remove Forms menu item in the traditional cloud workflow). This will extract any new or updated forms into a .tfout package that can be transferred back to the office using the reverse mechanism as before. This will create a .tfout file in the common \TerraFlex folder with the project name and a timestamp. On Android, you will also be prompted to Share the file when the process completes - this is built-in Android functionality that can be used to easily send the file to email or a cloud sharing app. Alternatively, you can always locate the file on disk in the common \TerraFlex folder.
  • You can use Extract Forms any time you are ready to send data back to the office. There is no explicit limit on how many forms can be included in one extraction. In addition to the forms, this extracted file will include the GNSS measurements and feature constructions (i.e., “sessions”) necessary for post-processing.
  • You do not need to transfer a new .tfin file to the field every time you want to collect data - only when sending new projects, tasks, or changes to an existing project.

Once the data has been transferred off the device, you are ready for check-in on the desktop.

Setting Up Post-Processing

Prior to check-in and post-processing of data, you will need to setup one or more Processing Profiles in the Trimble Positions Desktop add-in. These profiles are shared between projects.

  1. From the Desktop Administration window, click the Processing Profiles button. This will open a list of existing profiles that have been created.
  2. From the Processing Profiles list screen, click the Create… button to start creating a new profile. 
  3. From the Edit Profile window, provide a name and choose a method for base data usage:
    Using a single base station: this is the traditional method using the Trimble Community Base Station (CBS) list
    Using a folder or specific base files: this is for when you download base data manually
    Use the Processing Options area for specifying detailed post-processing behavior.
    You will most likely use the defaults on this screen. Click Select… to pick a base station from the CBS list.
  4. From the Select Base Station window, use the radio buttons at the top to find base stations closest to a selected city or the Current map center (best to do this while you have your map document open). The list will indicate whether the base station has dual frequency and GLONASS data and will be sorted by distance to the city or map center. The Update List button can be used to download a new CBS list from Trimble (can also be done using the Desktop Configuration app). You can also use the functionality in the Base Station area at the bottom to create new "user base station" entries in the list. Click OK (on two screens) to complete the process. You should now see the profile in the list.
  5. As data is checked-in, Trimble Positions will keep track of the unique usernames used in TerraFlex Offline (or in other workflows, unique devices). From the Desktop Administration window, click the Devices button to open this list. Here, you can select an entry and use the Set Profile… button to assign a default processing profile for this user or device. This can simplify the post-processing user experience a bit (covered below).

Checking In Data

With the collected data in the .tfout file being available back in the office, you are ready to use ArcMap and the Trimble Positions Desktop add-in for check-in.

  1. Confirm that the desired TerraFlex Offline project is open and visible in the Dockable Window. If the Dockable Window is not visible, click the “Geo icon” button in the toolbar - this is the Toggle Trimble Positions Desktop Dockable Window Visibility button and can be used to hide or show the window.
  2. From the Dockable Window, click the Handle Sessions button and choose the Check-in from a TerraFlex database context menu item.
  3. In the Check-in Window, use the “...” button to select the .tfout file you got back from the field. This will display summary information about the database and enumerate the data that can be checked-in.
    Data will be summarized by task with new data collection being categorized under the New Data Collection header. You will likely notice that data has been automatically been broken into sessions depending on the usage pattern in the field - this is expected.
  4. Select the desired sessions and click the Check-In button to complete the process. This will bring the sessions into the Trimble Positions database and will also store the features (with their current geometries and accuracies) in the geodatabase. You will be notified of any problems in the check-in.

You are now ready for post-processing and QA/QC.

Post-Processing & QA/QC

After check-in, you will see one or more sessions of data in the Dockable Window. You should also see graphic outlines displayed on the map - these are an indication of session extents and are color coded by status of the session. At this point, the workflow is identical to any other post-processing workflow in the Trimble Positions Desktop add-in (TerraSync, ArcPad + Positions). The sessions are stored in the Trimble Positions database and include the feature geometries and constructions - more granularity than can be stored in the geodatabase. At check-in, features in the Trimble Positions database get linked to the features stored in the geodatabase.

  1. From the Session List (default) panel in the Dockable Window, use the View Features button to see the list of features in a selected session. This switches to the Edit Session panel of the Dockable Window. From here you can view (sortable) feature details including accuracy and antenna type as well as Zoom To the feature. You will also see features flagged as not meeting the specified accuracy threshold (can be marked as an Exception or Unlinked from the feature in the geodatabase). Use the Display estimated accuracy outlines checkbox to turn on a visual indicator of feature accuracies. Right-click in the feature table and choose the Export features to Excel… context menu item to generate data for Excel. If you made changes to features, click Apply (stays on this panel) or just Finish. Remember that at this point, you have only changed the Trimble Positions representation of the feature geometry - these have not yet been applied to the geodatabase.
  2. Continuing on to more granularity, use the View Positions button to see the list of positions in a selected feature. This switches to the Edit Feature panel of the Dockable Window. From here you can view (sortable and groupable) position details including construction hierarchy, observation time, status, and accuracy. To view even more detail, use the Show Extended Data checkbox at the top - this adds vertical accuracy, correction type, PDOP, satellites, and antenna height. Use the List View or Tree View radio buttons to choose the desired layout (only really useful for line and polygon features with a mix of construction types). Use the Display estimated accuracy outlines checkbox to turn on a visual indicator of position accuracies. Right-click in the position table and choose the Export positions to Excel… context menu item to generate data for Excel. To remove (or re-add later) specific positions from the geometry construction, use the checkboxes in the list or the Use All button to include all of them. The Edit… button is only used with offset construction types. Click the Finish button to return to the previous Edit Session panel where you will need to use Apply (stays on the Edit Session panel) or Finish (returns to the Session List panel).
  3. From the Session List panel, select one or more sessions and click the Correct… button to begin post-processing. This will open the Correct Sessions window. 
  4. In the Correct Sessions window, you’ll see the list of sessions that you selected for post-processing. Use the Processing Profile to Use list to choose a profile to use for post-processing. They will be sorted by distance from the session and any default profile (for the user/device) will be the first choice in the list. Click the Correct button to begin processing. Detailed status and progress messages will be displayed in the large area to the right. These messages will also be saved to the Trimble Positions Desktop add-in log file. You can also use the Save to file… link to store just those messages to a new file. Close the window when the screen indicates that processing is complete (a summary will be presented at the bottom of the progress notification area).
  5. At this point, you will see the updated status of the session(s) in the list. You can also use the functionality described in 1) and 2) above to view the new feature geometries and positions which will reflect the post-processed accuracies. The feature graphics displayed on the map will indicate the new (pending) feature geometries which still have not yet been applied to the geodatabase (see 6) below).
  6. From the Session List panel, select one or more sessions and use the Update Features button to apply the new feature geometries to the geodatabase. This will also update all relevant autofields and metadata attributes as well.
  7. For additional QA/QC functionality in the Session List panel of the Dockable Window, right-click a session entry in the table and choose one of the context menu items:
    Zoom to: zooms to the selected session (same as the Zoom To button)
    Restore to original: restores all feature geometries and accuracies to their original state (before post-processing and editing); useful for re-doing the processing step#
    Show troubleshooting info: opens a window showing graphs of satellite count and average signal-to-noise ratios (SNR) for the session
    Properties: opens a list of technical properties of the session
  8. Once you are done with a session (they do take up some space in the Trimble Positions database) and have already updated the geodatabase with the results of post-processing, you can use the Remove button on the Session List panel to delete sessions from the Trimble Positions database.