Forge resolver

The Forge resolver enables you to define backend functions, and handle asynchronous events for your UI Kit and custom UI apps. Your backend functions must be defined in the src directory of your Forge app. You must then refer to your resolver in the manifest.

Invoke your resolver functions in your frontend assets using the invoke Forge UI bridge method.

Usage - UI Kit

Consider the following example manifest.yml file:

1
2
modules:
  jira:issuePanel:
    - key: hello-world-panel
      resource: example-resource
      resolver:
        function: issue-panel-resolver
      render: native
      title: Hello world!
      icon: https://developer.atlassian.com/platform/forge/images/issue-panel-icon.svg
  function:
    - key: issue-panel-resolver
      handler: index.handler
resources:
  - key: example-resource
    path: src/frontend/index.jsx

This is the manifest declaration for a basic Jira issue panel using Forge resolver for UI Kit.

In this example:

• resource is a reference to a defined key in the resources object.
• resolver contains a function property, which references the function module that contains the handler for the resolver to use in your UI app.
• render: native to instruct the platform to render the app's UI from the components you've defined.
• path refers to the handler function specified in the manifest.yml file. This function serves as the entry point for the application, where the UI components are defined, and the app logic is executed.

Consider an example src/frontend/index.jsx file that contains the resolver function definitions:

1
2
import React, { useEffect, useState } from 'react';
import ForgeReconciler, { Text } from '@forge/react';
import { invoke } from '@forge/bridge';

const App = () => {
  const [data, setData] = useState(null);
  useEffect(() => {
    invoke('getText', { example: 'my-invoke-variable' }).then(setData);
  }, []);
  return (
    <>
      <Text>Hello world!</Text>
      <Text>{data ? data : 'Loading...'}</Text>
    </>
  );
};

ForgeReconciler.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

In this example:

• A single resolver function is defined, with the string identifier "getText".
  • This function can be invoked from the UI app's frontend assets contained in src/frontend/index.jsx, by using the invoke Forge bridge method.

Continuing this example, the following code invokes the "getText" function defined above:

1
2
import Resolver from '@forge/resolver';

const resolver = new Resolver();

resolver.define('getText', (req) => {
  console.log(req);
  return 'Hello, world!';
});

export const handler = resolver.getDefinitions();

Including this code in an appropriate location in your frontend assets would result in "Hello, World!" appearing in your browser console.

Usage - Custom UI

Consider the following example manifest.yml file:

1
2
modules:
  jira:issuePanel:
    - key: hello-world-panel
      resource: example-resource
      resolver:
        function: issue-panel-resolver
      title: Hello world!
      icon: https://developer.atlassian.com/platform/forge/images/issue-panel-icon.svg
  function:
    - key: issue-panel-resolver
      handler: index.handler
resources:
  - key: example-resource
    path: static/hello-world/build

This is the manifest declaration for a basic Jira issue panel using custom UI and the custom UI resolver. In this example:

• resource is a reference to a defined key in the resources object.
• resolver contains a function property, which references the function module that contains the handler for the resolver to use in your UI app.
• path relative path to the directory of static assets for the resource. It must contain the index.html entry point for the custom UI app; in this case, static/hello-world/build/index.html.

Consider an example src/index.js file that contains the resolver function definitions:

1
2
import Resolver from "@forge/resolver";

const resolver = new Resolver();

resolver.define("exampleFunctionKey", ({ payload, context }) => {
  return { example: `Hello, ${payload.name}!` };
});

export const handler = resolver.getDefinitions();

In this example:

• A single resolver function is defined, with the string identifier "exampleFunctionKey".
  • This function can be invoked from the custom UI app's frontend assets contained in static/hello-world, by using the invoke Forge bridge method.

Continuing this example, the following code invokes the "exampleFunctionKey" function defined above:

1
2
import { invoke } from "@forge/bridge";

invoke("exampleFunctionKey", { name: "World" }).then((returnedData) =>
  console.log(returnedData.example);
);

Including this code in an appropriate location in your frontend assets would result in "Hello, World!" appearing in your browser console.

Methods

The @forge/resolver package exports a class that contains two methods.

define

The define method is used to define individual resolver functions, identified by a functionKey.

Function signature

1
2
function define(
  functionKey: string,
  cb: (request: {
    payload: {
      [key in number | string]: any;
    },
    context: {
      accountId?: string;
      accountType?: 'licensed' | 'unlicensed' | 'customer' | 'anonymous';
      cloudId?: string;
      workspaceId?: string;
      localId: string;
      installContext: string;
      environmentId: string;
      environmentType: string;
      extension: {
        config?: { [key: string]: any } // defined for macro extensions
        [key: string]: any;
      }
    }
  }) => Promise<{ [key: string]: any } | string | void> | { [key: string]: any } | string | void,
): this

Arguments

• functionKey: A string identifier for the resolver function. This string must exactly match the functionKey used to invoke this function in your frontend assets.
• cb: The callback to be run when the invoke function is called with the matching functionKey. The return value of this callback will be returned from the invoke function in your frontend assets. This callback will have the following data passed into its first argument:
  • payload: Data passed in from the payload parameter of the invoke function.
  • context:
    • accountId: The Atlassian ID or JSM Customer ID of the user that interacted with the component.
    • accountType: The account type of the user that interacted with the component, one of: licensed, unlicensed, customer, or anonymous. Note, this field is mainly intended to be used in components that permit access by users without corresponding product license.
    • cloudId: The ID of the application on which the extension is working, for example the ID of a Jira or Confluence instance.
    • workspaceId: The ID of the workspace on which the extension is working.
    • localId: The unique ID for this instance of this component in the content.
    • environmentId: The unique ID of the environment where the component is deployed.
    • environmentType: The name of the environment where the component is deployed.
    • installContext: The ARI identifying the cloud or product context of this component installation.

Additional contextual information for your custom UI app. The data available in the extension property depends on the module in which your custom UI resolver is used. Note that context is similar to Platform Context, although it's not a 1-to-1 mapping.

getDefinitions

The getDefinitions method returns the invocation function handler that can be used as the handler for the function referenced by the resolver key in eligible modules.

Function signature

1
2
  function getDefinitions(): InvocationHandler