Transformations API

You can use the Transformations API to set up file format transformations, such as converting Word files to PDF/A. A transformation configuration tells the archive which file formats to convert, how, and into what kind of representation.

Every call needs the headers in Common headers.

How a transformation runs

Your transformation configurations decide what the archive converts. Transformations run as part of the formatPreservation preservation action, after the archive has identified the file formats. For each representation of the package, the archive:

1. Checks the file format of the representation's first file.

2. Finds the enabled transformation configurations that have this format in sourceFormats, and that apply to the package's archive profile.

3. Converts the representation's files with the configuration's engine, and adds the result to the package as another representation of the type in targetType.

The new representation has the original name, with the targetExtension as its extension. If the package already has a representation with that name, the archive skips the conversion.

To run the transformations on packages that are already in the archive, run formatPreservation with the Preservation actions API.

List file formats

Returns the file formats that the archive knows. Use the puid values in sourceFormats.

GET /v2/transformations/formats

Required role: archive-content-manager

Response: 200 OK with an array of FileFormat. The list isn't split into pages.

curl "https://archive.example.com/v2/transformations/formats?filter=word" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant: example-tenant"

[
  {
    "puid": "fmt/40",
    "name": "Microsoft Word Document",
    "version": "97-2003",
    "mimeType": "application/msword",
    "extensions": ["doc"]
  }
]

List transformation configurations

GET /v2/transformations/configs

Required role: archive-content-manager

Response: 200 OK with a TransformationConfigList, sorted by name.

Get a transformation configuration

GET /v2/transformations/configs/{configId}

Required role: archive-content-manager

Response: 200 OK with a TransformationConfig.

• 404: there's no transformation configuration with this ID.

Create a transformation configuration

Sets up a transformation. The archive uses it the next time it runs formatPreservation on a package.

POST /v2/transformations/configs

Required role: archive-content-manager

{
  "name": "Word to PDF/A",
  "sourceFormats": ["fmt/40", "fmt/412"],
  "targetFormat": "PDF/A-1b",
  "targetExtension": "pdf",
  "targetType": "preservation",
  "transformation": {
    "engine": "word2pdf"
  },
  "enabled": true
}

Response: 200 OK with the TransformationConfig.

• 400 with UNSUPPORTED_VALUE: targetType isn't one of the allowed types.

• 400 with REQUIRED_FIELD: a required field is missing.

Update a transformation configuration

Replaces the configuration with the body that you send. The body has the same fields as Create a transformation configuration, so send all of them.

PUT /v2/transformations/configs/{configId}

Required role: archive-content-manager

Response: 200 OK with the updated TransformationConfig. The change applies to the next runs. Representations that the archive already created stay as they are.

• 404: there's no transformation configuration with this ID.

• The 400 errors of Create a transformation configuration.

Delete a transformation configuration

DELETE /v2/transformations/configs/{configId}

Required role: archive-content-manager

Response: 204 No Content. Representations that the configuration already created stay in their packages.

• 404: there's no transformation configuration with this ID.

Schemas

TransformationEngine

The engine values are:

• word2pdf: Word to PDF/A-1b.

• dwg2pdfa: DWG drawings to PDF/A-1b.

• tiff2jpeg: TIFF to JPEG.

• conversion: the general conversion engine.

TransformationConfig

TransformationConfigList

FileFormat