CardExchange Bridge Software Setup

Contents

Overview

This document will walk through the steps for a basic setup of the CardExchange Bridge data import software for CardExchange Cloud Controller. CardExchange Bridge Desktop is a C++ based application that installs the CardExchange Bridge service on a Windows PC. The service when setup will run on a schedule configured by the client or can be run as a onetime sync option to communicate and send data to a CardExchange Cloud Controller system.

Requirements

CardExchange Bridge requires a CardExchange Controller account with Bridge API access. CardExchange Cloud requires Bridge desktop application to be on v1.1 minimum. The latest version of CardExchange Bridge Desktop is available in the following link:

https://dl.cardexchangesolutions.com/bridge

A Cloud account’s client ID and secret key are also required for authentication. Instructions for obtaining the Client ID and secret are detailed in Section Login Authentication

To sync data from the client to CardExchange Controller, the client machine will need full access to the dataset’s location.

Application Installation

Installer Navigation

Note: You will have to uninstall previous versions before running the installer

The installer is simple with very little configuration. To continue to the next step, select Next. There is a back button in the top left corner to return to previous steps.

Open

Continue through the steps until you reach the last page stating the installation has been complete.

Application Logging

CardExchange Bridge installs a service folder in the Public Documents of the machine in this location: ‘C:\Users\Public\Documents\CardExchange Bridge\’

Two files are installed: ‘cardExchangeBridge.json’ and ‘service.log’

The JSON file is the application configuration file it uses to write and store the settings for the Bridge connection you will make. The service.log file log every action and network call made by the application. This log file is handy for checking errors around why record import may not have happened. Do not remove any files from this location.

Setup

Login Authentication

Server Options

When launching the application, the first configurable step is the Server login options. There are two options: Default, and Custom. Be aware the Custom option may be selected at first. Please select and use the Default option if it is already not selected unless directed and given a custom authentication and API URL.

Obtaining the Client ID and Client Secret Key

1. Go to the CardExchange Cloud Admin Center and log in. Https://admin.cardexchangecloud.com

2. In the left navigation bar, select the Settings - General menu option.

3. In the general settings menu page are the two items on the right.

Open

1. Copy and paste the Client ID and Client Secret in the respective fields in the software. Click the Login button to proceed.

2. When successful, a “User Authorized” message appears in the bottom left corner and the Next > button option will become available.

Database Setup

CardExchange Bridge offers connections of the following database options: Excel, Access, MySQL, SQLite, and ODBC.

To begin setting up the connection, select the Add button. Choose the database connection type, then type in a Connection Name at the bottom. The name should adequately describe the database or table purpose, for example, “Persons List SQL”.

After providing a Connection Name, select Next.

The next step includes locating your database and providing the service any additional options necessary to access or read from the database table.

After setting your database preferences, the main database section will reappear to begin the mappings process.

Database Mappings

In Mappings, each database column provided by the database can be mapped to a Controller property.

In the Person Tab, the database columns are the main items on the left, and the Controller property it maps to is in the drop-down menu.

However, in the Address and Profile tab options, the main items on the left are Controller property fields, with the database column available in the drop-down menu.

When all requirements have been met, select the Next button to continue.

Requirements

There are two mapping Controller properties that are required, the “First Name” and “Last Name” Controller properties must be set to two database field provided.

Next, the “Use this database” option must be selected if it is not already. If multiple tables are connected, one must be selected.

Lastly, one of the database column fields must be “Set as Key” meaning a key reference for importing and syncing records to Controller and back to the database if needed.

The Key is a unique identifier across every record. Typically, a Person or Employee number type is used for this as it is used as reference for identifying individuals in other systems as well.

Only one field is required to be used as key, however multiple can be set for very specific update functions.

Conditionals

The Address Type, and Profile tabs offers an option to create conditions for what Controller property to use for the respective settings.

All conditional options use a basic logic to determine what value to use depending on the data available in the database. All Address and Profile options are created in the Controller system and the Cloud Admin Center.

When [Database Column] [Operator] [Value] Use [Department from Controller]

Settings

The settings change the behavior of Bridge, particularly when it comes to Archival and Scheduling when Bridge syncs with Controller.

1. Update Existing Records: When the service runs, Bridge will match any existing records in Controller with the records provided in the database based on the Key used in mappings. Turn this option off to always import a new record if a change occurs.

2. Origin Value (REQUIRED): The Origin Value is a descriptive property that is applied to every record imported by Bridge using this connection. The description should tell an operator where that data originated from.

3. Archive Existing Records: If a duplicate record exists in Controller is imported by Bridge, the existing record will be Archived and the Bridge will create a new record instead of updating.

4. Block Active Cards: If a Person record holding an active card is to be archived, Bridge will ask Controller to block the card then archive it, instead of stating the record cannot be archived.

5. Restore Archive Records: If a record imported already exists as an Archived record, the Person will be Restored to the system.

Because CardExchange Bridge runs as a Windows Service in your machines background, a schedule will be needed to routinely check for changes and upload new person record details. A time of day can be set, or an interval can be chosen.

The schedule will not start until after the Bridge application has closed. An option to manually sync is provided in the Local Update step.

Profile

The Profile section is where the cardholder’s profile is determined either by using the same profile option for all records imported, or created conditional statements to determine what to use.

To create a conditional, select the Add Condition button in the bottom right. This will create a condition item in the menu above. Select the Profile database column next to When, pick the operator (typically “is” is the best option), type in the Value, then next to Use, select the Profile from Controller.

There are three operators to choose from: is, is not, or contains.

Select a default profile to use when none of the created conditions are met by a person record.

Filters

Filters are used for filtering out data that do not meat certain conditions. Much like the Conditionals created for Profiles and Address types, Filters offer additional conditional options.

There are additional operators that come with filters: is empty, is not empty.

Filters are not required for continuing.

Local Update

Local Updates offers three options to allow Controller to update the connected database downstream. The cardholder’s Chip Serial number and Card Status from Controller can be updated in the source file, as well as the Photo.

If you’ve mapped a local file system as the Photo storage, Bridge will need administrative privileges to right back.

To start an import, the Run Now button option can be selected. As mentioned in Settings, the schedule will not start until after Bridge has closed. It is recommended that for first time import, the Run now button option is used. Afterwards, the schedule will stay on time and keep track of changes.

When the setup is complete, select the Finish option.