diff --git a/docs/docs/docs/01-core/data-transfer/00-intro.md b/docs/docs/docs/01-core/data-transfer/00-intro.md index cb802ee69d..019f31cd40 100644 --- a/docs/docs/docs/01-core/data-transfer/00-intro.md +++ b/docs/docs/docs/01-core/data-transfer/00-intro.md @@ -1,6 +1,5 @@ --- title: Introduction -slug: /data-transfer tags: - data-transfer - experimental diff --git a/docs/docs/docs/01-core/data-transfer/01-engine.md b/docs/docs/docs/01-core/data-transfer/01-engine.md index 3a3f1f9293..ff389ca80f 100644 --- a/docs/docs/docs/01-core/data-transfer/01-engine.md +++ b/docs/docs/docs/01-core/data-transfer/01-engine.md @@ -12,12 +12,91 @@ The transfer engine manages the data transfer process by facilitating communicat `packages/core/data-transfer/src/engine/index.ts` -## Setting up a transfer +## Setting up the transfer engine -### Excluding data +A transfer engine object is created by using `createTransferEngine`, which accepts a [source provider](./source-providers/overview), a [destination provider](./destination-providers/overview), and an options object. + +Note: By default, a transfer engine will transfer ALL data, including admin data, api tokens, etc. Transform filters must be used if you wish to exclude, as seen in the example below. An array called `DEFAULT_IGNORED_CONTENT_TYPES` is available from @strapi/data-transfer containing the uids that are excluded by default from the import, export, and transfer commands. If you intend to transfer admin data, be aware that this behavior will likely change in the future to automatically exclude the entire `admin::` uid namespace and will instead require them to be explicitly included. + +```typescript +const engine = createTransferEngine(source, destination, options); +``` + +### Engine Options + +An example of every option: + +```typescript +const options = { + versionStrategy: 'ignore', // see versionStragy documentation + schemaStrategy: 'strict', // see schemaStragey documentation + exclude: [], // exclude these classifications of data; see CLI documentation of `--exclude` for list + only: [], // transfer only these classifications of data; see CLI documentation of `--only` for list + throttle: 0, // add a delay of this many millseconds between each item transferred + transforms: { + links: [ + { + // exclude all relations to ignored content types + filter(link) { + return ( + !DEFAULT_IGNORED_CONTENT_TYPES.includes(link.left.type) && + !DEFAULT_IGNORED_CONTENT_TYPES.includes(link.right.type) + ); + }, + }, + ], + entities: [ + { + // exclude all ignored content types + filter(entity) { + return !DEFAULT_IGNORED_CONTENT_TYPES.includes(entity.type); + }, + }, + ], + }, +}; +``` + +#### versionStrategy + +**TODO** + +#### schemaStrategy + +**TODO** + +### Handling Schema differences + +The transfer engine allows you to add listeners for managing differences in schema between the source and destination using `engine.onSchemaDiff(handler)` + +**TODO** + +### Progress Tracking events + +The transfer engine allows you to add event listeners to track the progress of your transfer. + +```typescript +engine.progress.stream; +``` + +### Diagnostics events + +`engine.diagnostics.onDiagnostic(formatDiagnostic('export'));` + +**TODO** ### Transforms +Transforms allow you to manipulate the data that is sent from the source before it reaches the destination. + +## Filters (excluding data) + +**TODO** + +## Map (modifying data) + +**TODO** + ## Running a transfer Note: The transfer engine (and the providers) current only support a single `engine.transfer()` and must be re-instantiated if intended to run multiple times. In the future it is expected to allow them to be used for multiple transfers in a row, but that usage is untested and will result in unpredictable behavior. diff --git a/docs/docs/docs/01-core/data-transfer/01-source-providers/00-overview.md b/docs/docs/docs/01-core/data-transfer/01-source-providers/00-overview.md index d9e123a679..9c0f1c7931 100644 --- a/docs/docs/docs/01-core/data-transfer/01-source-providers/00-overview.md +++ b/docs/docs/docs/01-core/data-transfer/01-source-providers/00-overview.md @@ -1,12 +1,11 @@ --- title: Source Providers -slug: /source-providers tags: - providers - data-transfer - experimental --- -# Destination Providers +# Source Providers TODO diff --git a/docs/docs/docs/01-core/data-transfer/01-source-providers/01-strapi-file.md b/docs/docs/docs/01-core/data-transfer/01-source-providers/01-strapi-file.md index 0f44fbd8d6..a8f1e5a00c 100644 --- a/docs/docs/docs/01-core/data-transfer/01-source-providers/01-strapi-file.md +++ b/docs/docs/docs/01-core/data-transfer/01-source-providers/01-strapi-file.md @@ -1,6 +1,5 @@ --- title: Strapi File -slug: /source-providers/strapi-file tags: - providers - data-transfer diff --git a/docs/docs/docs/01-core/data-transfer/01-source-providers/02-local-strapi copy.md b/docs/docs/docs/01-core/data-transfer/01-source-providers/02-local-strapi copy.md index 151db7915d..faa25ae060 100644 --- a/docs/docs/docs/01-core/data-transfer/01-source-providers/02-local-strapi copy.md +++ b/docs/docs/docs/01-core/data-transfer/01-source-providers/02-local-strapi copy.md @@ -1,6 +1,5 @@ --- title: Local Strapi -slug: /source-providers/local-strapi tags: - providers - data-transfer diff --git a/docs/docs/docs/01-core/data-transfer/01-source-providers/03-remote-strapi.md b/docs/docs/docs/01-core/data-transfer/01-source-providers/03-remote-strapi.md index f9df93946c..785289ad36 100644 --- a/docs/docs/docs/01-core/data-transfer/01-source-providers/03-remote-strapi.md +++ b/docs/docs/docs/01-core/data-transfer/01-source-providers/03-remote-strapi.md @@ -1,6 +1,5 @@ --- title: Remote Strapi -slug: /source-providers/remote-strapi tags: - providers - data-transfer diff --git a/docs/docs/docs/01-core/data-transfer/02-destination-providers/00-overview.md b/docs/docs/docs/01-core/data-transfer/02-destination-providers/00-overview.md index d62daa57c6..595141734b 100644 --- a/docs/docs/docs/01-core/data-transfer/02-destination-providers/00-overview.md +++ b/docs/docs/docs/01-core/data-transfer/02-destination-providers/00-overview.md @@ -1,6 +1,5 @@ --- title: Destination Providers -slug: /destination-providers tags: - providers - data-transfer diff --git a/docs/docs/docs/01-core/data-transfer/02-destination-providers/01-strapi-file.md b/docs/docs/docs/01-core/data-transfer/02-destination-providers/01-strapi-file.md index 05a8071133..18d9e23085 100644 --- a/docs/docs/docs/01-core/data-transfer/02-destination-providers/01-strapi-file.md +++ b/docs/docs/docs/01-core/data-transfer/02-destination-providers/01-strapi-file.md @@ -1,6 +1,5 @@ --- -title: Strapi File -slug: /destination-providers/strapi-file +title: Strapi File= tags: - providers - data-transfer diff --git a/docs/docs/docs/01-core/data-transfer/02-destination-providers/02-local-strapi copy.md b/docs/docs/docs/01-core/data-transfer/02-destination-providers/02-local-strapi copy.md index 4ac7cdbd19..fa7ffb9a45 100644 --- a/docs/docs/docs/01-core/data-transfer/02-destination-providers/02-local-strapi copy.md +++ b/docs/docs/docs/01-core/data-transfer/02-destination-providers/02-local-strapi copy.md @@ -1,6 +1,5 @@ --- -title: Local Strapi -slug: /destination-providers/local-strapi +title: Local Strapi= tags: - providers - data-transfer diff --git a/docs/docs/docs/01-core/data-transfer/02-destination-providers/03-remote-strapi.md b/docs/docs/docs/01-core/data-transfer/02-destination-providers/03-remote-strapi.md index 2407924a78..0e4a4b0cc5 100644 --- a/docs/docs/docs/01-core/data-transfer/02-destination-providers/03-remote-strapi.md +++ b/docs/docs/docs/01-core/data-transfer/02-destination-providers/03-remote-strapi.md @@ -1,6 +1,5 @@ --- -title: Remote Strapi -slug: /destination-providers/remote-strapi +title: Remote Strapi= tags: - providers - data-transfer