Extension API reference

The aha extension API is the primary entrypoint for extensions to integrate with Aha! Develop. There are several helpful methods for making requests to the Aha! Develop GraphQL API, working with Aha! Develop records, authenticating with services, and communicating between extensions.

Click any of the following links to skip ahead:

• Access

• Browser API

  • auth

  • command

  • commandPrompt

  • commandOutput

  • project

  • user

• Browser / Server API

  • account

  • triggerBrowser

  • triggerServer

  • on

  • getImporter

  • models

  • graphQuery

  • graphMutate

Access

Inside an extension, aha is accessible directly as a global variable:

aha.on("endpointName", ({ headers, payload }, {identifier, settings}) => {
  // code goes here.
})

In the browser console, aha is also accessible globally, through window:

feature = new aha.models.Feature({ referenceNum: "PLAT-123" })
await feature.getExtensionFields("aha-develop.github")

Top

Browser API

These methods are only accessible from extensions running in the browser.

auth

auth is used to fetch authentication information for a third-party service, optionally going through a login flow if necessary. This returns authData that can be passed into future requests to that service.

const authData = await aha.auth("github", {
  useCachedRetry: true,
  parameters: { scope: "repo, read:org" },
});

const graphqlWithAuth = graphql.defaults({
  headers: {
    authorization: `token ${authData.token}`,
  },
});

auth(service, options, callback)

• service: The service to authenticate to. Currently, supported services are asana, atlassian, ado, figma, github, gitlab, google, rally, sentry, trello, and zendesk.

• options:

  • parameters: service-specific parameters to pass through the authentication process.

  • useCachedRetry: use stored authentication information if it exists. Automatically reauthorize if necessary.

  • reAuth: authenticate if the user is not already logged in. True by default.

• callback: an optional callback called after a successful authentication. Only called when the user is logged in.

• returns authData: service-specific authentication information. All existing services have the following shape:

  {
    error: string,
    result: {
      token: string
    }
  }

command

command executes a command from a command extension contribution, passing args into it.

aha.command('aha-develop.github.addLink', { record: feature });

command(fullyQualifiedCommandName, args)

• fullyQualifiedCommandName: the fully qualified name of the command to execute. If you are executing a command from your own extension, you can use the short name instead.

• args: an object that will be sent to the command

commandPrompt

From a command extension contribution, commandPrompt will open a prompt for user input.

const prUrl = await aha.commandPrompt("Link URL", {
  placeholder: "Enter the URL to a pull request",
});

commandPrompt(prompt, { placeholder, default })

• prompt: a short bit of text to describe what the prompt is for

• placeholder: placeholder text to show on the empty field

• default: default data to fill the field with

Returns a promise that will resolve with the input value.

commandOutput

commandOutput prints a message to the command window while a command is running.

if (!record) {
  aha.commandOutput("Open a record first to sync PRs for that record");
  return;
}

commandOutput(message)

• message: a string to print to the command window

project

Returns a Project instance representing the current team/project for the user/page. This will be the team/project currently selected in the switcher in the top-left corner of the browser.

This can potentially return null in cases where there is no current team/project for the current page.

console.log(aha.project.name); // logs the current team/project's name

user

This returns a User instance representing the current user.

console.log(aha.user.name); // logs the current user's name

Top

Browser / Server API

These are available anywhere aha is accessible.

account

This returns an Account instance representing the current account.

console.log(aha.account.name); // logs the current account's name

triggerBrowser

triggerBrowser will trigger an event handler contribution in the current browser tab.

aha.triggerBrowser('aha.workflow-board.shipped', args);

triggerBrowser(fullyQualifiedEventName, args)

• fullyQualifiedEventName: the fully qualified name of the event to trigger. If you are triggering an event from your own extension, you can use the short name instead.

• args: event-specific args that will be passed to the event handler.

triggerServer

triggerServer will trigger an event handler contribution running on the Aha! Develop servers, running with the permissions of the user who installed the extension.

aha.triggerServer('aha.workflow-board.shipped', args);

triggerServer(fullyQualifiedEventName, args)

• fullyQualifiedEventName: the fully qualified name of the event to trigger. If you are triggering an event from your own extension, you can use the short name instead.

• args: event-specific args that will be passed to the event handler.

on

aha.on("addLink", async ({ record, { identifier, settings } }) => {
  ...

on is a generic method for registering contributions and event handlers.

getImporter

getImporter returns an object that can be used to register callbacks when importing records from other systems.

const importer = aha.getImporter("aha-develop.github-import.issues");
importer.on({ action: "listCandidates" }, ...

getImporter(importerName)

• importerName: the fully qualified name of the importer extension to use for registering callbacks.

models

models exposes a number of JavaScript wrappers to Aha! Develop models. These are JavaScript objects that can be used in an object-oriented way to fetch and save Aha! Develop record data.

graphQuery

graphQuery runs a GraphQL query against the Aha! Develop GraphQL API.

const query = `
  query features($releaseId: ID)  {
  features(filters: {releaseId: $releaseId}, order: [{name: createdAt, direction: DESC}]) {
    nodes {
      id
      name
      referenceNum
      assignedToUser {
        name
      }
      requirements {
        name
        referenceNum
      }
    }
  }
}`;
const resultData = aha.graphQuery(query, { variables: { releaseId: "DEMO-R-1" } });

graphQuery(queryString, { variables })

• queryString: a string that can be used as a GraphQL query

• variables: optional variables to be used with the GraphQL query

graphQuery returns the GraphQL object result as a plain JavaScript object.

graphMutate

graphMutate runs a GraphQL mutation against the Aha! Develop GraphQL API.

const mutation = `
  mutation CreateFeature($name: String, $releaseId: ID) {
    createFeature(attributes: {name: $name, release: {id: $releaseId}}) {
      ...
`;
const resultData = aha.graphMutate(mutation, { variables: { name: "A new feature", releaseId: "DEMO-R-1" } });

graphMutate(mutationString, { variables })

• queryString: a string that can be used as a GraphQL mutation

• variables: optional variables to be used with the GraphQL mutation

graphMutate — Returns the GraphQL object result as a plain JavaScript object

Top