Migrate your legacy SuiteScript framework (V1/V2) flows to integrator.io

Summary: This article explains how to migrate SuiteScript framework V1 and V2 flows from the legacy SuiteScript-based Celigo Integrator to integrator.io before the legacy platform is retired.

Important: The V1 and V2 references in this article are SuiteScript framework versions. They are different from Integrator V1, which uses Java bridges. Integrator V1 is not covered by this article.

Because all flow configuration is stored inside your NetSuite account, you can extract it yourself without Celigo involvement. This article covers four stages: extracting your legacy flow configuration from NetSuite, rebuilding the flow in integrator.io, testing with a known data set, and going live.

The legacy SuiteScript-based Celigo Integrator is a NetSuite bundle (Bundle ID: 20038) that runs SuiteScript framework V1 and V2 flows and is scheduled for retirement on Jan 31st, 2027. After that date, these flows will stop running. This article walks you through extracting your legacy flow configuration from NetSuite and rebuilding each flow in integrator.io.

Because the legacy integrator stores all flow configuration inside your NetSuite account, not on Celigo's servers, you can recover the complete setup yourself, as long as the bundle has not been uninstalled.

Estimated time: Simple scheduled flows with no custom scripts take 1–2 hours per flow. Flows with hooks, chained flows, or real-time triggers typically take 1–2 days and may benefit from involvement by Celigo Professional Services.

This article covers four stages:

1. Understanding what a legacy flow is made of
2. Extracting the flow configuration, field mappings, and hook scripts from NetSuite
3. Rebuilding the flow in integrator.io
4. Testing and going live

Who performs these steps: All extraction steps (stage 2) can be completed by your NetSuite administrator. The rebuild steps (stage 3) can also be done in-house, but flows with custom scripts (hooks), chained flows, or real-time triggers are more complex; many customers engage Celigo Professional Services or an implementation partner for that stage.

Caution: Never run the legacy flow and the new integrator.io flow simultaneously; duplicate records will be created in the destination system. The go-live checklist at the end of this article ensures you turn off the legacy flow before turning on the new one.

Before you begin

Stage 1: Understand what you're migrating

A SuiteScript framework V1 or V2 flow covered by this article is defined by four components, all stored inside your NetSuite account:

1. The flow record: a custom NetSuite record that stores the flow's name, schedule, type (batch or real-time), and full configuration as a JSON text blob.
2. The configuration JSON: embedded in the flow record. It describes the source and destination record types, the saved search used to select records, hook script references, and pointers to field mapping files.
3. The mapping files: JSON text files in the NetSuite File Cabinet, one per mapping set, named by a globally unique identifier (GUID).
4. Hook scripts: SuiteScript files referenced by the flow, present only if the flow uses custom logic.

Migrating a flow means extracting all four components and recreating their behavior in integrator.io.

Stage 2: Extract your legacy flow configuration

Stage 2 covers how to locate your legacy flows in NetSuite and extract the three files you need for migration: the configuration JSON, the field mapping files, and any hook scripts.

Step 1: Verify the bundle is still installed

1. Sign in to NetSuite as Administrator.
2. Go to Customization > SuiteBundler > Search & Install Bundles > List.
3. Look for a bundle named "Celigo Integrator" with Bundle ID 20038.

If the bundle appears, even if the integration has been inactive for years, your flow data is intact. If it doesn't appear, the bundle was uninstalled, and its records were deleted. See Bundle was uninstalled in the troubleshooting section.

Step 2: Open the legacy flow list

The legacy integrator's own screens inside NetSuite have been deprecated. Instead, you link your legacy integrations to integrator.io once, and then view them from the integrator.io homepage.

1. Sign in to integrator.io. (If you do not have an account yet, see Stage 3, Step 2; you will need one for the migration anyway.)
2. Create a connection to your NetSuite account if you do not already have one: go to Resources > Connections > + Create connection, select NetSuite as the application, fill in the connection form, and click Save & authorize. Your Account ID is found in NetSuite under Setup > Integration > SOAP Web Services Preferences > Account ID.
3. Back on the Connections page, click your NetSuite connection's name to edit it.
4. Expand the Advanced section, check the box Link SuiteScript integrator, then save and close the connection.
5. Click Home in the main navigation.

You should now see your legacy NetSuite integrations appear as tiles on the integrator.io homepage, alongside any existing IO integrations. Legacy tiles are marked with a grey bar. Open a tile to see its flows, including each flow's name, type, schedule, and settings. If the tiles do not appear, or you cannot create the connection, use Step 3 to look for the flow records directly in NetSuite.

Step 3: Find flow records directly (alternative method)

Use this method if the legacy integration isn't accessible through integrator.io. Most SuiteScript-based legacy flows covered by this article can be found using the custom record types below.

1. Go to Customization > Lists, Records, & Fields > Record Types.
2. Find the following record types and select List next to each:

Note: Some older integration apps may not have the expected batch custom record. Those configurations are not covered by this procedure. If the expected flow record is not present, do not assume that the integration has no legacy configuration.

