Setup¶

Download¶

A copy of the GeoCat Bridge for ArcGIS® Pro add-in can be obtained from the GeoCat software repository.
The add-in is fully functional, but will run in Community Edition mode (so you can try it out) until you activate it with a valid license.

Alternatively, you can contact us so we can help you get the software on your system.

Installation¶

Once you have downloaded the add-in file, installation is easy.

Assuming that you already have installed ArcGIS Pro on your system, the only thing you need to do is double-click the GeoCat.Bridge.esriAddinX file. This will unpack the add-in, copy the binary files to the right location(s) on disk and register it.

Warning

Always make sure that there are no running instances of ArcGIS Pro during the installation process.

When you double-click the .esriAddinX file, you should see a dialog similar to this:

Digital Signature

GeoCat bv will always ship Bridge with a digital certificate.
Please ensure that the add-in file has been signed with a valid certificate before you hit the Install Add-In button, and make sure that the details look similar to the screenshot above.

Alternatively, you can also let Pro load a shared add-in at startup from a so-called well-known folder. This approach is especially useful for administrative installations.

Details about setting up shared add-ins, or deleting (uninstalling) or disabling an add-in can be found in the official ArcGIS Pro documentation. If you wish to temporarily hide the GeoCat Bridge toolbar without uninstalling it, you can customize the ribbon.

Configuration Files¶

GeoCat Bridge stores its configuration in one or more GeoCat.Bridge.config files.
These XML files can either be shared (i.e. for all users) or personal (current user).

License Files

In addition to the configuration files, GeoCat Bridge may also look for license files named GeoCat.Bridge.lic in the same directories as the configuration files. See the Activation section for more information about licensing.

Load Order¶

When GeoCat Bridge is started, it will look for GeoCat.Bridge.config files in the following order:

A shared configuration in the directory as defined by the BRIDGE_HOME system environment variable (if present).
Any configuration(s) in shared add-in directories that ArcGIS Pro is aware of.
The personal configuration in the user profile directory (e.g. %USERPROFILE%\Documents\ArcGIS\AddIns\ArcGISPro\{9d56cd06-73bd-4e0e-bca4-3c037e21aecb}).

File Structure¶

Each configuration file consists of a set of so-called data spaces and a list of general options.

It also keeps track of when the configuration file was last modified, and which model version it has.

The model version should be compatible with the version of GeoCat Bridge that you are running.
If the version is lower than the actual version, GeoCat Bridge will try to upgrade the configuration file(s) automatically.

Info

If GeoCat Bridge cannot find any (valid) configuration file(s), it will create a new personal one in the user profile directory. That file will have all the default global options, but does not contain any data spaces.

General Options¶

GeoCat Bridge will use the global options of the first shared configuration that is found (see search order above). Since these apply to all users, they will overrule any global options in the user profile configuration, and will be read-only.

If no shared configuration is found, the global options from the personal user configuration will be used. In that case, the user will also be able to change these options.

Data Spaces¶

Data spaces can be shared or personal.

A data space from a shared configuration file will be available to all users, and it is read-only.

By default, each newly created data space is stored in the personal configuration file (in the user profile). This means that these data spaces are editable by the user that created them.

Info

If you notice that all your data spaces are missing when you start GeoCat Bridge, then it is likely that the configuration failed to load, and that a new (empty) personal configuration file was created.

If this happens, please check the log files for any errors.

However, GeoCat Bridge should always create a backup of the configuration file before it loads it, so your original configuration file should not be lost.

If you keep having problems, please contact GeoCat support and send us the backup file, so we can investigate the issue and possibly repair your configuration.

Administrative Install¶

Administrators may wish to deploy GeoCat Bridge from a shared add-in directory as described in the previous sections. This will ensure that the GIS users in your organization all use the same version and/or configuration of GeoCat Bridge.

As an admin, you should first install Bridge locally (see previous sections), activate it, and configure Bridge according to your liking.

Next, you need to copy/move the .esriAddinX file to a shared add-in folder, along with the GeoCat.Bridge.config and GeoCat.Bridge.lic files that Bridge has saved in %USERPROFILE%\Documents\ArcGIS\AddIns\ArcGISPro\{9d56cd06-73bd-4e0e-bca4-3c037e21aecb}. (1)

ArcGIS Pro uses unique identifiers for each add-in, and 9d56cd06-73bd-4e0e-bca4-3c037e21aecb happens to be the ID that was generated for GeoCat Bridge.
This ID will likely always remain the same for the lifetime of GeoCat Bridge for ArcGIS Pro.

Access privileges

