Skip to content

Connecting a System

This guide walks you through the process of connecting an external system to DIBOP, from selecting a connector to activating the connection.

Before You Begin

To connect a system, you will need:

  • Credentials for the external system (API key, OAuth2 client ID/secret, or username/password)
  • Enterprise Admin or higher role in DIBOP
  • The external system's API must be reachable from DIBOP's network

Credential Readiness

Have your credentials ready before starting. DIBOP encrypts credentials immediately upon entry -- you will not be able to view them again after saving.

Step 1: Find the Connector

  1. Navigate to CONNECT > Integrations in the sidebar
  2. Browse or search the connector catalogue for the system you want to connect
  3. Click on the connector card to open its detail drawer

If the connector you need is not in the catalogue, contact your platform administrator. They may be able to create a custom connector using the Connector SDK.

Step 2: Start the Connection

  1. In the connector detail drawer, click Connect
  2. The connection setup form opens, pre-populated with defaults from the connector template

Step 3: Configure Credentials

The credential form adapts based on the connector's authentication type:

API Key Authentication

Field Description
API Key Your API key for the external system
Header Name The HTTP header used to send the key (e.g., X-API-Key, Authorization)
Key Prefix Optional prefix before the key value (e.g., Bearer, Api-Key) 
Header: X-API-Key: abc123def456

OAuth2 Authentication

Field Description
Client ID Your OAuth2 application's client ID
Client Secret Your OAuth2 application's client secret
Token URL The endpoint where DIBOP requests access tokens
Scopes Space-separated list of OAuth2 scopes to request
Grant Type Typically client_credentials for server-to-server integrations

DIBOP handles the token lifecycle automatically -- requesting tokens, caching them, and refreshing them before they expire.

Basic Authentication

Field Description
Username Your account username
Password Your account password

DIBOP encodes these as a standard HTTP Basic Authentication header.

No Authentication

Some connectors (public APIs like REST Countries or Open-Meteo) do not require credentials. The connection setup form will indicate that no credentials are needed.

Step 4: Configure Connection Settings

Beyond credentials, you may have additional settings to configure:

Setting Description Default
Connection Name A friendly name for this connection instance Auto-generated from system name
Base URL Override Override the default base URL (e.g., for sandbox environments) Connector default
Timeout (seconds) How long to wait for API responses before timing out 30
Retry on Failure Whether to automatically retry failed requests Enabled
Max Retries Maximum number of retry attempts 3

Sandbox Environments

If the external system provides a sandbox or staging environment, use the Base URL Override to point your connection at the sandbox while you build and test orchestrations. Switch to production when you are ready.

Step 5: Test the Connection

Before activating, click Test Connection to verify that DIBOP can reach the external system with your credentials.

The test will:

  1. Attempt to authenticate using the credentials you provided
  2. Make a lightweight health-check call to the system's API
  3. Report the result:
    • Success -- the system responded with a valid response
    • Auth Failure -- the credentials were rejected
    • Timeout -- the system did not respond within the timeout window
    • Network Error -- the system is unreachable

If the test fails, review your credentials and network settings. See Testing Connections for detailed troubleshooting.

Step 6: Activate the Connection

Once the test passes:

  1. Click Save & Activate
  2. The connection is created and immediately available for use in orchestrations
  3. You are redirected to My Connections, where your new connection appears in the active list

What Happens Behind the Scenes

When you activate a connection, DIBOP:

  1. Encrypts your credentials using AES-256 encryption and stores them in Azure Key Vault
  2. Creates a connector instance linked to your enterprise, isolated from all other tenants
  3. Registers the connection so it appears in orchestration step selectors
  4. Initialises health monitoring -- DIBOP will periodically check the connection's health and update its status

Managing Multiple Connections

You can create multiple connections to the same system. This is useful for:

  • Sandbox vs Production -- maintain separate connections for testing and live data
  • Multiple Accounts -- if you have different credentials for different purposes
  • Regional Endpoints -- connect to different regional instances of the same system

Each connection instance operates independently with its own credentials and configuration.

Deactivating a Connection

To deactivate a connection without deleting it:

  1. Navigate to CONNECT > My Connections
  2. Find the connection and click the three-dot menu
  3. Select Deactivate

A deactivated connection:

  • Stops health monitoring
  • Cannot be used in new orchestration executions
  • Retains its credentials (they are not deleted)
  • Can be reactivated at any time

Active Orchestrations

If any active orchestrations use this connection, they will fail on steps that reference it. Deactivate or update the orchestrations first.

Deleting a Connection

To permanently delete a connection:

  1. Navigate to CONNECT > My Connections
  2. Find the connection and click the three-dot menu
  3. Select Delete
  4. Confirm the deletion

Deleting a connection permanently removes:

  • The connection instance
  • All stored credentials
  • Health check history

Irreversible

Deleting a connection cannot be undone. Historical execution logs that reference this connection will retain the system name but will no longer be able to re-execute.

Next Steps