Generic Connector

Out of the box, ScriptRunner Connect offers a bunch of Connectors that make it easy to call third-party APIs. However, sometimes you may need to connect to something that ScriptRunner Connect does not support. ScriptRunner Connect can connect to anything as long as the following pre-requisites are fulfilled:

  • Connection to the third-party service can be established. Behind the firewall services may need to be configured to let the connection from ScriptRunner Connect side go through by either allowlisting our static IP or by setting up a reverse proxy in a less restricted network.
  • Third-party service has HTTP-based API that can be called.

The most straightforward way to call a third-party API is to use Fetch API. However, most of the time you'll also need to authenticate the request, and hardcoding credentials directly into the 'fetch' call is a bad practice. To circumvent the need to hardcode any credentials in the code, ScriptRunner Connect offers a concept of Generic Connector. Generic Connector works by asking you a base URL for the service you want to work with, and one or more HTTP headers that need to be passed along with each API request. Usually, these headers are related to authentication, but technically can be anything that you don't want to repeat or expose in your code. To add headers you have 2 options, add them as Basic Auth, in which case we'll be encoding this header for you so you wouldn't have to, or add any other header without any post-processing in the custom headers section. Once the Generic Connector has been configured you can import it like any other API Connection and use it in the code.

Generic API Connections only expose a 'fetch' function, which you can use like any other Managed API Fetch call.


Even though ScriptRunner Connect comes with a bespoke Connector for Jira Cloud, we could also, for example, use the generic connector to connect to Jira Cloud. First, we need to grab the API Key from Atlassian, and then we can configure a generic connector:

Once the generic connector is configured, we can make an API call in the code.

For this example, let's fetch an issue from Jira Cloud:

import JiraCloud from './api/generic'; export default async function(event: any, context: Context): Promise<void> { const issueKey = 'ISSUE-1'; // Fetch the issue const response = await JiraCloud.fetch(`/rest/api/3/issue/${issueKey}`); // Check if the response is OK (within 200 range) if (!response.ok) { // If not then throw an error throw Error(`Unexpected response: ${response.status}`); } // If it is OK, then read the body as JSON const issue = await response.json(); // And then print out the reporter's display name console.log(issue.fields.reporter.displayName); }

Sometimes you may want to use alternative authentication schemes to what ScriptRunner Connect offers. For example, you may want to connect to Jira Cloud using API Key as shown above but would also like to use Managed API rather than low-level Fetch API. To achieve this, you can construct the Managed API manually and use it with the generic connector:

import { JiraCloudApi } from '@managed-api/jira-cloud-v3-sr-connect'; import JiraCloudGeneric from './api/generic'; export default async function(event: any, context: Context): Promise<void> { // Construct Managed API manually by pulling `connectionId` from the Generic API Connection and then pass it into Managed API constructor const JiraCloud = new JiraCloudApi(JiraCloudGeneric.connectionId); // Fetch the issue const issue = await JiraCloud.Issue.getIssue({ issueIdOrKey: 'EL-66' }); // And then print out the reporter's display name console.log(issue.fields.reporter.displayName); }

A temporary workaround

At this time, to use a manually constructed Managed API, you need to configure an API Connection that uses the Managed API you need to work with. API Connection does not have to be functional, it just needs to be configured in the UI, which causes the corresponding Managed API to be pulled into your workspace.

Once the Package Manager feature arrives, this workaround will no longer be necessary, since it will allow you to directly pull in any Managed API into your workspace.

Importing Managed API manually

When you use Managed APIs via API Connections, the construction of the Managed API is taken care of for you, which also means you won't have to import them manually. However, when you need to construct it manually, you also need to import them manually. You can find all the Managed APIs here, and the ones you need to use include the sr-connect  postfix. The convention for the Managed API class is `{ProductName}Api` (for example, `JiraCloudApi`).

You can use UNPKG to browse the content of Managed APIs if you need to find out the class name that you need to import. For example, browsing Jira Cloud's Managed API index.d.ts file reveals this information. We aim to make this information more transparent in the future.

You can also use the import-suggestions feature to pull in the Managed API manually if you know the import name:

On this page