3. If you have a flow reference, for example, i123 or e456, use the letter to identify which list to open: i = Real Time Import Flow, e = Real Time Export Flow. Batch flows are usually referenced by name. The number is the record's internal ID; match it against the ID or Flow ID column, or open the record directly by internal ID.

Once you open the flow record, you'll see the flow's name, integration, record type, and (for batch flows) its schedule and Version field. For batch flows, the Version field identifies the SuiteScript framework version, V1 or V2. These framework versions are not the same as Integrator V1.

Step 4: Copy the flow configuration JSON

1. On the flow record, find the Configuration field (a long free-text field). The field ID varies by flow type:
   • Batch flows: custrecord_celigo_batch_data_flow_conf
   • Real-time exports: custrecord_celigo_rt_export_conf
   • Real-time imports: custrecord_celigo_rt_import_flow_conf
2. Copy the entire contents and save the text as <flow-name>-config.json.
3. If the Configuration field is empty, open the file linked in the Configuration File field and download it instead.

You now have a JSON file containing everything about the flow: source and destination record types, the saved search it uses, schedule details, hook references, and mapping file pointers.

Note: If the content isn't readable JSON (for example, it looks like random characters), the file is encrypted. Contact Celigo Support and reference this article; they can assist with decryption.

{
  "requestMappingRef": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
  "responseMappingRef": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901" },
  "uiProperties": {
    "operationMappings": ["c3d4e5f6-a7b8-9012-cdef-123456789012"]
  },
  "nextDataFlow": null,
  "hook": { "preSavePage": "celigo_hook_preprocess" }
}

The GUID values under requestMappingRef.id, responseMappingRef.id, and uiProperties.operationMappings are the mapping file names you'll download in step 5.

Step 5: Download the field mapping files

1. In the configuration JSON, search for requestMappingRef and responseMappingRef. Each entry has an id value that looks like a long random string (a GUID). Also check uiProperties.operationMappings for additional GUIDs.
2. In NetSuite, go to Documents > Files > File Cabinet.
3. Navigate to Celigo > Integrator > Configuration > Global > Mappings.
4. Download the file named <GUID>.txt for each GUID you found.

You now have one or more JSON files listing every field-to-field mapping the legacy flow uses. Keep these alongside the configuration JSON; they're the complete specification of your flow.

Step 6: Capture hook scripts

Complete this step only if your flow uses custom scripts.

1. In the configuration JSON, search for hook. Note the referenced hook information.
2. Ask your NetSuite administrator to first check Customization > Scripting > Scripts. You can filter for scripts whose names start with "Celigo," or check the bundle's folder in the File Cabinet at Celigo > Integrator > Scripts.
3. If you cannot locate the hook in those locations and the configuration contains a hook file name, copy the file name and use NetSuite global search to locate the file.
4. Download or copy the referenced script file.

Note: The locations above are common places to find hook scripts, but the script location is not guaranteed.

If there are no hook entries in your configuration JSON, your flow is configuration-only and doesn't require this step.

Stage 3: Rebuild the flow in integrator.io

Stage 3 covers creating the equivalent flow in integrator.io using the configuration you extracted in stage 2. Complete stage 2 before starting here.

Note: Most customers can complete stage 3 themselves for simple scheduled flows. For flows with hooks, chained flows, or real-time triggers, Celigo Professional Services has done this migration many times and can accelerate the rebuild. Contact your account manager to discuss an engagement.

Step 1: Map legacy concepts to integrator.io equivalents

Use this table to translate the components you extracted from NetSuite into integrator.io equivalents before you start building:

Step 2: Set up integrator.io

1. Sign in to integrator.io. If you don't have an account, contact your Celigo account manager.
2. Create a NetSuite connection: go to Resources > Connections > Create connection > NetSuite. Follow the token-based authentication setup. Your NetSuite admin creates an access token at Setup > Users/Roles > Access Tokens > New, then pastes the Token ID and Token Secret into the connection form.
3. Select Test connection.

The connection status turns green when the connection is working. If it fails, recheck the token values and confirm that the token's role has web services permission.

4. Create a connection to the other system in your integration the same way: Resources > Connections > Create connection, select the application, and enter its credentials.

Step 3: Build the flow

1. Go to Integrations, open or create an integration tile, and select Create flow.
2. Add the source (export): select the connection for the system the data comes from. For a NetSuite source, select NetSuite > Saved search and pick the same saved search named in your legacy configuration JSON. Set the schedule to match the legacy flow's schedule.
3. Add the destination (import): select the connection for the system data goes to, choose the same record type or endpoint the legacy flow wrote to, and set the same operation (add, update, or add or update).
4. Recreate the mappings: open the import step's Mappings editor and enter each field pair from the mapping files you downloaded in stage 2, step 5. The legacy mapping JSON lists source and destination field names; copy them one row at a time.
5. Recreate hooks (if any): go to Resources > Scripts > Create script, port the legacy hook logic into the matching integrator.io hook type (preSavePage, preMap, postMap, or postSubmit), and attach the script in the export or import's Hooks section. Legacy SuiteScript hook code can't be pasted as-is; it must be adapted to integrator.io's scripting model. This is typically the most complex part of the migration.
6. Save the flow but leave it turned off.

