AboutSupportDeveloper GuideVersion 41.129.83.2

A Desktop Agent is a desktop component (or aggregate of components) that serves as a launcher and message router (broker) for applications in its domain.

A Desktop Agent can be connected to one or more App Directories and will use directories for application identity and discovery. Typically, a Desktop Agent will contain the proprietary logic of a given platform, handling functionality like explicit application interop workflows where security, consistency, and implementation requirements are proprietary.

interface DesktopAgent {
    addContextListener(handler: OpenFin.FDC3.v1_2.ContextHandler): OpenFin.FDC3.v1_2.Listener;
    addContextListener(contextType: null | string, handler: OpenFin.FDC3.v1_2.ContextHandler): OpenFin.FDC3.v1_2.Listener;
    addIntentListener(intent: string, handler: OpenFin.FDC3.v1_2.ContextHandler): OpenFin.FDC3.v1_2.Listener;
    broadcast(context: OpenFin.FDC3.v1_2.Context): void;
    findIntent(intent: string, context?: OpenFin.FDC3.v1_2.Context): Promise<OpenFin.FDC3.v1_2.AppIntent>;
    findIntentsByContext(context: OpenFin.FDC3.v1_2.Context): Promise<OpenFin.FDC3.v1_2.AppIntent[]>;
    getCurrentChannel(): Promise<null | OpenFin.FDC3.v1_2.Channel>;
    getInfo(): OpenFin.FDC3.v1_2.ImplementationMetadata;
    getOrCreateChannel(channelId: string): Promise<OpenFin.FDC3.v1_2.Channel>;
    getSystemChannels(): Promise<OpenFin.FDC3.v1_2.Channel[]>;
    joinChannel(channelId: string): Promise<void>;
    leaveCurrentChannel(): Promise<void>;
    open(app: TargetApp, context?: OpenFin.FDC3.v1_2.Context): Promise<void>;
    raiseIntent(intent: string, context: OpenFin.FDC3.v1_2.Context, app?: TargetApp): Promise<OpenFin.FDC3.v1_2.IntentResolution>;
    raiseIntentForContext(context: OpenFin.FDC3.v1_2.Context, app?: TargetApp): Promise<OpenFin.FDC3.v1_2.IntentResolution>;
}

Methods

  • Publishes context to other apps on the desktop.

    DesktopAgent implementations should ensure that context messages broadcast to a channel by an application joined to it should not be delivered back to that same application.

     agent.broadcast(context);
    

    Parameters

    Returns void

  • Find out more information about a particular intent by passing its name, and optionally its context.

    findIntent is effectively granting programmatic access to the Desktop Agent's resolver. A promise resolving to the intent, its metadata and metadata about the apps that registered it is returned. This can be used to raise the intent against a specific app.

    If the resolution fails, the promise will return an Error with a string from the ResolveError enumeration.

    // I know 'StartChat' exists as a concept, and want to know more about it ...
    const appIntent = await agent.findIntent("StartChat");

    // returns a single AppIntent:
    // {
    // intent: { name: "StartChat", displayName: "Chat" },
    // apps: [{ name: "Skype" }, { name: "Symphony" }, { name: "Slack" }]
    // }

    // raise the intent against a particular app
    await agent.raiseIntent(appIntent.intent.name, context, appIntent.apps[0].name);

    Parameters

    Returns Promise<OpenFin.FDC3.v1_2.AppIntent>

  • Find all the avalable intents for a particular context.

    findIntents is effectively granting programmatic access to the Desktop Agent's resolver. A promise resolving to all the intents, their metadata and metadata about the apps that registered it is returned, based on the context types the intents have registered.

    If the resolution fails, the promise will return an Error with a string from the ResolveError enumeration.

    // I have a context object, and I want to know what I can do with it, hence, I look for for intents...
    const appIntents = await agent.findIntentsByContext(context);

    // returns for example:
    // [{
    // intent: { name: "StartCall", displayName: "Call" },
    // apps: [{ name: "Skype" }]
    // },
    // {
    // intent: { name: "StartChat", displayName: "Chat" },
    // apps: [{ name: "Skype" }, { name: "Symphony" }, { name: "Slack" }]
    // }];

    // select a particular intent to raise
    const startChat = appIntents[1];

    // target a particular app
    const selectedApp = startChat.apps[0];

    // raise the intent, passing the given context, targeting the app
    await agent.raiseIntent(startChat.intent.name, context, selectedApp.name);

    Parameters

    Returns Promise<OpenFin.FDC3.v1_2.AppIntent[]>

  • Returns the Channel object for the current channel membership.

    Returns null if the app is not joined to a channel.

    Returns Promise<null | OpenFin.FDC3.v1_2.Channel>

  • Returns a channel with the given identity. Either stands up a new channel or returns an existing channel.

    It is up to applications to manage how to share knowledge of these custom channels across windows and to manage channel ownership and lifecycle.

    Error with a string from the ChannelError enumeration.

    Parameters

    • channelId: string

    Returns Promise<OpenFin.FDC3.v1_2.Channel>

  • Joins the app to the specified channel. An app can only be joined to one channel at a time. Rejects with error if the channel is unavailable or the join request is denied. Error with a string from the ChannelError enumeration.

    Parameters

    • channelId: string

    Returns Promise<void>

  • Removes the app from any channel membership.

    Context broadcast and listening through the top-level fdc3.broadcast and fdc3.addContextListener will be in a no-op when the app is not on a channel.

    Returns Promise<void>

  • Launches an app by target, which can be optionally a string like a name, or an AppMetadata object.

    If a Context object is passed in, this object will be provided to the opened application via a contextListener. The Context argument is functionally equivalent to opening the target app with no context and broadcasting the context directly to it.

    If opening errors, it returns an Error with a string from the OpenError enumeration.

       //no context and string as target
    agent.open('myApp');
    //no context and AppMetadata object as target
    agent.open({name: 'myApp', title: 'The title for the application myApp.', description: '...'});
    //with context
    agent.open('myApp', context);

    Parameters

    Returns Promise<void>

  • Raises an intent to the desktop agent to resolve.

    //Find apps to resolve an intent to start a chat with a given contact
    const appIntent = await fdc3.findIntent("StartChat", context);
    //use the returned AppIntent object to target one of the returned chat apps with the context
    await fdc3.raiseIntent("StartChat", context, appIntent.apps[0].name);
    //or use one of the AppMetadata objects returned in the AppIntent object's 'apps' array
    await fdc3.raiseIntent("StartChat", context, appMetadata);

    Parameters

    Returns Promise<OpenFin.FDC3.v1_2.IntentResolution>