a9script

Docs / Connections & functions

Designing a function set

You have an API’s documentation and a business need. You do not configure the API. You configure the few operations the need uses, each as a function named in the business’s words. This page walks through that for one integration: a new Jira issue becomes a Linear issue, linked back.

From two APIs to the functions an integration calls
  1. Jira APILinear APIGET /issue/{key}GET /searchPOST /issuePUT /issue/{key}POST /commentGET /projectissueCreateissueUpdatecommentCreateteams

    1Each API offers far more operations than one integration needs. Configuring all of them gives a script nothing to go on.

  2. Jira APILinear APIGET /issue/{key}GET /searchPOST /issuePUT /issue/{key}POST /commentGET /projectissueCreateissueUpdatecommentCreateteams

    2The business need picks the operations: a new Jira issue becomes a Linear issue. That needs one read in Jira, one create in Linear, and a search for a later catch-up run.

  3. functions, named for the businessJira get issuehttpJira search issueshttp, pagedLinked commenttemplateIssue to LinearmappingLinear create issuehttpj2l on issuescript

    3Each chosen operation becomes a function with a name from the business, plus the shaping a script would otherwise do by hand: a mapping, a template. The script calls them by name.

Start from the need, not from the API

Write the need as one sentence, then list what has to happen, in order. Each step that reads, writes or reshapes something becomes a function.

When a Jira issue is created, open a Linear issue for it and link the two.

Step of the needFunctionTypeWhy this type
Read the new issueJira get issueHTTP callOne read in Jira, answering the issue’s fields.
Shape it for LinearIssue to LinearJSON mappingThe field names differ; the mapping says how.
Create the Linear issueLinear create issueHTTP callOne create in Linear, answering the created issue.
Say where it wentLinked commentText templateOne line, the same every time.
Find older issues laterJira search issuesHTTP call, pagedOnly for a catch-up run; one line reads every page.

Everything else Jira and Linear offer stays unconfigured. A function nobody calls is one more thing to keep working.

Name a function for what it does

The explorer beside a connection: the address of a system, who you are to it, and the endpoints it answers on.The explorer beside a connection: the address of a system, who you are to it, and the endpoints it answers on.
The explorer beside a connection: the address of a system, who you are to it, and the endpoints it answers on.
  • Name it for the business action: Linear create issue, not POST graphql. A script reads like the need when its calls do.
  • One function per business operation. If two steps call the same endpoint with different meaning, they are two functions.
  • Group by system. The explorer lists the functions under the automation they belong to, beside the connections they use.

Put the shaping in the function

The answer tab: which statuses count as an answer, and the value at a path the script receives instead of the whole response.The answer tab: which statuses count as an answer, and the value at a path the script receives instead of the whole response.
The answer tab: which statuses count as an answer, and the value at a path the script receives instead of the whole response.

A script should receive the thing it asked for, not an envelope around it. Settle that on the function:

  • Accept these statuses — anything else stops the run with what came back, so the script writes no status check.
  • Take the value at — Linear create issue answers the created issue at data.issueCreate.issue, so the script reads created.identifier.
  • When nothing is found — a lookup that may find nothing answers null; a create that made nothing stops the run.

The same holds for the other types: the JSON mapping turns a Jira issue into Linear’s fields, the template writes the comment. The script passes values and never rebuilds a structure by hand.

Configure what the API demands once

What the far end needs on every call belongs on the function, not in a loop in the script:

  • Pages — Jira search issues asks by offset, fifty at a time.
  • Wait and repeat — a 429 from Jira parks the run for as long as Jira asks.
  • Retry safety — the search is marked safe to repeat; the create is not.

The settings are explained on Connections and functions.

Test each function on its own

A configured call after Test: the answer a script gets, and the request that was sent — the credential named, never shown.A configured call after Test: the answer a script gets, and the request that was sent — the credential named, never shown.
A configured call after Test: the answer a script gets, and the request that was sent — the credential named, never shown.

Before a script uses a function, press Test with real arguments and read the answer. A function that answers what the need expects is done; the script only has to put the calls in order.

Then the script is the business logic

A configured function in the script editor: its signature and what it answers, before anything is activated.A configured function in the script editor: its signature and what it answers, before anything is activated.
A configured function in the script editor: its signature and what it answers, before anything is activated.

With the functions in place, the script is the sentence from the top of this page, written out: read the issue, create its Linear issue, remember the link, return what happened. It holds no URL, no credential, no status check and no paging. Hovering a function’s name shows its signature and what it answers.

Next

Rendered from docs/guide/designing-a-function-set.md in the product's own repository, at build time. Found a problem on this page? Write to the address in the footer.