You'll see the complete flow on the flow builder canvas: one export step, one import step, mappings saved, and hooks attached.

Step 4: Handle real-time flows

If your legacy flow reference started with e (real-time export out of NetSuite):

1. Install the integrator.io SuiteApp in NetSuite if not already present. integrator.io prompts you to do this during NetSuite connection setup.
2. In integrator.io, create the export as type NetSuite > Real-time and configure the same record type and filter condition shown in your legacy configuration JSON.

If your legacy flow reference started with i (real-time import into NetSuite):

Check whether the source system supports webhooks in integrator.io. If it does, build the flow with a webhook-based listener. If it doesn't, use a scheduled flow with a 5–15 minute interval. Be aware that polling introduces latency the original real-time flow didn't have; verify this is acceptable for your use case before going live.

Stage 4: Test and go live

Always test with a small, known data set before enabling the flow for production.

1. Pick or create one test record in the source system, for example, one sales order with a recognizable name like MIGRATION-TEST-001.
2. If your export uses a saved search, temporarily add a filter so it returns only the test record.
3. In integrator.io, open the flow and select Run now.
4. Watch the run in the Dashboard > Run console.

The run should complete with one success and zero errors. Verify that the test record was created or updated in the destination system with all fields populated correctly.

5. Compare each field against a record the legacy flow previously processed. Every mapped field should match.
6. Remove the temporary saved-search filter.

Troubleshooting

This section covers the most common errors encountered during migration, their causes, and how to resolve them. Match the symptom in the left column to find the fix.

Go-live checklist

Complete every item before enabling the flow.

• Legacy flow configuration JSON, mapping files, and hook scripts are saved locally as a permanent archive.
• New integrator.io flow completed the first-run test with one success and zero errors.
• A batch of 10–50 production records processed correctly in a second test run.
• Field-by-field comparison against legacy output completed for at least three records.
• All hooks ported and verified (or confirmed the flow has none).
• Schedule on the integrator.io flow matches the legacy schedule; verify timezone.
• Error alerting configured in integrator.io (Integration > Notifications) so errors notify your team.
• The legacy flow is turned off in NetSuite: open the flow record and select the Disabled or Inactive checkbox. Do not run both flows simultaneously; duplicate records will be created in the destination system.
• The integrator.io flow is turned on.
• After one week of clean runs: archive the legacy configuration and schedule the bundle's retirement with your NetSuite admin.

Glossary

This glossary defines key terms used throughout this article. Terms specific to the legacy SuiteScript Integrator are labeled accordingly; terms marked as integrator.io terms refer to the new platform.

Legacy SuiteScript field IDs and JSON reference (for engineers)

Legacy record types and key field IDs

The following custom record types are used by the SuiteScript-based legacy flows covered by this procedure. Some older integration apps may not have the expected batch custom record. Use these IDs for direct record access or scripted extraction.

Other useful fields: integration link (*_integr or *_integration), use case or scenario (*_usecas or *_usecase), schedule (custrecord_celigo_batch_data_flow_sch), disabled flag (*_disabl), record type (*_record or *_recordtype), and real-time qualifier (custrecord_celigo_qualifier).

Bulk extraction via saved search

To extract flow records that use these custom record types, create a saved search on each applicable record type above with columns: internalid, name, the flow ID field, the configuration field, integration, scenario, isinactive, and the disabled flag. Export as CSV for a complete flow inventory.

The configuration JSON can exceed CSV cell character limits. For full fidelity, pull the configuration field via SuiteScript or copy it per record.

Configuration JSON anatomy (V2)

Key paths inside the flow configuration JSON:

• requestMappingRef.id and responseMappingRef.id: GUID of the mapping file. File Cabinet path: Celigo/Integrator/Configuration/Global/Mappings/<GUID>.txt.
• uiProperties.operationMappings: additional sub-mapping GUIDs.
• nextDataFlow (Celigo.integrator.model.DataFlowReference) chained flow reference; carries dataFlowId and dataFlowInternalId.
• Hook references: search for hook; values name SuiteScript functions shipped in the bundle or in customer files.
• Saved search and record type identifiers for source and destination.

Mapping and configuration files may be encrypted at rest; the legacy integrator decrypts them via its internal crypto module on load. 

Flow reference format

i<internalId> = real-time import flow record; e<internalId> = real-time export flow record. The number is the NetSuite internal ID of the custom record; cross-check against the Flow ID field visible in the UI.

SuiteScript framework V1 vs. V2

The batch flow record's Version field identifies the SuiteScript framework version, V1 or V2. These framework versions belong to the SuiteScript-based legacy integrator covered by this article and are different from Integrator V1, which uses Java bridges.