title | sidebarTitle | icon |
---|---|---|
Integration configuration reference (nango.yaml) |
Integration config (nango.yaml) |
arrow-right-arrow-left |
Integrations are configured in the nango.yaml
file, which lives in your code base (learn more).
integrations:
asana: # Integration ID.
syncs:
asana-fetch-tasks: # Sync name.
description: | # Sync description.
Some long description, some long description, some long description,
some long description, some long description, some long description.
output: AsanaTask # Synced model
endpoint: GET /tasks # Generated endpoint to access the synced model.
sync_type: incremental # Data is replaced ('full') or upserted ('incremental') on each sync execution.
runs: every 30min # Sync frequency.
input: AsanaProject # Necessary input to execute the sync.
scopes: # Required scopes.
- scope1
- scope2
auto_starts: true # If true, data syncing starts when a new connection is created.
track_deletes: true # If true, automatically detects deleted records (for full refresh syncs only).
webhook_subscriptions: # The types of webhook this sync handles.
- subscription1
- subscription2
actions:
asana-create-task:
description: | # Action description.
Some long description, some long description, some long description,
some long description, some long description, some long description.
output: AsanaTask # Returned model
endpoint: POST /tasks # Generated endpoint to trigger to action.
input: # Necessary input to execute the action.
scopes: # Required scopes.
- scope1
- scope2
models:
AsanaTask: # Schema for sync output AND action input/output.
id: string # Required unique field for sync output models.
project_id: string
name: string
completed: boolean
created_at: date
modified_at: date
AsanaProject: # Schema for sync input.
id: string
Integration configuration fields are under integrations.<INTEGRATION-ID>
.
Sync configuration fields are under integrations.<INTEGRATION-ID>.syncs.<SYNC-NAME>
.
Each sync has a corresponding generated endpoint to fetch the data, configured in the `endpoint` field below.
<Tip>
Syncs can have multiple output models. This is useful when there is some form of dependency between the two models, e.g.
- Fetching the data for a model from the external API requires fetching the data from another model first
- You want the records of one model to be persisted before the records of another model
When defining multiple output models, you must define as many endpoints. The 1st endpoint will return the 1st model, the 2nd endpoint the 2nd model, etc.
Here's an example:
```yaml
asana-fetch-tasks-and-comments:
output:
- AsanaTask
- AsanaComment
endpoint:
- GET /tasks
- GET /comments
```
</Tip>
The value is formatted as follows: `<METHOD> <URL-PATH>`. e.g.: `GET /tasks`.
Possible method values are: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
The method/endpoint combination can be shared across syncs to unify the communication with external APIs.
Learn more about [incremental vs. full refresh](/understand/concepts/syncs#sync-modes-full-refresh-vs-incremental) syncing.
Defaults to 24h.
Sync inputs are passed from your app to the sync script via the connection metadata ([step-by-step guide](/integrate/guides/advanced/store-customer-specific-data)).
This list is just indicative; it doesn't trigger any automatic configuration (yet). List necessary scopes on the external API developer portal and your Nango UI integration settings.
Defaults to no scope.
Defaults to `true`.
Defaults to `false`.
<Info>
This setting only applies if `sync_type: full` ([details](/understand/concepts/syncs#detecting-deletions-incremental-vs-full-refresh-syncs)). For incremental syncs, this setting is ignored; instead, you must flag deleted records in the sync script using `nango.batchDelete()` ([reference](/reference/scripts)).
</Info>
Action configuration fields are under integrations.<INTEGRATION-ID>.actions.<ACTION-NAME>
.
Each action has a corresponding generated endpoint to trigger it, configured in the `endpoint` field below.
The value is formatted as follows: `<METHOD> <URL-PATH>`. e.g.: `POST /tasks`.
Possible method values are: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
The method/endpoint combination can be shared across actions to unify the communication with external APIs.
Action inputs are passed as parameters when triggering the action.
This list is just indicative; it doesn't trigger any automatic configuration (yet). List necessary scopes on the external API developer portal and your Nango UI integration settings.
Defaults to no scope.
The models
section contains the schemas referenced in the inputs & outputs of the above integrations
section.
For each model, you must define its fields and data types. Data types are based on Typescript types, with some tweaks:
nango.yaml type |
Corresponding Typescript type |
---|---|
bool or boolean |
boolean |
string |
string |
char |
string |
integer or int or number |
number |
date |
Date |
You can also pass existing Typescript types such as undefined
, null
, and more.
Your can use array types if the []
notation:
models:
Folder:
files: string[]
You can use union types such as:
models:
User:
name: string | null | undefined
You can also use string unions to enforce specific values:
models:
User:
gender: m | f
You can mix types and strings in unions:
models:
User:
gender: male | female | null
Your can use other models as types:
models:
User:
id: string
Account:
users: User[]
You can have a model extend the properties of another base model:
models:
Issue:
id: integer
title: string
author: string
GithubIssue:
__extends: Issue
issue_number: string
LinearIssue:
__extends: Issue
roadmap_id: string
You can allow dynamic keys in models:
models:
Task:
id: string
__string: string
Which translates to the following generated Typescript model:
export interface Task {
id: string;
[key: string]: string;
}
Changes to your integration configuration become active once you deploy them to a Nango environment using the nango deploy
CLI command.
These changes can have significant impacts, in particular, if you:
- Add a sync
- Remove a sync or an action
- Change a model or a script
Unless you sync configuration specifies auto_start=false
, the deployment will kick off the data synchronization between the external API and Nango, for all relevant connections.
This change will be reflected in the Nango UI in Integrations > select your integration > Script tab.
Removing a sync will erase all the cached data related to that sync, for all relevant connections. The synced records will no longer be accessive via the Nango API & SDKs.
This change will be reflected in the Nango UI in Integrations > select your integration > Script tab.
Changing the integration ID in your configuration is the equivalent of deleting the sync with the old integration ID, and creating a new one. So, the data cached by the old sync will be deleted (for all relevant connections).Removing an action will cause the failure of any request to trigger this action.
This change will be reflected in the Nango UI in Integrations > select your integration > Script tab.
For full refresh syncs, as the data is replaced on each sync execution, the new model and script logic will apply to all records as soon as the sync executes following the deployment.
For incremental syncs, you can end up with model disparities, as older records will have outdated content. You will still be able to fetch them from the Nango cache. In some cases, it's better to trigger a full resync via the API or the Nango UI, so that all historical records are fetched again using the new script & model.
The models defined in your nango.yaml
configuration are used to generate Typescript models (in the nango-integrations/models.ts
file).
You can then import the relevant models from models.ts
in your integration scripts.