Repackage an Unzipped SSP File

Repackage a Swimlane Solution Package (SSP) after unzipping and editing it so that it imports correctly into Turbine.

Swimlane recommends working with a support representative before editing SSP files manually. Incorrect edits can cause import failures that are difficult to diagnose.

At a Glance

Step	Action
1	Unzip the .ssp file.
2	Edit the entity files as needed.
3	Recompress using the CLI zip command (not OS-level compression).
4	Rename the .zip to .ssp.
5	Verify the archive structure before importing.

What Is Inside an SSP

An SSP is a standard zip archive with the .ssp extension. When you unzip it, you will see:

manifest.json — Package metadata (name, version, description). Located at the root of the archive.

Entity directories — Folders such as Application, Playbook, Workflow, Workspace, Report, Dashboard, Sensor, Connector, and others. Each folder contains one or more .json files representing individual entities.

Meta directory — Internal mapping files that Turbine uses to link entities together during import.

Do not rename, delete, or modify files in the Meta directory. These files are critical for a successful import. If they are missing or corrupted, the import will fail.

Guidelines for Editing

Edit only entity .json files in the entity directories (such as Application, Workflow, and so on). Change only the specific fields you need to update.

Do not rename files. File names are linked to internal mappings.

Do not leave files empty. An empty file causes an import error.

Do not add or remove files unless you also understand how to update the internal mappings in the Meta directory.

Validate your JSON. Malformed JSON causes a "could not load file" error during import.

Repackage the SSP

Open a terminal and navigate into the SSP content directory — the folder that contains manifest.json and the entity directories.

Verify that you are in the correct directory:

ls manifest.json

Compress the contents back into a .zip file using the CLI:

zip -r filename.zip . -x "*/\.*"

Rename the .zip file to .ssp:

mv filename.zip filename.ssp

Use the CLI zip command as shown above. Do not use your operating system's built-in compression (for example, right-click and compress on macOS or Windows). OS-level tools often create a wrapper directory inside the archive, which causes a "Couldn't find mapping in the package" error on import.

The -x "*/\.*" flag excludes hidden files (such as .DS_Store on macOS) that can interfere with import.

Verify Before Import

After repackaging, verify the structure is correct.

List the archive contents:

unzip -l filename.ssp

Confirm that manifest.json and the entity directories appear at the root level of the archive — not inside a subdirectory.

Correct — files are at the root:

manifest.json
Application/abc123.json
Meta/IdMapping.json
Workflow/def456.json

Incorrect — files are nested in a wrapper directory (will fail on import):

my-package/manifest.json
my-package/Application/abc123.json
my-package/Meta/IdMapping.json

If the structure is incorrect, delete the .ssp file, navigate into the content directory, and repeat the zip command from step 3.

Common Errors

Error on Import	Likely Cause	Fix
"Couldn't find mapping in the package"	The archive has a wrapper directory, or the Meta directory is missing.	Re-zip from inside the content directory so files are at the root.
"Could not load file in package"	An entity JSON file is malformed or empty.	Validate JSON syntax in all edited files.
"Swimlane solution package required"	The file does not have a .ssp extension.	Rename the file to end in .ssp.