open

Desktop Agent bridging message exchange for a open API call on the DesktopAgent. Generated by API calls:

• open(app: AppIdentifier, context?: Context): Promise<AppIdentifier>

Message Exchange Type: Request Response (single)

E.g.

// Open an app without context, using an AppIdentifier object to specify the target and Desktop Agent
let AppIdentifier = {appId: 'myApp-v1.0.1', desktopAgent:"DesktopAgentB"};
let instanceMetadata = await fdc3.open(AppIdentifier);

// Open an app with context, using an AppIdentifier object to specify the target and Desktop Agent
let AppIdentifier = {appId: 'myApp-v1.0.1', desktopAgent:"DesktopAgentB"};
let instanceMetadata = await fdc3.open(AppIdentifier, contextObj);

Note that it is not currently possible to identify resolve all available applications within a Desktop Agent via the FDC3 API. Hence, fdc3.open calls without a specified desktopAgent field in their AppIdentifier, e.g.:

// Open a target app via AppIdentifier, without a specified Desktop Agent 
let AppIdentifier = {appId: 'myApp-v1.0.1'};
let instanceMetadata = await fdc3.open(AppIdentifier);

should always be processed locally without be passed to the bridge.

The fdc3.open command should result in a single copy of the specified app being opened and its instance data returned, or an error if it could not be opened. If no context is included, the responding Desktop Agent MAY return the new app's AppIdentifier as soon as it launches, without waiting for the app to initialize FDC3. If context is included, the responding Desktop Agent MUST wait for the app to initialize FDC3 and add a matching context listener. If the app does not initialize FDC3 within the timeout, the response MUST contain the OpenError.ApiTimeout error; if it initializes but does not add the required listener, the response MUST contain OpenError.AppTimeout.

If the remote Desktop Agent is not currently connected from the bridge, the OpenError.DesktopAgentNotFound error should be returned in the response from the bridge and the promise returned from the call to fdc3.open rejected with it.

Message exchange

Request format

Request message schemas

• https://fdc3.finos.org/schemas/next/bridging/openAgentRequest.schema.json
• https://fdc3.finos.org/schemas/next/bridging/openBridgeRequest.schema.json

Example

Outward message to the bridge:

// agent-A -> DAB
{
    "type": "openRequest",
    "payload": {
        "app": {
            "appId": "myApp",
            "desktopAgent":"agent-B"
        },
        "context": {/*contextObj*/}
    },
    "meta": {
        "requestUuid": "<requestUuid>",
        "timestamp": "2020-03-...",
        "source": {
            "appId": "AChatApp",
            "instanceId": "02e575aa-4c3a-4b66-acad-155073be21f6"
        }
    }
}

which is repeated on to the target agent as:

// DAB -> agent-B
{
    "type": "openRequest",
    "payload": {
        "app": {
            "appId": "myApp",
            "desktopAgent":"DesktopAgentB"
        },
        "context": {/*contextObj*/}
    },
    "meta": {
        "requestUuid": "<requestUuid>",
        "timestamp": 2020-03-...,
        "source": {
            "appId": "AChatApp",
            "instanceId": "02e575aa-4c3a-4b66-acad-155073be21f6",
            "desktopAgent": "agent-A" //added by DAB
        }
    }
}

Response format

Response message schemas

• https://fdc3.finos.org/schemas/next/bridging/openAgentResponse.schema.json
• https://fdc3.finos.org/schemas/next/bridging/openAgentErrorResponse.schema.json
• https://fdc3.finos.org/schemas/next/bridging/openBridgeResponse.schema.json
• https://fdc3.finos.org/schemas/next/bridging/openBridgeErrorResponse.schema.json

Example

Response message from target Desktop Agent:

// agent-B -> DAB
{
    "type": "openResponse",
    "payload": {
        "appIdentifier": {
            "appId": "myApp",
            "instanceId": "e36d43e1-4fd3-447a-a227-38ec48a92706"
        }
    },
    "meta": {
        "requestUuid": "<requestUuid>",
        "responseUuid": "<responseUuid>",
        "timestamp": "2020-03-..."
    }
}

which is augmented and repeated on by the bridge as:

// agent-B -> DAB
{
    "type": "openResponse",
    "payload": {
        "appIdentifier": {
            "appId": "myApp",
            "instanceId": "e36d43e1-4fd3-447a-a227-38ec48a92706"
        }
    },
    "meta": {
        "requestUuid": "<requestUuid>",
        "responseUuid": "<responseUuid>",
        "timestamp": "2020-03-...",
        "sources": [{ "desktopAgent": "agent-B" }] // added by DAB
    }
}