Forge Developer

Beta

Forge Developer

Beta

Rate this page:

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
3
4
5
6
7
8
9
10
11
12
13
14
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
resources:
  - key: example-resource
    path: static/hello-world/build
function:
  - key: issue-panel-resolver
    handler: index.handler

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
3
4
5
6
7
8
9
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".

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

1
2
3
4
5
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
3
4
5
6
7
8
9
10
11
12
13
14
15
function define(
  functionKey: string,
  cb: (request: {
    payload: {
      [key in number | string]: any;
    },
    context: {
      cloudId: string;
      localId: string;
      extensionContext: {
        [key: string]: any;
      }
    }
  }) => Promise<{ [key: string]: any } | void> | { [key: string]: any } | 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: Additional contextual information for your custom UI app. The data available in extensionContext depends on the module in which your custom UI resolver is used.

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
  function getDefinitions(): InvocationHandler

Rate this page: