---
title: Repackage an Unzipped SSP File
slug: repackage-an-unzipped-ssp-file
docTags: 
createdAt: 2025-08-11T11:13:48.000Z
---

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

:::hint{type="warning"}
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.

:::hint{type="warning"}
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

1. Open a terminal and navigate into the SSP content directory — the folder that contains `manifest.json` and the entity directories.
2. Verify that you are in the correct directory:

```bash
ls manifest.json
```

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

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

4. Rename the `.zip` file to `.ssp`:

```bash
mv filename.zip filename.ssp
```

:::hint{type="warning"}
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.
:::

:::hint{type="info"}
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.

1. List the archive contents:

```bash
unzip -l filename.ssp
```

2. 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:

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

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

```javascript
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`.                                  |