inteligr8/alfresco-transform-core
1
0
Fork 0
mirror of https://github.com/Alfresco/alfresco-transform-core.git synced 2025-08-14 17:58:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

Save point: [skip ci]

Browse Source 
* docs
This commit is contained in:
alandavis
2022-07-20 13:35:35 +01:00
parent 929b69384b
commit 6692946fb5
5 changed files with 30 additions and 260 deletions
Download Patch File Download Diff File Expand all files Collapse all files

224
docs/alfresco-transformer.yaml
View File

@@ -1,224 +0,0 @@
swagger: '2.0'
info:
description: |
**Alfresco Transform Engines REST API**
Transform Request & Response API to allow a source file to be transformed into a
target file, given a set of transform options.
The new JSON-based Transform Engines API is used by the Alfresco Transform Service (ATS).
ATS provides an independently-scalable transform service, initially used by ACS
Content Repository, as part of the overall Alfresco Digital Business Platform (DBP).
Note: Each kind of Transform Engine implements this Transform Engines API, including:
* ImageMagick
* LibreOffice
* PDF Renderer
* Tika
In the future, this Transform Engines API may form the basis for adding custom Transform Engines.
version: '1'
title: Alfresco Transform Engines REST API
basePath: /alfresco/api/-default-/private/transformer/versions/1
tags:
- name: Transform
description: Transform Engine Request / Respone
paths:
'/transform':
post:
x-alfresco-since: "2.0"
tags:
- Transform
summary: Transform Engines API
description: |
**Note:** available with Alfresco Transform Engines 2.0 and newer versions.
This endpoint supports both JSON and Multipart. The JSON API is used within the
Alfresco Transform Service (eg. ACS 6.1). The Multipart API remains for backwards
compatibility (eg. ACS 6.0).
**Using JSON (application/json -> application/json)**
The ACS Content Repository 6.1 (or higher) provides the option to offload
supported transformations to the Alfresco Transform Service.
The JSON API is used within the Alfresco Transform Service. It relies on the
source and target files being stored and retrieved via the Alfresco Shared File
Store (see also [alfresco-sfs.yaml](https://github.com/Alfresco/alfresco-shared-file-store/blob/master/docs/api-definitions/alfresco-sfs.yaml)).
Here's a pseudo-example transform request:
```JSON
{
"schema": 1,
"requestId": "0aead31c-e3ca-42c9-8e16-c1938ff64c3a",
"clientData": "opaque-client-specific-data-123xyz",
"sourceReference": "598387b8-d85d-4557-816e-50f44c969e04",
"sourceSize": 32713,
"sourceMediaType: "image/jpeg",
"sourceExtension": "jpeg",
"targetMediaType: "image/png",
"targetExtension": "png",
"transformRequestOptions": {
"resizeWidth": "25",
"resizePercentage": "true",
"maintainAspectRatio": "true"
}
}
```
Here's a pseudo-example response of a successful transform:
```JSON
{
"schema": 1,
"status": 201
"requestId": "0aead31c-e3ca-42c9-8e16-c1938ff64c3a",
"clientData": "opaque-client-specific-data-123xyz",
"sourceReference": "598387b8-d85d-4557-816e-50f44c969e04",
"targetReference": "5bc81e48-e17a-4727-bd1c-3a279aa6b421"
}
```
Here's a pseudo-example response of a failed transform:
```JSON
{
"schema": 1,
"status": 400,
"errorDetails": "Lorem ipsum dolor sit amet, ..."
"requestId": "0aead31c-e3ca-42c9-8e16-c1938ff64c3a",
"clientData": "opaque-client-specific-data-123xyz",
"sourceReference": "598387b8-d85d-4557-816e-50f44c969e04"
}
```
**Using Multipart (multipart/form-data -> application/octet-stream)**
The Multipart API remains for backwards compatibility (eg. ACS 6.0). It requires
the source file to be uploaded via multipart/form-data (along with transformation
options). The target file is returned as a binary response (application/octet-steam).
operationId: transformOperation
parameters:
- in: body
name: transformRequest
description: The Transform Request including source reference and transform options
required: true
schema:
$ref: '#/definitions/transformRequest'
consumes:
- application/json
- multipart/form-data
produces:
- application/json
- application/octet-stream
responses:
'201':
description: Successful response
schema:
$ref: '#/definitions/transformReply'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
'/transformer/options':
get:
tags:
- Transform
description: List transform options
operationId: transformOptions
produces:
- application/json
responses:
200:
description: Successful response
schema:
type: array
xml:
name: transformOptions
wrapped: true
items:
$ref: '#/definitions/transformOption'
definitions:
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- statusCode
- briefSummary
- stackTrace
- descriptionURL
properties:
errorKey:
type: string
statusCode:
type: integer
format: int32
briefSummary:
type: string
stackTrace:
type: string
descriptionURL:
type: string
logId:
type: string
transformRequest:
type: object
properties:
requestId:
type: string
sourceReference:
type: string
sourceMediaType:
type: string
sourceSize:
type: integer
format: int64
sourceExtension:
type: string
targetMediaType:
type: string
targetExtension:
type: string
clientData:
type: string
schema:
type: integer
transformRequestOptions:
type: object
additionalProperties:
type: string
transformReply:
type: object
properties:
status:
type: integer
requestId:
type: string
sourceReference:
type: string
targetReference:
type: string
clientData:
type: string
schema:
type: integer
errorDetails:
type: string
transformOption:
type: object
required:
- required
- name
properties:
required:
type: boolean
name:
type: string

25
docs/engine_config.md
View File

@@ -1,16 +1,16 @@
## T-Engine configuration
T-Engines provide a */transform/config* end point for clients (e.g. Transform-Router or
Alfresco-Repository) that indicate what is supported. T-Engines store this
Repository) that indicate what is supported. T-Engines store this
configuration as a JSON resource file named *engine_config.json*.
The config can be found under `alfresco-transform-core\<t-engine-name>\src\main\resources
\engine_config.json`; current configuration files are:
* [Pdf-Renderer T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/alfresco-docker-alfresco-pdf-renderer/src/main/resources/engine_config.json).
* [ImageMagick T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/alfresco-docker-imagemagick/src/main/resources/engine_config.json).
* [Libreoffice T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/alfresco-docker-libreoffice/src/main/resources/engine_config.json).
* [Tika T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/alfresco-docker-tika/src/main/resources/engine_config.json).
* [Misc T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/alfresco-docker-transform-misc/src/main/resources/engine_config.json).
The config can be found under `alfresco-transform-core/engines/<t-engine-name>/src/main/resources
/<t-engine-name>_engine_config.json`; current configuration files are:
* [Pdf-Renderer T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/engines/pdfrenderer/src/main/resources/pdfrenderer_engine_config.json).
* [ImageMagick T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/engines/imagemagick/src/main/resources/imagemagick_engine_config.json).
* [Libreoffice T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/engines/libreoffice/src/main/resources/libreoffice_engine_config.json).
* [Tika T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/engines/tika/src/main/resources/tika_engine_config.json).
* [Misc T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/engines/misc/src/main/resources/misc_engine_config.json).
*Snippet from Tika T-engine configuration:*
```json
@@ -64,9 +64,7 @@ The config can be found under `alfresco-transform-core\<t-engine-name>\src\main\
T-Engines. In this example there are two groups of options called **tikaOptions**
and **pdfboxOptions** which has a group of options **targetEncoding** and
**notExtractBookmarksText**. Unless an option has a **"required": true** field it is
considered to be optional. You don't need to specify *sourceMimetype*,
*targetMimetype*, *sourceExtension* or *targetExtension* as options as
these are automatically added.
considered to be optional.
*Snippet from ImageMagick T-engine configuration:*
```json
@@ -93,11 +91,6 @@ The config can be found under `alfresco-transform-core\<t-engine-name>\src\main\
use this approach as it is easier to read. A transformOptionsGroup can contain one or more transformOptionsValue
and transformOptionsGroup.
**Limitations**:
* For a transformOptions to be referenced in a different T-engine, another transformer
with the complete definition of the transformOptions needs to return the config to the client.
* In a transformOptions definition it is not allowed to use a reference to another tranformOption.
### Transformers
* **transformers** - A list of transformer definitions.
Each transformer definition should have a unique **transformerName**,