Scripts

Examples

Sync script

import type { GithubIssueDemo, NangoSync } from './models';

export default async function fetchData(nango: NangoSync) {
    // Fetch issues from GitHub.
    const res = await nango.get({
        endpoint: '/repos/NangoHQ/interactive-demo/issues?labels=demo&sort=created&direction=asc'
    });

    // Map issues to your preferred schema.
    const issues: GithubIssueDemo[] = res.data.map(({ id, title, html_url }: any) => {
        return { id, title, url: html_url };
    });

    // Persist issues to the Nango cache.
    await nango.batchSave(issues, 'GithubIssueDemo');
}

Action script

import type { NangoAction, GithubCreateIssueInput, GithubCreateIssueResult } from './models';

export default async function runAction(nango: NangoAction, input: GithubCreateIssueInput): Promise<GithubCreateIssueResult> {
    // Create a GitHub issue.
    const res = await nango.post({
        endpoint: '/repos/NangoHQ/interactive-demo/issues',
        data: {
            title: `[demo] ${input.title}`,
            body: `The body of the issue.`,
            labels: ['automatic']
        }
    });

    // Send response.
    return { url: res.data.html_url, status: res.status };
}

Read more about scripts to understand what role they play in Nango.

Scripts expose a helper object (NangoSync for sync scripts, NangoAction for action scripts), which allows to interact with external APIs & Nango more easily.

The script helper object shares some methods, but not all, with the Node backend SDK, which is why this reference will link to the Node SDK reference a lot.

Common helper methods

HTTP requests

HTTP requests in scripts are made with the proxy (concept / step-by-step guide / reference).

There is one simplification to using the proxy in scripts. Because scripts always execute in the context of a specific integration & connection, you do not need to specify the providerConfigKey & connectionId parameters when calling the proxy from script.

Instead of writing:

const res = await nango.get({
    endpoint: '/external-endpoint',
    providerConfigKey: '<string>',
    connectionId: '<string>'
});

You can write:

const res = await nango.get({ endpoint: '/external-endpoint' });

Logging

You can collect logs in scripts. This is particularly useful when:

• developing, to debug your scripts
• in production, to collect information about script executions & understand issues

Collect logs in scripts as follows:

await nango.log("This is a log.");

Logs can be viewed & searched in the Nango UI. We plan to make them exportable in the future as well.

Environment variables

Scripts sometimes need to access sensitive variables that should not be revealed directly in the script code.

For this, you can define environment variables in the Nango UI, in the Environment Settings tab. Then you can retrieve these environment variables from scripts (reference).

Trigger action

Scripts currently do not support importing files, which limits the ability to share code between scripts.

As a temporary workaround, you can call action scripts from other scripts (reference).

Paginate through API responses

Follow the pagination step-by-step guides to learn how to easily paginate through API responses.

Manage connection metadata

Retrieve, edit or override the connection metadata.

Get connection

Get the connection details, including the API credentials (reference).

Sync-specific helper methods

Sync scripts persist data updates to the Nango cache, which your app later fetches (cf. step-by-step guide).

Save records

Upserts records to the Nango cache (i.e. create new records, update existing ones). Each record needs to contain a unique id field used to dedupe records.

const githubIssues: GitHubIssue[] = ...; // Fetch issues from GitHub API. 

await nango.batchSave(githubIssues, 'GitHubIssue');

Parameters

Show child attributes

recordList · Model[] · required

The list of records to persist.

modelType · string · required

The model type of the records to persist.

Delete records

Marks records as deleted in the Nango cache. Deleted records are still returned when you fetch them, but they are marked as deleted in the record’s metadata (i.e. soft delete).

The only field that needs to be present in each record when calling batchDelete is the unique id; the other fields are ignored.

const githubIssuesToDelete: { id: string }[] = ...; // Fetch issues to delete from GitHub API. 

await nango.batchDelete(githubIssuesToDelete, 'GitHubIssue');

Parameters

Show child attributes

recordList · { id: string }[] · required

The list of records to delete.

modelType · string · required

The model type of the records to delete.

Action-specific helper methods

ActionError

You can use ActionError in an action script to return a descriptive error to your app when needed:

export default async function runAction(nango: NangoAction): Promise<Response> {
    // Something went wrong...

    throw new ActionError({ any_key: 'any_value' });
}

In this case, the response to the trigger action call will be:

{
  "error_type": "action_script_failure",
  "payload": {
    "any_key": "any_value"
  }
}

Questions, problems, feedback? Please reach out in the Slack community.