Create a custom integration
Step-by-step guide on how to create a custom integration with Nango.
In Nango, integration use-cases are mapped to syncs and actions. Before starting, determine if a sync, an action, or a combination of both fits your use case.
Pre-requisite: set up an integrations folder (step-by-step guide).
Edit the nango.yaml
configuration
In your nango-integrations
folder, open the nango.yaml
configuration file (reference).
Configure a sync
This example nango.yaml
configuration describes a sync that continuously fetches contacts from Salesforce:
Learn more about sync configurations in the reference and check out example templates.
Configure an action
This example nango.yaml
configuration describes an action that synchronously fetches a contact by ID from Salesforce:
Learn more about actions configurations in the reference and check out example templates.
Write an integration script
Generate the integration script scaffolding
Everytime that you modify the nango.yaml
configuration, run:
Among other things, this will generate the integration script files with initial scaffolding for any sync or action that you added (existing integration script files stay untouched).
Start script development mode
Before you plan to modify your integration scripts, run:
This command starts a process that continuously compiles your integration scripts and prints code syntax errors.
Write a sync script
Open the generated sync script (named [sync-name].ts
) which should contain the following scaffolding :
Fill in the fetchData
method with your integration code (in the example here, we fetch tasks from Salesforce):
In this integration script, the following Nango utilities are used:
nango.lastSyncDate
is the last date at which the sync has runawait nango.batchSave()
to persist external data in Nango’s cacheawait nango.get()
to perform an API request (automatically authenticated by Nango)await nango.log()
to print console logs (replacesconsole.log()
)
Learn more about sync scripts: understanding syncs, script reference, example templates.
Write an action script
Open the generated action script (named [action-name].ts
) which should contain the following scaffolding :
Fill in the runAction
method with your integration code (in the example here, we fetch available contact fields from Salesforce):
In this integration script, the following Nango utilities are used:
await nango.get()
to perform an API request (automatically authenticated by Nango)nango.ActionError()
to report errors in the execution of the integration scriptawait nango.log()
to print console logs (replacesconsole.log()
)return
will synchronously return results from the action trigger request
Learn more about action scripts: understanding actions, script reference, example templates.
Test your integration scripts locally
Easily test your integration scripts locally as you develop them with the dryrun
function of the CLI (reference):
Because this is a dry run, syncs won’t persist data in Nango (and actions never persist data); instead, the retrieved data will be printed to the console.
By default, dryrun
retrieves connections from your Dev
environment.
Deploy your integration scripts
Nango provides multiple cloud environments so you can test your integration scripts more thoroughly before releasing them to customers.
To deploy all integration scripts at once, run (reference):
In the Nango UI, navigate to the Endpoints tab of the relevant integration(s) to verify the deployment succeeded.
Learn more about scripts.
Questions, problems, feedback? Please reach out in the Slack community.
Was this page helpful?