Configuration

io.Connect Desktop

To configure io.Connect Desktop to connect to io.Manager, use the "server" top-level key of the system.json system configuration file of io.Connect Desktop located in the %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config folder. Add the following basic configuration to enable connection to io.Manager:

{
    "server": {
        "enabled": true,
        "url": "http://localhost:4356/api"
    }
}

This will add io.Manager as an additional app store and instruct it to store Layouts and app preferences. If you want io.Manager to be the only app store, set the "appStores" top-level key in the system.json file to an empty array.

The "server" top-level key has the following properties:

Property	Type	Description
`"cache"`	`object`	Settings for persisting data received from io.Manager. Defaults to `{}`. Available since io.Connect Desktop 9.4.
`"clientAuth"`	`"no-auth" \| "negotiate" \| "kerberos"`	The client authentication mechanism for the REST service. Defaults to `"no-auth"`.
`"enabled"`	`boolean`	If `true`, will enable connecting to io.Manager.
`"features"`	`object`	Features to be injected automatically in io.Connect Desktop.
`"fetchInterval"`	`number`	Interval in seconds at which the server will be polled for new data (apps, Layouts, commands). Defaults to `30`.
`"requests"`	`object`	Settings for the requests sent to io.Manager. Defaults to `{}`. Available since io.Connect Desktop 9.4.
`"startRetries"`	`number`	Number of times io.Connect Desktop will try to reconnect to io.Manager. Defaults to `10`.
`"startRetryInterval"`	`number`	Interval in seconds at which io.Connect Desktop will try to connect to io.Manager. Defaults to `10`.
`"tokenRefreshInterval"`	`number`	Interval in seconds at which io.Connect Desktop will try to refresh the io.Manager token. Defaults to `3600`.
`"url"`	`string`	Required. URL pointing to io.Manager.

The "features" object has the following properties:

Property	Type	Description
`"applicationsStore"`	`boolean`	If `true` (default), the io.Manager app store will be automatically injected.
`"layoutsStore"`	`boolean`	If `true` (default), the io.Manager Layout store will be automatically injected.
`"commands"`	`boolean`	If `true` (default), the io.Manager commands will be automatically injected.
`"preferencesStore"`	`boolean`	If `true` (default), the io.Manager app preferences store will be automatically injected.

To send client crashes to the io.Manager Server, edit the "output" property of the "crashReporter" top-level key in the system.json file:

{
    "crashReporter": {
        "output": {
            "type": "server",
            "serverUrl": "http://localhost:4356/api/crashes"
        }
    }
}

If you want to support different environments and regions that connect to different io.Manager instances, see the Getting Started > How to > Rebrand io.Connect Desktop > Functionality > Environments & Regions section of the io.Connect Desktop documentation.

Available since io.Connect Desktop 9.4

The "cache" object has the following properties:

Property	Type	Description
`"clearOld"`	`boolean`	If `true`, on opening a new session to io.Manager, all cache files from previous sessions will be deleted. Defaults to `false`.
`"enabled"`	`boolean`	If `true`, will enable caching and persisting data from io.Manager locally (e.g., in case of connection interruptions). Defaults to `false`.
`"location"`	`string`	Location for the persisted cache files. Defaults to `"%LocalAppData%/interop.io/io.Connect Desktop/UserData/%GLUE-ENV%-%GLUE-REGION%/ioManagerCache"`.

The "requests" object has the following properties:

Property	Type	Description
`"closeSessionTimeout"`	`number`	Interval in milliseconds to wait for a response to the `closeSession` request to io.Manager. Defaults to `10000`.
`"openSessionTimeout"`	`number`	Interval in milliseconds to wait for a response to the `openSession` request to io.Manager before proceeding from cache. Defaults to `60000`.
`"timeout"`	`number`	Interval in milliseconds to wait for a response from io.Manager. Defaults to `60000`.

io.Connect Browser

Connecting to io.Manager from an io.Connect Browser project requires modifying the configuration for initializing the @interopio/browser-platform library in the Main app.

To specify settings for the connection to the io.Manager, use the manager property of the optional configuration object when initializing the @interopio/browser-platform library. The following example demonstrates configuring the connection to io.Manager with Basic authentication:

import IOBrowserPlatform from "@interopio/browser-platform";

