The integrator-api module lets a script work with exports and imports in two ways. A real resource is one that exists in your account with its own ID, which your script runs by passing that ID. A virtual resource is one your script defines inline as a JSON object and runs immediately — it's never saved to your account and has no ID. Knowing which one you need determines which method you call.
This article explains the difference and when to choose each. For the method signatures, see integrator.io API and JavaScript runtime objects.
Real resources
A real resource is an export or import you created in integrator.io and can see in the UI. It has an ID, it can be reused across flows and scripts, and you change its configuration by editing the resource rather than by editing code.
To run one, pass its ID:
exports.run({ _id: '5f4••••••••••••••••••d34' })Use a real resource when:
- Several flows or scripts need the same export or import logic.
- You want someone without scripting access to be able to see and change the configuration.
- You want the resource captured in your account's configuration when you clone, template, or download the integration.
To find a resource's ID, see Retrieve the resource ID.
Virtual resources
A virtual resource is defined entirely inside your script. You pass the full resource definition — the connection ID, the adaptor type, and the adaptor-specific configuration — in the function call, and integrator.io runs it against the connection you named. Nothing is added to your account.
exports.runVirtual({
export: {
_connectionId: '612••••••••••5e7',
// adaptor-specific configuration
}
})Virtual resources still require a real connection. The connection supplies the credentials; only the export or import definition is virtual.
Use a virtual resource when:
- The configuration depends on values your script computes at runtime.
- You need a one-off query that doesn't justify a saved resource.
- You're populating a form field on demand and don't want a saved export cluttering the account.
Three methods run virtual resources:
-
exports.runVirtual( options )— runs a virtual export and returns the data. -
exports.runVirtualWithPaging( options )— runs a virtual export and returns one page at a time, for result sets larger than a single page. -
imports.runVirtual( options )— runs a virtual import and sends the data to the destination.
Mapping without importing
imports.runMapping( options ) is a third case. It takes a virtual import definition and a set of records, applies only the mapping instructions in that definition, and returns the mapped data. It doesn't send anything to the destination application.
Use it when you want the import's field mapping applied to records inside your script — to inspect the mapped output, pass it to another step, or reuse one mapping definition in more than one place — without writing to the destination.
The response for each record includes the mapped data, a status code, and any mapping errors.
Choosing between them
| You want to | Use |
|---|---|
| Run an export that already exists in your account | exports.run( options ) |
| Run an export defined in your script | exports.runVirtual( options ) |
| Run a script-defined export and page through large results | exports.runVirtualWithPaging( options ) |
| Run an import that already exists in your account | imports.run( options ) |
| Run an import defined in your script | imports.runVirtual( options ) |
| Apply an import's mapping without writing to the destination | imports.runMapping( options ) |
To build a virtual definition, start from a real resource: create the export or import in the UI, retrieve its JSON through the integrator.io REST API, and remove the read-only fields the platform manages. For the full procedure, see Build an export definition for a script.