Export

This class defines an export job. Exports are user-bound (see /api/export).

An export defines:

• which data to export:
  • the data to export is based on a search, which is executed under the rights of the user (search)
  • it is possible to configure export options field by field (fields)
  • the assets to export are provided by field name (eas_fields)
  • if given, the preferred asset version is exported (unless stated otherwise in assets)
  • with each asset exported, a relative path is included in the CSV or XML export files
  • it is possible to configure export options by file class (classes) or even for specific assets (assets)
  • by default, linked objects are only exported with IDs, the version and the _standard field in XML exports. To load linked objects and include the content in the export, use merge_linked_objects
• how to map and present the data:
  • the data can be provided as CSV (csv) and/or XML (xml, xml_one_file_per_object)
  • it is possible to specify a specific mapping profile (mapping)
• when it should be launched
  • the export can be scheduled to run periodically using schedules (_schedules)
  • if no schedules are set, the export is launched immediately
• the transport mechanisms used to transport the export data (_transports)
  • if no transports are defined, the export is only available for download

The export is also used to track the job’s progress:

• the attribute _state is used to know the current state of an export/transport

Finally, the export also provides information about the generated files and downloads:

• a list of generated files (_files) is provided, including their relative paths and sizes
• a list of available downloads (_downloads) is provided, including the URLs used to download the export

Detailed information

Exports are stored on the server in their separate directories. Exports can contain folders and files, depending on the export definition. Exports are transported by the user using transport definitions.

After each sucessful Export an event is created (/api/event).

Lifecycle

The Export lifecycle looks as follows:

1. Inform frontends using /api/event about the starting Export
2. Log in the User of the Export, use the rights of that User
3. Create a unique Export directory, in case of an update, wipe the existing one
4. Execute the search of the Export
5. Collect all Objects and the corresponding files (Assets)
6. Copy all files into the Export filestructure
7. Link files to the Object Information (relative local URLs to the exported files)
8. Write XML and CSV files to the Export directory
9. Start all defined transports to send emails and copy files
10. Inform frontends using /api/event about the finished Export

Attributes

* Fields are provided in the ES format (the one used by /api/search)

Field Export Attributes

The field export attributes is a JSON object with the following optional arguments.

EAS Field Export Attributes

The field export attributes is a JSON object with the following optional arguments. Some of them are only meaningful for certain EAS fields:

type “version”

Asset Export Attributes

Version Export Attributes

The version export attributes is a JSON object with the following optional arguments. Some of them are only meaningful for certain asset classes:

type “version”

type “custom”

Field Export Attributes

Array of version export attributes: version attributes for the asset.

CSV Export Attributes

The CSV Export always includes a header with the field names. Values can include Newlines.

Export of hierarchical linked objects

If hierarchical objects are exported, there are multiple options to export the path in the CSV file:

• hierarchy is null (not set):

  • ignore that the object is hierarchic
  • don’t export the path at all, only export the standard of the exported object (default)

• hierarchy is any of the following strings:

  • ">" or "/"

    • the standards of each element of the path are rendered into one column (from root to exported object)
    • the concatenated elements are separated by " > " or " / " respectively

  • "column"

    • the standards of each element of the path are rendered into a column each (from root to exported object)
    • for each part of the path to the object, there is a new column for each element of the path
    • the columns are numbered with suffixes from #0 (root) to #n (exported object)

This rule applies for top level objects as well as for linked objects.

Transport Export Attributes

A Transport is used to send exports after they are finished.

Ad-hoc users are provided as in /api/collection.

Transport type “download”

This type of transport has no attributes, a list of downloads will be available in the read-only attribute _download.

Transport type “rsync”

RSYNC can be used to copy files away from the Export directory to a backup directory or a remote server using the SSH, RSH, or RSYNC as transport protocol.

File

For each file, the following attributes are provided:

Download

For each download, the following attributes are provided:

The url is persistent for the lifetime of the export’s transport. So that after a scheduled update of the export, the URL does not change.

State

These values are always possible for _state:

Related operations

• /export: CRUD operations on exports

Example

{
	"classes": {
		"image": {
			"version": "current+original"
		},
		"office": {
			"version": "current"
		}
	},
	"eas_fields": [
		"bilder.datei",
		"bilder.rueckseite",
		"bilder._nested:bilder__documents.file"
	],
	"assets": {
		"1000127337": true,
		"1000130848": {
			"version": "custom",
			"format": "tiff",
			"size": "custom",
			"custom_size": "height",
			"custom_size_pixel": "123",
			"watermark": true
		},
		"1000130849": false,
		"1000130851": true
	},
	"csv": {
		"delimiter": ";",
		"quote": "\"",
		"escape": "\"",
		"empty_columns": false,
		"all_languages": false,
		"hierarchy": ">"
	},
	"merge_linked_objects": "not_in_main_search",
	"merge_max_depth": "3",
	"xml": true,
	"xml_one_file_per_object": true,
	"search": {
		"search": [
			{
				"bool": "must",
				"type": "in",
				"fields": [
					"bar._pool.pool._id",
					"Test._pool.pool._id",
					"video._pool.pool._id",
					"bilder._pool.pool._id"
				],
				"in": [
					1,
					2,
					35,
					37,
					38
				]
			}
		],
		"sort": []
	},
	"fields": {
		"video.videodatei": {
			"watermark": true,
			"display_name": "videodatei",
			"versions": [
				"huge"
			]
		},
		"bilder.standort.Standort._objecttype": {
			"display_name": "_objecttype"
		},
		"bilder.standort.Standort._id": {
			"display_name": "_id"
		},
		"bilder.standort.Standort.version": {
			"display_name": "version"
		},
		"bilder.standort.Standort._changelog": {
			"display_name": "_changelog"
		},
		"bilder.standort.Standort._standard": {
			"display_name": "_standard"
		},
		"bilder.standort.Standort.ort": {
			"display_name": "ort"
		},
		"bilder.standort.Standort.synonyme": {
			"display_name": "synonyme"
		},
		"bilder.standort": {
			"display_name": "standort"
		}
	}
}

Note: state has been implemented as _state directly in export and transport.