Synergize Integration API

Explorer has an integration scheme that works from either a Windows desktop or a web browser (or control).

It provides secure, reliable access to data in a Synergize repository.

This guide is intended to help developers of third-party systems (like transportation management systems) write the code that is needed, to ensure the security and reliability of the integration.

There are two types of integration: Desktop-based and Web-based.

 

Technical Background

First, read about how Synergize Integration Configurations are created: Configuring Synergize Explorer Integration.

The information in a Synergize repository is protected, so that only trusted agents can request data, and the actual signed-in users are identified, so that they see only documents that they are allowed to see.

 

To accomplish this, there are three configurable elements to integration:

  • Server identity (where the Explorer application is set up, identified with a base URL)

  • Customer ID (which company is making the request)

  • Encryption key (the private key that is paired with the customer ID to determine if the request is coming from a trusted source or not)

 

A URL for Synergize Explorer Integration is created using a single API call.

Behind the scenes, the following occurs:

  • Starting with the base URL

  • Encrypting and appending the query portion of the URL

  • Digitally signing the URL

  • Returning the fully-encrypted and signed URL

 

For security reasons, the URL can be used only once, to execute the initial search through the Synergize repository.

A second attempt to use the URL (for example, by a copied and pasted URL or refreshing the browser) will not be allowed.

However, you can refresh the data in an existing window, by coding a conditional check to see if the window still exists and sending it a command.

 

 

Prerequisites

You must use .NET Full, until we support .NET Core alone.

 

 

Integration Types

There are two integration types; one builds on the other.

Once you have configured the web-to-web configuration, you can build on that to accomplish the Windows desktop to web integration.

1. Basic integration (all implementations): Web to Web

2. Windows integration (extra steps): Windows Desktop to Web

 

 

Configuration

If you have created the following configuration (pictured), you would need to ensure that you used values in your call that matched:

  • The Base URL, Customer ID, and Encryption Key, as specified on the Connection Info page

    Graphical user interface, text, application

Description automatically generated

  • Configuration Name: ARDOCS_TMWSuite

  • Your Dictionary of key-value pairs with just one entry, the key called ord_number (the External name in the Field mapping table). (The value for ord_number would come from, for example, the currently selected record in the screen that is calling the integration code.)

    Graphical user interface, application, Teams

Description automatically generated

  • In a repository that has been enabled for views, you have an additional field to define the default view.

    Note that you can select available views in the repository, but a User's access to particular views is still honored by the system.

    In other words, the User may not have access to the default view but would still be able to select the repository views they did have access to.

    Graphical user interface, application

Description automatically generated

 

 

API for Testing

For your convenience, we provide the following call to confirm that the integration model is actually being derived properly.

Call the method to return an IntegrationModel and compare it to the one you instantiated before.

Given the same encrypted URL, customer ID, and encryption key, the models should be equal.

  • return a deserialized IntegrationModel class :

    • Build.IntegrationModel(string url, string customerId, string encryptionKey)