You may want to restrict the access privileges (ACLs) of the general GeoCat.Bridge.config file to prevent regular users from manually editing a configuration XML file (and potentially breaking it).

Now, when other users open ArcGIS Pro, the Bridge add-in will be loaded together with the configuration that you set up, and GeoCat Bridge will also be activated using your license key/file.

Your users will not be able to alter the data spaces and general options that you pre-configured for them. However, they will be able to create their own data spaces.

Duplicating administrative Data Spaces

Users can duplicate a data space that has been configured by an administrator. However, any encrypted passwords that may have been stored in the configuration will not be copied and the unique identifiers of these data spaces will change as well.

Bridge Home Directory¶

There may be scenarios where you wish to keep the GeoCat.Bridge.config file separated from the shared add-in directory.
If this applies to you, then you may set a BRIDGE_HOME system environment variable and point it to the directory path that contains the GeoCat.Bridge.config file.

For example, if your file is located at C:\MyConfigs\GeoCat.Bridge.config, then you should set the BRIDGE_HOME variable to C:\MyConfigs\.

Warning

The BRIDGE_HOME directory is only intended for shared configuration and/or license files. You should not place the actual GeoCat.Bridge.esriAddinX file in this directory.

Updating Bridge¶

When a new version of GeoCat Bridge is released, you can simply download the new version from the customer portal and install it over the existing version.

Make sure that ArcGIS Pro is not running during the installation process. Once the new version is installed, you can start ArcGIS Pro again, and GeoCat Bridge should automatically update your existing configuration, if required.

Tip

GeoCat takes great care that your configuration is properly migrated to a new model version.
However, you may wish to backup your configuration file(s) before you update GeoCat Bridge.

Administrative updates

For administrative installations, you should always update and test GeoCat Bridge locally first.

Because GeoCat Bridge cannot (over)write shared configuration files, you will have to make sure that the configuration file that has to be updated is the personal one in the administrative user's profile directory (e.g. %USERPROFILE%\Documents\ArcGIS\AddIns\ArcGISPro\{9d56cd06-73bd-4e0e-bca4-3c037e21aecb}).

After the personal configuration file has been updated successfully, you can copy it to the shared add-in directory.
Then, copy the new .esriAddinX file to the shared add-in directory, so that all users will have the updated software and configuration when they start ArcGIS Pro.

Activation¶

When you first install GeoCat Bridge, you will notice that it's running as the Community Edition.
With this version, you will not be able to publish maps or metadata to your own services.

If you wish to activate the full version of Bridge, you need to acquire a license from GeoCat bv.

Once you have obtained a license key or file, click the Activate Now... button in the About tab of the Bridge backstage settings:

License Key¶

This is the recommended method to activate Bridge and also the easiest. It also allows you to use a license on multiple machines, provided that you have purchased enough seats. However, your machine needs to be able to connect to the GeoCat license server in this case.

Choose the License Key (online) option and paste the GCBxxxx key that you obtained from the customer portal into the text box. Then hit the Activate button.

Migrating from Bridge for ArcMap

If you are migrating from Bridge for ArcMap, your license needs to be updated. The old license keys (starting with geocatbridge- instead of GCB) are technically still valid, but may not work after all. Please contact GeoCat support in that case, so we can migrate your license key on our end.

If the activation was successful, you will see your license details in the About tab, which may look like this for example:

License File¶

When you are working in an offline environment (i.e. with restricted Internet access or none at all), you can activate Bridge using a license file. Note that this licensing method is intended for single use licenses (node-locked).

To activate, choose the License File (offline) option and copy the activation code that is displayed:

Submit a ticket on the GeoCat customer portal (login required) and paste the activation code, so GeoCat can generate a license file (.lic) for you.
Then, go back to ArcGIS Pro and point the activation form to the location where you saved the license file. Then hit the Activate button.

If the license file is valid, should now see your license details in the About tab.

Info

If you are migrating from Bridge for ArcMap, your old license file will no longer work, even if your machine remains the same. Please request a new license file as described above.

Deactivation¶

To deactivate a license, simply click the Deactivate button under the License section of the About tab. You will be warned before the deactivation is performed.

This will release the license (i.e. clear all license data) from the machine, so that you may activate it on another machine, or re-activate it on the same machine using a different license key or file.

First Glance¶

Once the add-in has been properly installed (or copied to a well-known folder), you should be able to see a new GeoCat Bridge tab on the ribbon interface at the top of ArcGIS Pro:

The first thing do next, is to set up a data space! Hit the Settings button on the Bridge toolbar, which should get you straight to the Bridge configuration backstage.

In the next documentation section, we will show you how to configure a data space.