const config = {
    licenseKey: "my-license-key",
    manager: {
        // URL pointing to io.Manager.
        url: "https://my-io-manager.com:4242/api",
        // Basic authentication.
        auth: {
            basic: {
                username: "username",
                password: "password"
            }
        },
        fetchIntervalMS: 10000,
        tokenRefreshIntervalMS: 15000
    }
};

const { io } = await IOBrowserPlatform(config);

The manager object has the following properties:

Property	Type	Description
`auth`	`object`	Required. User authentication configuration.
`cache`	`object`	Settings for persisting data received from io.Manager. Available since io.Connect Browser 9.4.
`fetchIntervalMS`	`number`	Interval in milliseconds at which a new snapshot of app definitions and Layouts will be fetched from io.Manager. Defaults to `60000`.
`getHeaders`	`function`	Callback that will be invoked on every request. Returns extra headers that will be merged with the existing ones. This callback can be used as a convenient way to refresh your access tokens. For more details, see the Request Headers section. Available since io.Connect Browser 9.4.
`headers`	`object`	Object containing key/value pairs of headers to be sent with every request.
`requests`	`object`	Settings for the requests sent to io.Manager. Available since io.Connect Browser 9.4.
`tokenRefreshIntervalMS`	`number`	Interval in milliseconds at which the session token will be refreshed. Defaults to `3600000`.
`url`	`string`	Required. URL pointing to io.Manager.

The auth object has the following properties:

Property	Type	Description
`basic`	`object`	Object with required `username` and `password` properties for Basic authentication.
`username`	`string`	Username for authentication.
`token`	`object`	Object with an optional `bearer` property holding an access token for token-based authentication. Keep in mind that the token provided here can't be refreshed after it expires. To be able to refresh your access token, use the `getHeaders` property of the `manager` object. For more details, see the Request Headers section.

Available since io.Connect Browser 9.4

The cache object has the following properties:

Property	Type	Description
`clearOld`	`boolean`	If `true`, on opening a new session to io.Manager, all cache databases from previous sessions will be deleted. Defaults to `false`.
`enabled`	`boolean`	If `true` (default), will enable caching and persisting data from io.Manager locally (e.g., in case of connection interruptions).

The requests object has the following properties:

Property	Type	Description
`closeSessionTimeout`	`number`	Interval in milliseconds to wait for a response to the `closeSession` request to io.Manager. Defaults to `10000`.
`openSessionTimeout`	`number`	Interval in milliseconds to wait for a response to the `openSession` request to io.Manager before proceeding from cache. Defaults to `10000`.
`timeout`	`number`	Interval in milliseconds to wait for a response from io.Manager. Defaults to `10000`.

Request Headers

The headers object allows you to provide additional headers that will be sent with every request to io.Manager.

// Defining additional headers that will be applied to every request sent to io.Manager.
const headers = {
    HeaderName: "HeaderValue",
    AnotherHeaderName: "AnotherHeaderValue"
};

const config = {
    licenseKey: "my-license-key",
    manager: {
        url: "https://my-io-manager.com:4242/api",
        // Providing additional headers.
        headers
    }
};

const { io } = await IOBrowserPlatform(config);

Available since io.Connect Browser 9.4

The getHeaders property can be used to provide a callback that will be invoked on every request sent to io.Manager. This offers a convenient way to refresh your access tokens. The callback will receive as an argument an object containing all current request headers. The information about the current headers can help you determine what additional headers to apply to the request in case you need to send different headers with the different requests. The callback must return an object with key/value pairs representing the additional request headers that will be merged with the existing ones.

The following example demonstrates how to provide a callback that will obtain and add to the headers a valid access token on each request sent to io.Manager:

import IOBrowserPlatform from "@interopio/browser-platform";

// Callback for handling the request headers.
const getHeaders = async () => {
    // Your custom internal logic for refreshing and retrieving the access token.
    const token = await getAccessToken();

    const extraHeaders = {
        Authorization: `Bearer ${token}`
    };

    // The returned headers will be merged with the existing ones.
    return extraHeaders;
};

const config = {
    licenseKey: "my-license-key",
    manager: {
        url: "https://my-io-manager.com:4242/api",
        // Providing a callback that will be invoked on every request sent to io.Manager.
        getHeaders
    }
};

const { io } = await IOBrowserPlatform(config);

io.Manager Documentation

Configuration

io.Connect Desktop

io.Connect Browser

Request Headers