Manage GIS Connections

Use the GIS Connection Manager command to establish a connection to a GIS data source and specify a connection name for easy referencing when using other GIS commands that require the connection. One or more GIS data connections can be stored in your VCE project, allowing them to be reused when required and shared through project templates.

TBC allows you to connect to the following types of GIS data sources to download schemas and upload features as applicable:

  • Shapefile
  • File geodatabase
  • Enterprise geodatabase
  • Esri service
  • Postgres database
  • SQL Server Service

Table showing function/feature support for GIS data sources...

Table showing additional information on Esri service providers...

Note: To understand how coordinate systems are handled when working with GIS connections, see Working with Coordinates Systems in GIS Connections.

Prerequisites:

To set up a new GIS data source connection:

  1. Select GIS Connection Manager in GIS > Connection to display the GIS Connection Manager command pane.

    Any existing connections are listed in the Connections list.

  2. Click the New button.
  3. In the Connection name field, enter a reference name for the connection that you can select when using the Get GIS Schema command or Write Features to GIS command.
  4. In the Data source type drop-down list, select the source type to which you want to connect.
    • Shapefile

      After selecting this data source:

      1. After selecting this data source, click the Connect button.
      2. In the Open dialog, select one or more (use Ctrl + click) shapefiles you want to include in the connection and click Open.

      Properties for the connection are displayed in the Properties list in the GIS Connection Manager.

    • File geodatabase

      This source type supports both ArcGIS Pro (if installed with license) and File geodatabase (if ArcGIS Pro is not installed).

      After selecting this data source:

      1. Check or uncheck the Use feature name instead of alias check box to select to use either GIS feature class names (checked) or feature class aliases (unchecked) for the creation of corresponding feature codes in the Feature Definition file. Aliases tend to be more descriptive than names, but they can be very long, or identical for different feature classes. Names are always unique.
      2. Click the Connect button.
      3. In the Select Geodatabase dialog, select the folder containing the file geodatabase you want to include in the connection and click Select Folder.
      4. In the Data provider drop -down list, select FileGeodatabaseProvider.
      5. Optionally, select an XSLX file containing XLSForm definitions coming from ArcGis Survey123 Connect. This helps to enhance the feature definition with pick-lists, aliases, and description values.
      6. Optionally, check the Merge common coordinates to points per layer check box to merge GIS coordinates into points in TBC to ensure points are referenced within the geometry along with coordinates.
      7. Click OK.

      Properties for the connection are displayed inthe Properties list in the GIS Connection Manager.

      Note that the File geodatabase provider does not support the updating of non-simple feature types in geodatabases, such as feature classes involved in geometric networks and topologies. In addition, it does not support feature classes involved in relationship classes.

    • Enterprise geodatabase

      After selecting this data source:

      1. Check or uncheck the Use feature name instead of alias check box to select to use either GIS feature class names (checked) or feature class aliases (unchecked) for the creation of corresponding feature codes in the Feature Definition file. Aliases tend to be more descriptive than names, but they can be very long, or identical for different feature classes. Names are always unique.
      2. Click the Connect button.
      3. In the Open dialog, locate the geodatabase connection (.sde) in the Database Connections folder and click Open.

      Properties for the connection are displayed in the Properties list.

      Notes:
      - The Enterprise geodatabase provider does not support the updating of non-simple feature types in geodatabases, such as feature classes involved in geometric networks and topologies.
      - To connect to an ArcGIS Enterprise geodatabase, you must first create a connection (.sde) to it in ArcGIS for Desktop. See the ArcGIS documentation for additional information.
      - Connections to data source types other than ArcGIS Enterprise geodatabase and file geodatabase are not supported.
      - The Select a Geodatabase dialog is a standard ArcGIS dialog over which TBC has only limited control; exercise care when using this dialog.
      - See your ArcGIS user documentation to determine which versions of the product are supported on the various versions of the Windows operating system.
      - For more information on creating an ArcGIS Enterprise Geodatabase provider connection, including ArcGIS licensing requirements, see Configure and Troubleshoot an ArcGIS Enterprise Geodatabase Provider. Also, see Working with Coordinate Systems in GIS Connections.

    • Esri service

      This data provider type allows connections to Esri ArcGIS feature services published or hosted in ArcGIS Portal (Enterprise) or ArcGIS Online using an OAuth2 authentication flow. Feature services backed by an enterprise geodatabase as well as feature layers are supported. Once the connection properties have been defined and TBC connects to the feature service, you will be prompted for login credentials using a standard ArcGIS authentication form. You must have an appropriate role (or user type) assigned in ArcGIS Portal or ArcGIS Online in order to read and write data through the feature service.

      Note: If you intend to use features services from an organization’s instance of ArcGIS Portal, it is an Esri requirement that applications authenticating with ArcGIS Portal using an OAuth2 authentication flow are first registered with the Portal by an organization’s administrator. During this one-time registration, two important connection parameters (Client ID and Return URL) are determined and will be constant for that instance of ArcGIS Portal. Your ArcGIS Portal administrator should be able to provide these values to you. For more information on how to register TBC with your instance of ArcGIS Portal, click here.

      Note: When writing feature data to a GIS connection, each feature is assigned a unique identification number. Use Project Settings > General Information > Reference number to browse a file list and select a unique identifier for your project. You can use the project Reference number, if that configuration is available, to identify the project from which each feature comes. You can filter the feature service data using this unique ID.

      After selecting this data source:

      1. Click the Connect button. Then, In the Select GIS Data Source dialog, do the following:
      2. Enter or select the Feature service URL.

        If you have already connected to one or more Esri service providers since your last installation of TBC, each of those connections is available for selection in a drop-down list.

        This URL is easily discoverable through ArcGIS desktop or web tools and is typically in the form:

        https://<host>/<uniqueID>/ArcGIS/rest/services/<serviceName>/FeatureServer/

        It will always end with /FeatureServer (with or without the trailing slash). Note that the <uniqueID> portion of the URL may not be present when working with ArcGIS Portal URLs.

      3. If necessary, enter the Authentication URL.

        This URL is required only when TBC cannot discover it from the specified Feature service URL. If you are unsuccessful in connecting to the feature service without it, you can try providing it manually here. This URL can have a different hostname than what’s used in the feature service URL, but it will generally end with
        /sharing/generateToken or /sharing/rest/generateToken

      4. If necessary, enter the Client ID and Return URL.

        These properties are required only when connecting to feature services from an organization’s instance of ArcGIS Portal. TBC will remember the last used values, so it is necessary to enter them only the first time (per TBC installation). Typical values are:

        Client ID = <16-character alphanumeric string>

        Return URL = my-app://auth

      5. Optionally, check the Densify geometries with true curves check box to convert true curves to straight line segments on import.

        For feature services backed by an enterprise geodatabase and published on ArcGIS Portal, line and polygon feature geometries can contain true curves (for example, ellipsoidal arcs) and TBC has been enabled as a true curve client from an Esri perspective. However,, the import of true curve data is not fully supported in TBC at this time, and so for datasets that may contain true curve geometries, you should check this check box.

      6. Click Select.

      Properties for the connection are displayed inthe Properties list in the GIS Connection Manager.

    • Postgres database

      TBC supports the exchange of geometry and GIS data with PostGIS, a spatial database extender for PostgreSQL object-relational databases. PostGIS provides support for geographic objects, allowing location queries to be run in SQL.

      After selecting this data source:

      1. Click the Connect button.
      2. In the connection dialog, enter the URL, Database, and Port to use for the connection, along with your login credentials.
      3. Optionally, select an STC Configuration file (generated by QGIS Desktop for STDM) to use for the exchange of features and/or attributes and to populate the project's Feature Definition Library as necessary.
      4. Optionally, check the Merge common coordinates to points per layer check box to merge GIS coordinates into points in TBC to ensure points are referenced within the geometry along with coordinates.
      5. Click OK.

      Properties for the connection are displayed inthe Properties list in the GIS Connection Manager.

    • SQL Server Service

      After selecting this data source:

      1. Click the Connect button to display the Select SQL Server GIS Data Sourcesdialog.
      2. In the Select SQL Server GIS Data Sourcesdialog, select the Server to which you want to connect.
      3. Enter authentication credentials.

        All databases on the selected server containing spatial features are displayed in the Database drop-down list.

      4. Select the Database to which you want to connect.
      5. Click OK.

      Properties for the connection are displayed in the Properties list in the GIS Connection Manager.

    To avoid serious errors when writing data to, or reading data from, the GIS data source, the coordinate system specified in your TBC project must match the coordinate system specified in the GIS data source, or you must specify a resolution if there is a mismatch. Note the following:

    • TBC attempts to find a Trimble coordinate system that exactly matches the coordinate system specified in the GIS data source (which is typically in OGC WKT format). If an exact match cannot be found, an Error dialog displays stating that a new coordinate system will be constructed based on available parameters in the GIS coordinate system. Click OK to continue.
  • If the Trimble coordinate system matching the file geodatabase coordinate system (or constructed for it based on available parameters) does not match the coordinate system currently specified for the project, the GIS Coordinate System Mapping dialog displays. Use it to specify whether to:
    • Change the project coordinate system to match the GIS (file geodatabase) coordinate system and not transform grid coordinates
    • Keep the project and GIS (file geodatabase) coordinate systems and transform the grid coordinates
    • Consider the project and GIS coordinate (file geodatabase) systems to be the same and not transform coordinates
  • Specify the elevation type coming from the GIS data source: Orthometric heights or Ellipsoidal heights.

    Click OK after making your selection.

    • If the GIS data source includes multiple coordinate systems, you are prompted to either use the first one found or cancel the connection.
    • Feature coordinate elevations will be used when writing features to GIS connections with 3D coordinates.
  1. When you are done, click Close.

    You are now ready to download (get) a GIS schema containing feature definitions from the selected GIS data source and upload (write) processed feature data matching the schema to the GIS data source.

To change the name of an existing GIS data source connection:

  1. Select GIS Connection Manager in GIS > Connection to display the GIS Connection Manager command pane.

    All existing connections are listed in the Connections list.

  2. In the Connections list, select the connection you want to edit.
  3. In the Name field, enter edits as necessary.
  4. When you are done, click Close.

To remove a GIS data source connection:

  1. Select GIS Connection Manager in GIS > Connection to display the GIS Connection Manager command pane.
  2. In the Connections list, select the connection you want to remove.
  3. Click Remove.

Related topics

Work with GIS Data Sources

Download (Get) a GIS Schema and Export It to an FXL File

Upload (Write) Processed Features to a GIS Data Source

Download (Read) Features from a GIS Data Source

Upload (Write) Observation Metadata to a GIS Data Source