Custom UI resolver

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

Invoke your resolver functions in your frontend assets using the invoke custom UI bridge method. Install the custom UI resolver using the @forge/resolver npm package.

Usage

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 custom UI app.
• path is the 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 custom UI 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;
      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.
    • 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