Intents

Intents enable late-binding workflow orchestration using the "verb-noun" paradigm. An app raises an intent (e.g., "ViewChart") with context data, and the platform resolves which app should handle it.

How Intents Work

Intents decouple the caller from the responder. When App A raises an intent:

App A specifies the intent name (verb) and context data (noun)
The platform finds all apps registered to handle that intent
If multiple handlers exist, the Intent Resolver UI prompts the user to choose
The selected app receives the context and performs the action

FDC3 Compliantio.Connect intents follow FDC3 intent standards (e.g., ViewChart,ViewContact). Use FDC3 standard intent names for maximum interoperability.

Registering an Intent Handler

Intents are typically registered in the app's JSON definition file. They can also be registered dynamically in code:

Dynamic intent registration

io.intents.register("ViewChart", (context) => {
  if (context.type === "fdc3.instrument") {
    const { ticker } = context.id;
    renderChart(ticker);
  }
});

Static Registration (App Definition)

App definition with intents

{
  "name": "chart-app",
  "type": "window",
  "details": { "url": "http://localhost:3002" },
  "intents": [
    {
      "name": "ViewChart",
      "displayName": "View Chart",
      "contexts": ["fdc3.instrument"]
    }
  ]
}

Raising an Intent

Raise an intent

await io.intents.raise({
  intent: "ViewChart",
  context: {
    type: "fdc3.instrument",
    id: { ticker: "MSFT" },
    name: "Microsoft Corporation",
  },
  target: "startNew", // or "reuse" to use existing instance
});

Target Options

"startNew" — always launch a new instance of the handler app
"reuse" — route to an existing instance if available
(no target) — let the platform decide, showing the Intent Resolver if ambiguous

Intent Resolver

When multiple apps can handle the same intent, io.Connect displays the Intent Resolver UI. This modal lets the user choose which app should process the intent.

The Intent Resolver is a system app that can be customized or replaced with your own implementation to match your organization's design system.

React Pattern

Intents in React

import { useContext, useEffect } from "react";
import { IOConnectContext, useIOConnect } from "@interopio/react-hooks";

// Handler component
function ChartHandler() {
  const io = useContext(IOConnectContext);

  useEffect(() => {
    if (!io) return;

    io.intents.register("ViewChart", (context) => {
      console.log("Rendering chart for:", context);
    });
  }, [io]);

  return <div>Chart App</div>;
}

// Raiser component
function InstrumentList() {
  const viewChart = useIOConnect((io) => async (ticker: string) => {
    await io.intents.raise({
      intent: "ViewChart",
      context: {
        type: "fdc3.instrument",
        id: { ticker },
      },
    });
  });

  return (
    <ul>
      <li onClick={() => viewChart("AAPL")}>Apple</li>
      <li onClick={() => viewChart("MSFT")}>Microsoft</li>
    </ul>
  );
}

← PreviousInterop Methods Next →Workspaces