--- title: Import Swimlane Solution Packages slug: import-swimlane-solution-packages docTags: createdAt: 2025-08-11T11:13:48.000Z --- Import Swimlane Solution Packages (SSPs, file extension `.ssp`) into a Turbine instance. Packages contain one or more applications, applets, playbooks, builder components, or builder solutions along with all associated entities. ## At a Glance | **Step** | **Action** | | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Upload the `.ssp` or `.json` file. | | 2 | Review and select the entities to import. | | 3 | Optionally turn on **Import playbooks/webhooks in enabled state**. If you turn it on, choose whether to retry skipped playbook runs. | | 4 | Resolve any duplicate or overwrite conflicts. | | 5 | Resolve any plugin version requirements. | | 6 | Monitor import progress. | | 7 | Review results and resolve actionable issues. | | 8 | Enable any remaining disabled playbooks and webhooks. | | 9 | Reconfigure credentials, key store values, and secure asset fields. | :::hint{type="info"} Importing SSPs requires the **System Administrator** role. ::: :::hint{type="info"} Connectors are not included in SSPs. Install and configure required connectors separately before importing. During import, Turbine displays connector cards showing which connectors are needed so you can verify they are installed. ::: ## Upload and Import an SSP 1. Open the **Applications and Applets** page. 2. Click the plus icon and select **Import or Export a package**. 3. Drag and drop your `.ssp` or `.json` file into the dialog, or click **Browse** to select it. 4. Wait for Turbine to upload and validate the package. A spinner indicates upload progress. After validation, Turbine either proceeds to the entity selection screen (if the SSP contains a relationship graph) or directly to import (for older SSP formats). ## Select Entities to Import After validation, Turbine displays a **tree view** of all entities in the package. The tree shows each entity with its type label and any child entities nested beneath it. 1. Review the entity tree. By default, all entities are selected. 2. Use the **Select All** / **Deselect All** toggle to change the selection in bulk. 3. Click individual check boxes to include or exclude specific entities. 4. Optionally, turn on **Import playbooks/webhooks in enabled state** (see below). 5. Click **Import** (or **Overwrite** when selected items already exist in the tenant). ![](https://api.archbee.com/api/optimize/n8uUzk0MM4uC57-zlHNtY/17sM3cj-mTRKlZSGDBDsk_package-import-enable-playbooks-webhooks.png) ### Import Playbooks and Webhooks in Enabled State By default, imported playbooks and webhooks stay **disabled**. That is safer while a package is still loading, but any matching trigger during the import window (webhook POST, scheduled tick, or another inbound event) is **skipped**. After import, you would otherwise enable the content from Take Action, and those skipped runs would not run again unless you retry them later from Operational Health. Starting in **Turbine 26.4.0**, the entity-selection screen includes **Import playbooks/webhooks in enabled state**. The same toggle appears when you **deploy** from the Content Library. | **Choice** | **What happens** | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Toggle **off** (default) | Playbooks and webhooks remain disabled after import. Enable them later. Skipped runs from the import window are not replayed as part of this import. | | Toggle **on**, then **No** | After entities finish importing, Turbine enables the imported playbooks and webhooks. It does not replay skipped runs from the import window. | | Toggle **on**, then **Yes** | Turbine enables the imported playbooks and webhooks, then replays skipped playbook runs from the import window. | When you turn the toggle **on**, Turbine asks: **Retry skipped events?** Would you like to retry skipped playbook runs during import? - **Yes** — enable, then replay skipped runs from the import window. - **No** — enable only. You cannot replay skipped runs unless the enable toggle is on. Replay always runs **after** enablement. Use this when you need the solution running as soon as import finishes, and you do not want webhook or schedule traffic from the import window to be lost. :::hint{type="info"} Package **try** / dry-run does not enable playbooks or webhooks and does not replay skipped runs. ::: ::Image[]{src="https://api.archbee.com/api/optimize/n8uUzk0MM4uC57-zlHNtY/abCdh08NSXu1-yQt4DUV8_retry-skipped-events-confirm.png" size="40" isUploading="false" position="center" width="800" height="236" darkWidth="800" darkHeight="236" showCaption="false"} ### What Turbine Replays The replay window starts when you start the import and ends after the imported entities are loaded and enabled. | **Trigger type** | **What happens** | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Webhook and other inbound events | Turbine replays each skipped run that targeted an imported playbook during the window, in the order the events arrived. | | Scheduled (cron) playbooks | If a schedule fired more than once while the playbook was still disabled (for example, a one-minute schedule during a multi-minute import), Turbine replays only the **most recent** missed tick for that playbook. Earlier ticks in the same window are not replayed. | Progress can show these phases after the package contents are imported: - **Enabling imported playbooks and webhooks** - **Replaying skipped playbooks...** On a small package, these phases can be brief. ::Image[]{src="https://api.archbee.com/api/optimize/n8uUzk0MM4uC57-zlHNtY/iOXwXwGx24a-fBZ9cOSA__replaying-skipped-playbooks-progress.png" size="20" isUploading="false" position="center" width="800" height="515" darkWidth="800" darkHeight="515" showCaption="false"} ### Import Results: Enablement and Replay Summary When enablement (and optional replay) ran, the import results include a reactivation summary. Depending on what occurred, it can include: - How many playbooks and builder playbooks were enabled - How many playbook runs were skipped during the import window - How many of those runs were submitted and queued for replay - Whether older scheduled ticks were skipped because a newer missed tick for the same playbook was replayed - Playbook IDs that were enabled You can still review skipped and replayed runs in **Operational Health → Events**. Filter around the import finish time to confirm webhook and schedule activity. If you enabled content but skipped replay, retry individual or bulk skipped runs from Operational Health after import. See the Operational Health Events topic for retrying runs skipped while a playbook was disabled. ### Partial Import Warning If you deselect some entities from the package, Turbine displays a confirmation dialog: :::BlockQuote *You are choosing not to bring in all the content of this solution. This will likely cause the solution not to work as intended.* ::: You can click **Cancel** to return to the selection screen, or **Install Anyway** to proceed with the partial import. :::hint{type="info"} SSPs exported from Turbine versions before 11.4.0 do not support selective entity import. All entities in those packages are imported automatically. ::: ## Import Application Records You can import application records packaged within an SSP into another tenant. Before importing: - Ensure you are logged into the destination tenant. Take the following Steps to Import Application Records: 1. Navigate to **Applications & Applets**. 2. Click the plus icon. 3. Select  **Import or Export a package**.  4. Select **Import**. Drag and drop the .ssp file or browse for it and open it. ![](https://api.archbee.com/api/optimize/n8uUzk0MM4uC57-zlHNtY/HmMhoeejqUiCSp_tIpwF6_image7.png) 5. Turbine uploads and validates the package. The **Package Import** dialog opens. 6. Applications that contain exported records display an **Import Records** toggle. 7. Enable the toggle for: - KB Article - Routing Rule 8. Click **Import Settings** to configure record import settings. Refer to the Configure Import Settings for more information. ### Configure Import Settings ![](https://api.archbee.com/api/optimize/n8uUzk0MM4uC57-zlHNtY/05uWl1mt0pZ-OJyy7ZxI0_image3.png) ### Key Field  The **Key Field** determines how imported records are identified. Available options in the dropdown include all columns from the exported .csv file.  By default **Tracking ID** is selected. ### Creation Type The following creation modes are available: | **Option** | **Description** | | --------------------- | --------------------------------- | | Insert only | Inserts new records only | | Insert and/or Replace | Replaces matching records | | Insert and/or Update | Updates existing matching records | By default **Insert only** is selected. ### Error Handling The following error handling options are available: | **Option** | **Description** | | ------------ | ---------------------------- | | Set as empty | Sets invalid values to empty | | Skip row | Skips records with errors | | Stop Import | Stops the import process | By default **Skip row** is selected. ### Complete the Import 1. Click **Apply** to save import settings. 2. Click **Import**. Turbine imports the records into the selected applications. ### Reference Fields When importing records that contain reference fields: - References are preserved when the referenced application and records exist in the destination tenant. - References are also preserved when the referenced records are imported as part of the same SSP. - If a referenced application is not imported and does not exist in the destination tenant, the reference value cannot be resolved. - If referenced records are not imported or cannot be matched in the destination tenant, the reference value is imported as empty. :::hint{type="info"} Turbine may display warnings when reference values cannot be resolved during import. ::: :::hint{type="info"} - If you do not open **Import Settings**, the import uses the default settings: - Key Field = Tracking ID - Creation Type = Insert only - Error Handling = Skip Row - Before carrying out Import, it is recommended to read Export Application Records. ::: ## Handle Connectors During Import SSPs reference connectors by name but do not include connector packages. When you select entities that reference connectors, Turbine displays a **connector panel** next to the entity tree. The panel shows: - The number of connectors required (for example, *"In order for this SSP to import successfully, we must import 2 Connectors first."*). - A card for each connector showing its **icon**, **title**, and **author** from the Marketplace. - A **View Details** link on each card to open the connector's full Marketplace details. If a referenced connector is not installed on the target system: 1. Note the connector name from the panel. 2. Install it from the **Marketplace** before or after import. 3. If you import without the connector, Turbine displays a warning. You can install the connector later and manually link it. ## Resolve Duplicate and Overwrite Conflicts If an entity in the package already exists in the target environment, Turbine alerts you. ### Non-Selectable SSPs (No Relationship Graph) If the SSP does not contain a relationship graph, Turbine displays a list of duplicate entities with a warning icon. You must confirm the overwrite for all duplicates: 1. Review the list of existing entities that will be overwritten. 2. In the confirmation dialog, **press and hold** the mouse button on the overwrite button to confirm. 3. Release to complete the overwrite. ### Selectable SSPs (With Relationship Graph) If the SSP contains a relationship graph, Turbine shows duplicate entities highlighted in the entity tree with an overwrite icon. | Conflict Type | Description | Action | | ---------------------------- | --------------------------------------------------------- | ------------------------------------------------------- | | **UID conflict** | An entity with the same unique identifier already exists. | Select the entity to overwrite it, or deselect to skip. | | **Name or acronym conflict** | A different entity with the same name or acronym exists. | Select to overwrite, or deselect to skip. | A warning message appears at the top of the selection screen: :::BlockQuote *Certain items already exist in the environment. Selecting these items will overwrite the existing files.* ::: If any selected entity requires an overwrite, the **Import** button changes to **Overwrite**. Click it, then **press and hold** to confirm. ## Import Errors: Same Name, Different Sharing ID Sometimes the entity tree does not list an item as a simple duplicate, but the import still stops with errors when Turbine **saves** packaged entities. Typical messages include: - **Builder component**: BuilderComponent named '\' already exists in this environment with a different sharing Id. To proceed further with the import, the existing BuilderComponent must be renamed. - **Playbook**: Playbook with name '\' already exists - **Asset or other entities**: An error was encountered while saving the asset or Save of \ failed (often with a chain of dependent builder components listed in the error text) **What this means:** The target tenant already has an entity **with the same name** as something in the package, but that existing entity came from **another export or solution** and has a **different sharing identity** than the one in the SSP. Turbine does **not** merge those automatically. The text is **intentional** so you know exactly which name conflicts and that you must act before the import can succeed. | Approach | When to use it | | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Rename or delete** the conflicting entity **in the target tenant** | You want to keep the version from the SSP and the UI directs you to free the name (for example rename the existing builder component or playbook). | | **Change what you import** | On the entity selection screen, **deselect** types or items you do not need, if overlapping content from two solutions makes part of the package redundant. | | **Adjust the package** | Work with your team to rename entities **inside** the SSP (or re-export from a clean source) when bulk collisions are hard to fix in the tenant. | | **Use a clean tenant** | You need a full import without resolving many collisions (for example a new environment used only for that solution). | :::hint{type="info"} For long error lists, use **Copy Notes** or **Download Notes** on the import results screen, or capture a **HAR** file while reproducing the import, so support can see the same messages you see. ::: ## Resolve Plugin Version Requirements If the SSP requires plugins that are a different version than what is installed on the target system, Turbine pauses the import and displays a notification. 1. Review the list of plugins that need to be upgraded. 2. Upgrade each plugin to the required version. 3. After all plugins are upgraded, click **Continue** to resume the import. :::hint{type="warning"} If the target system has a newer plugin version than the SSP expects and the SSP requires a downgrade, the import cannot proceed. Re-export the SSP from a system with a compatible plugin version. ::: ## Monitor Import Progress After you start the import, Turbine displays a **progress spinner** with a percentage and a real-time status label. | **Progress** | **Status Label** | | ------------ | ---------------------------------------------------- | | 0% | Preparing to start the import | | 10% | Validating package contents | | 20% | Installing required connectors | | 30% | Processing entities to import | | 40% | Validating entities | | 50% | Importing entities | | 70% | Linking and verifying relationships between entities | | 80% | Running integrity checks | | 90% | Finalizing import | | 100% | Import complete | The progress indicator shows the current percentage in the center of the spinner. If the import fails, the spinner displays **Import Failed** with an error message below it. :::hint{type="info"} You cannot cancel an import once it has started. Wait for the import to complete or fail before taking further action. ::: ## Review Import Results After the import completes, Turbine displays a results screen with up to three tabs. | Tab | Contents | | -------------------- | --------------------------------------------------------------------------------------------- | | **Take Action** | Actionable issues you can resolve inline. A yellow badge shows the count of remaining issues. | | **Take Note** | Non-actionable informational warnings. These do not prevent the solution from functioning. | | **Import Inventory** | A read-only tree of all entities that were imported. | ### Actionable vs. Non-Actionable Issues | Category | Description | Examples | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | **Actionable** (Take Action tab) | Issues that require your action for the solution to be fully functional. Resolving them inline marks them as complete. | A secure credential was removed; a key store reference was stripped; an asset configuration needs updating. | | **Non-actionable** (Take Note tab) | Informational warnings you should be aware of but that do not require immediate action. | A playbook was disabled during export; a webhook URL was modified. | Each actionable issue shows the affected entity name, the issue description, and a control to resolve it (for example, reconfigure a credential or enable a disabled task). After you resolve an issue, it is marked as complete and the count decreases. ### Post-Import Actions From the results screen footer, you can: | Button | Action | | --------------------- | ------------------------------------------------------------------------------- | | **Go to Application** | Opens the imported application in the builder so you can review and fix issues. | | **Go to Applet** | Opens the imported applet in the builder. | | **Import More** | Returns to the upload screen to import another SSP. | | **Close** | Closes the import dialog. | ### Copy or Download Import Notes From the results screen header, you can save a summary of all issues and warnings. - Click **Copy Notes** to copy the summary to your clipboard. - Click **Download Notes** to save it as a `.txt` file named `Swimlane Import Package.txt`. ## Enable Playbooks and Webhooks After Import Unless you used **Import playbooks/webhooks in enabled state**, playbooks and webhooks remain **disabled** after import. Enable them from the results banners or from Playbooks / webhook configuration before the solution is fully operational. Starting in **Turbine 26.4.0**, you can also replay skipped runs during import instead of only from Operational Health. ### Enable Playbooks After a successful import, if there are disabled playbooks, Turbine displays an info banner: :::BlockQuote *Some playbooks were disabled during export. Enable them all now or later.* ::: 1. Click **Enable N Playbooks** (where N is the count) to enable all disabled playbooks at once. 2. Alternatively, navigate to the **Playbooks** page and enable them individually. The **Include Scheduled Tasks** toggle controls whether scheduled-trigger playbooks are included in the bulk enable. Toggle it off to exclude scheduled playbooks from the bulk action. ### Enable Webhooks If there are disabled webhooks, a similar banner appears: :::BlockQuote *Some webhooks were disabled during export. Enable them all now or later.* ::: 1. Click **Enable N Webhooks** to enable all at once. 2. Alternatively, enable them individually from the webhook configuration. ### Enable Builder Playbooks If the SSP contains builder solutions with disabled builder playbooks, you can enable them in bulk from the import results screen. Turbine clears the "disabled" status and removes the associated informational messages. ## Reconfigure Credentials and Secure Values During export, the following are removed for security: | Item | Post-Import Action | | --------------------------------------- | ------------------------------------------------------ | | Secure credentials in assets | Open each asset and re-enter the credentials. | | Key store values mapped to task inputs | Open the application and add the key store references. | | Secure values in asset configurations | Open each asset and reconfigure the secure fields. | | Dynamic Orchestration asset credentials | Open each DO asset and re-enter credentials. | | Sensor credentials | Open each sensor and re-enter credentials. | | Webhook URLs | Verify and update webhook URLs if they have changed. | These items appear on the **Take Action** tab of the import results. Resolve each one to mark it as complete. ## Deploy from Content Library When importing from the Content Library (deploy flow), the experience is the same as a standard import with the following differences: | Difference | Standard Import | Content Library Deploy | | ------------------- | ---------------------------- | ----------------------------------------------------------------------- | | Terminology | "Import," "Importing" | "Deploy," "Deploying" | | Dialog title | "Import" or "Package Import" | "Deploy Package" or entity-specific (for example, "Deploying Playbook") | | Inventory tab label | "Import Inventory" | "Deployed Inventory" | | Import More button | "Import More" | "Deploy More" (if applicable) | All other functionality (entity selection, overwrite handling, progress tracking, and result review) is identical. The **Import playbooks/webhooks in enabled state** toggle and **Retry skipped events?** confirmation also apply to Content Library **deploy**. Package **try** / dry-run does not enable content or replay skipped runs. ## Version History and Revert When working with Content Library content, the import dialog includes additional tabs for managing versions. ### View Version History 1. Open the content from the Content Library. 2. Select the **Version History** tab. 3. Review the table showing each version with its **version number**, **last modified** timestamp, and **commit message**. ### Revert to a Previous Version If a newer version introduces issues, you can revert to a previous version. 1. In the **Version History** tab, click **Revert**. 2. Select the version you want to revert to by clicking its radio button. 3. Enter a **new version number** for the reverted content. The version must be valid and unique. 4. Enter a **reason for reverting** in the commit message field. 5. Click **Revert** to confirm. On success, Turbine displays a confirmation: :::BlockQuote *\[Package name] has been successfully reverted in your Library.* ::: :::hint{type="info"} After reverting in the Content Library, the version in tenant environments may be out of sync. **Redeploy** the reverted content to each tenant to apply the change. ::: If the revert fails, Turbine displays an error message. Wait a few minutes and try again. If the error persists, contact support. ## Troubleshooting | Issue | Cause | Resolution | | --------------------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Import fails with "Incompatible Swimlane version" | The SSP was exported from a newer Turbine version. | Upgrade the target Turbine instance. | | Import fails with "Plugin upgrade required" | The target system has an older version of a required plugin. | Upgrade the plugin from the notification, then click **Continue**. | | Import fails with "Plugin downgrade required" | The target system has a newer plugin version than the SSP expects. | Re-export the SSP from a system with the matching plugin version. | | Import fails with "Dynamic Orchestration feature flag required" | The SSP uses Dynamic Orchestration but the flag is not enabled. | Enable the Dynamic Orchestration feature flag, then retry. | | Import fails with "Python version" error | The SSP requires a different Python version. | Verify the Python runtime version on the target system. | | "Could not load file in package" | A file is missing or corrupted in the SSP. | Re-export the SSP from the source system, or see [Repackage an Unzipped SSP File](docId\:yEVfL9bCUyPqFmOZwRZfT). | | Playbooks not running after import | Playbooks are disabled during export by default. | Enable playbooks from the import results screen, or use the **Import playbooks/webhooks in enabled state** toggle during entity selection (optionally replay skipped runs). | | "No connector matching the provided name exists" | A referenced connector is not installed on the target system. | Install the connector from the Marketplace before retrying. | | "Solution not working as intended" after partial import | Some dependent entities were not imported. | Re-import the SSP with all entities selected. | | Import stalls at a percentage | A network or server issue interrupted the process. | Wait for the import to time out, then retry. If the issue persists, check server logs. |