Strapi Plugin Import Export Entries

When importing media, the plugin supports several formats to identify or create files:

1. By ID (number or object with id): Searches the database for the existing media ID.
2. By Hash or Name (object with hash or name): Searches the database for a match.
3. By URL (object with url or string): If no match is found by ID, hash, or name, the plugin downloads the file from the provided URL.
   • Note: The server must have access to the URL.
   • The hash and name are deduced from the URL.
   • You can provide extra metadata like caption or alternativeText when importing via URL.

Example Media Objects:

• { id: 1 } (By ID)
• { hash: "alpaga.jpg" } (By Hash)
• { url: "https://example.com/image.jpg" } (By URL)
• { id: 734, url: "http://localhost:1337/alpaga.jpg", name: "Alpacool", caption: "Alpacool In Da Hood" } (Full metadata)

The behavior of relations during import depends on the data type provided:

• object: The relation is searched in the database by id. If an entry is found, it is updated with the provided data; otherwise, a new entry is created.
• number: The relation is treated strictly as an ID.
• JSON v2 Note: In the JSON v2 format, relations should be specified by their ids within the flattened structure.

JSON v2 is the recommended structure for imports. It uses a flattened format where dependencies rely solely on ids (objects are not supported in this version). Collection types, single types, media, and components are all treated uniformly under the data key.

Requirements:

• A top-level version key set to 2 is required.
• The data object contains keys corresponding to the model UID (e.g., api::collection-name.collection-name or plugin::upload.file).
• Inside each model key, sub-keys are the ids of the entries, and values contain the entry data.

{
  "version": 2,
  "data": {
    "api::collection-name.collection-name": {
      "1": {
        "id": 1
      },
      "2": {
        "id": 2
      }
    },
    "plugin::upload.file": {
      "1": {
        "id": 1
      }
    }
  }
}

New releases may include changes to the administration panel that require a rebuild. Use the --clean flag to ensure a fresh build.

# Using yarn
yarn build --clean

# Or using npm
npm run build --clean

After installation, enable the plugin by adding it to your config/plugins.js file.

module.exports = ({ env }) => ({
  //...
  'import-export-entries': {
    enabled: true,
    config: {
      // See `Config` section.
    },
  },
  //...
});

Install the plugin using your preferred package manager and then enable it in your Strapi configuration.

Requirements:

• Strapi v4 is required.

# Using yarn
yarn add strapi-plugin-import-export-entries

# Or using npm
npm i strapi-plugin-import-export-entries

You can configure global plugin settings in config/plugins.js.

One available option is serverPublicHostname. If you are using a local provider to persist media, set this to your server's public URL to ensure media URLs are exported correctly.

module.exports = ({ env }) => ({
  //...
  'import-export-entries': {
    enabled: true,
    config: {
      /**
       * Public hostname of the server.
       * If you use the local provider to persist medias,
       * `serverPublicHostname` should be set to properly export media urls.
       */
      serverPublicHostname: 'https://yoga.com', // default: "".
    },
  },
  //...
});

When importing data, the plugin needs to know which field to use to identify existing entries (to decide whether to update or create). By default, this is the id attribute.

However, when transferring data between different databases, id values often change. To use a different unique attribute (like name or email) as the identifier, add idField to the pluginOptions in your collection's schema.json.

{
  "collectionName": "hospitals",
  "info": {
    "displayName": "Hospital",
  },
  "pluginOptions": {
    "import-export-entries": {
      "idField": "name"
    }
  },
  "attributes": {
    "name": {
      "type": "string",
      "unique": true
    },
    // ... other attributes
  }
}

The plugin automatically injects several components into the Strapi Content Manager to facilitate data operations:

List View (Collection Types)

• Alerts: Displayed in the actions area.
• ImportButton: Provides import functionality in the actions area.
• InjectedExportCollectionType: Provides export functionality for entire collections in the actions area.

Edit View (Single Types/Entries)

• Alerts: Displayed in the right-links area.
• InjectedImportExportSingleType: Provides import/export capabilities for a specific entry in the right-links area.

The plugin integrates with the Strapi Admin panel through three main lifecycle methods: register, bootstrap, and registerTrads.

1. register(app): Adds a dedicated 'Import Export' menu link to the Strapi sidebar and registers the plugin's core initializer.
2. bootstrap(app): Injects UI components into the Content Manager. It adds buttons and alerts to both the List View (for collection types) and the Edit View (for single types).
3. registerTrads({ locales }): Loads and prefixes plugin-specific translations for the supported locales.

This integration ensures that import/export capabilities are available directly within the standard Strapi content management workflows.

The version 2 import format is structured by SchemaUID. The root object contains a version key and a data object. The data object maps each SchemaUID to its corresponding entries, where entries are keyed by a unique FileId (string or number).

Schema Structure:

• version: Must be 2.
• data: An object where keys are SchemaUID (e.g., api::article.article) and values are SlugEntries.
• SlugEntries: A record where keys are FileId and values are FileEntry objects containing the actual attribute data.

{
  "version": 2,
  "data": {
    "api::article.article": {
      "file-id-1": {
        "title": "My Article",
        "content": "..."
      }
    },
    "plugin::upload.file": {
      "media-id-1": {
        "name": "image.png",
        "url": "/uploads/image.png"
      }
    }
  }
}

If you are importing large files that exceed the default server limits, you must increase the jsonLimit in the Strapi strapi::body middleware within config/middlewares.js.

// ./config/middlewares.js

module.exports = {
  // ...
  {
    name: 'strapi::body',
    config: {
      jsonLimit: '10mb',
    },
  },
  // ...
}