Data Export

You can export data using either the CLI or the raw export API. This can be useful when test data is needed for a service, e.g. in a staging environment.

Data export to CSV with the CLI

platformOS CLI provides the pos-cli data export --zip command. Options:

• --path (short: -p): A file path to a JSON file which will be created by the CLI and where the exported data is stored.
• --export-internal-ids: By default, export will use the autogenerated external_id for the id field. When this option is set, it will use the normal id from the object.

Under the hood, the CLI uses the export API that's described in the next section. However, using the CLI provides some major benefits:

• Leveraging the CLI's authentication mechanism (i.e. you don't need to manually send your authentication token)
• Writing downloaded data directly to the file system

Example:

pos-cli data export --zip --path=data.zip production

Data export with GraphQL

It is possible to export data with GraphQL. It's a two step process.

Step 1: Trigger data export via GraphQL Mutation

The following GraphQL mutation will create a built-in Background Job that will generate the zip file with the data asynchrounously. The most important field that will be returned by this mutation is the id, as it will be necessary to fetch the URL to the zip file once it's created:

mutation create_data_export(
  $records_filter: DataExportRecordsInput
  $users_filter: DataExportUsersInput
) {
  record: data_export(
    records: $records_filter
    users: $users_filter
  ) {
    id
    created_at
    updated_at
    status
    url
  }
}

Please note that you can specify the filters, that will be taken into consideration and only data matching the filters will be included in the CSV files.

Encrypting data using GPG

It is a security standard to encrypt data at rest. To encrypt the content of each CSV file with your GPG, you can use the encryption argument. To store your public GPG key, we recommend using the constants feature.

mutation create_data_export(
  $records_filter: DataExportRecordsInput
  $users_filter: DataExportUsersInput
  $key: GPGKey!
) {
  record: data_export(
    records: $records_filter
    users: $users_filter
    encryption: { gpg: { key: $key } }
  ) {
    id
    created_at
    updated_at
    status
    url
  }
}

Step 2: Get the URL to the zip file with the data

After some time, depending on the amount of the data, the following GraphQL query will return the secure URL to download the zip file. Please note that you must provide the id of the DataExport, returned by data_export mutation.

query get_data_export(
  $id: ID!
) {
  records: data_exports(
    per_page: 1
    page: 1
    filter: {
      id: { value: $id }
    }
  ) {
    results{
      created_at
      updated_at
      id
      status
      url
    }
  }
}

The returned data.zip file is compatible with the Import Data using CSV. In fact, Instance Copy feature in Partner Portal behind the scenes relies on this functionality - it exports the data from the source instance and imports it to the destination instance.

Exporting files

Currently, the user cannot manually request exporting all of the files uploaded to the instance, due to the potential size. However, Instance Copy feature in Partner Portal does copy user uploaded files as well. If you need to download all of the files from platformOS, submit the request to our support.