Quick reference for transformers in ACS Community 6.2

[angelborroy]

From ACS 6.2 a new Local Transform Sevice is available. Transformers before ACS 6.0 are now referred to as Legacy transformers.

You can turn on and off Local and Legacy transforms by setting Alfresco global properties.

Local Transform Service configuration

-Dlocal.transform.service.enabled=true
-DlocalTransform.pdfrenderer.url=http://alfresco-pdf-renderer:8090/
-DlocalTransform.imagemagick.url=http://imagemagick:8090/
-DlocalTransform.libreoffice.url=http://libreoffice:8090/
-DlocalTransform.tika.url=http://tika:8090/
-DlocalTransform.misc.url=http://transform-misc:8090/

Legacy Transform Service configuration

-Dlegacy.transform.service.enabled=true
-Dalfresco-pdf-renderer.url=http://alfresco-pdf-renderer:8090/
-Djodconverter.url=http://libreoffice:8090/
-Dtika.url=http://tika:8090/
-Dimg.url=http://imagemagick:8090/
-Dtransform.misc.url=http://transform-misc:8090/

Requests made to the V1 REST API for renditions make use of the RenditionService2 (available in Local Transform Service), which supports asynchronous requests.

https://api-explorer.alfresco.com/api-explorer/#/renditions

The RenditionService2 will use the Local Transform Service if it is available. If not, the service with fallback to the transformers performed the Legacy Transform Service.

The original RenditionService is now deprecated as it supports synchronous requests or requests that have
callbacks that must be processed on the same node.

Prior to ACS 6.0, legacy transformers ran within the same JVM as the ACS repository. They and their supporting code has been deprecated and will go away at some point.

Services still using V0 REST API and legacy transformers:

• Text extract for Solr (NodeContentGet webscript). Search Services 1.5 will make use of Local Transform Service.
• Synchronous transforms used by Share web app (v0 scripts, rules, actions). ACS 6.3 will make use of Local Transform Service.

Building a new Transformer for Local Transform Service

From ACS 6.2 it is possible to create custom transforms that run in separate processes known as Transformer Engines. The same engines may be used in Community and Enterprise Editions.

They may be directly connected to the ACS repository as Local Transforms, but in the Enterprise edition there is the option to include them as part of the Transform Service which provides more balanced throughput and better administration capabilities.

You can learn how to create a Transformer Engine and how to migrate your legacy transformer in:

• https://github.com/Alfresco/acs-packaging/blob/master/docs/creating-a-t-engine.md
• https://github.com/Alfresco/acs-packaging/blob/master/docs/migrating-a-legacy-transformer.md

Also, a sample on a Markdown to PDF Transformer Engine is available in:

https://github.com/aborroy/alf-tengine-markdown

The folder ats-transformer-markdown includes a Spring Boot application that exposes the Transform Service by HTTP and a sample web page to test the Transformer.

The folder docker includes a Docker Compose template to use this new transformer with the Local Transform Service by setting the values in Alfresco global properties:

    alfresco:
        build:
          context: ./alfresco
        mem_limit: 1700m
        environment:
            JAVA_OPTS: "
                 -Dlocal.transform.service.enabled=true
                 -DlocalTransform.markdown.url=http://alf-tengine-markdown:8090/
            "
        volumes:
          - ./rendition-defs-markdown.json:/usr/local/tomcat/shared/classes/alfresco/extension/transform/renditions/rendition-defs-markdown.json

    alf-tengine-markdown:
        image: alfresco/ats-transformer-markdown:1.0
        mem_limit: 1g
        environment:
            JAVA_OPTS: " -Xms256m -Xmx512m"
        ports:
            - 8096:8090

Deploying a new Transformer

Transformers are exposed to the Local Transform Service as HTTP Endpoints, so the Markdown to PDF Transformer provides the transform endpoint as http://alf-tengine-markdown:8090/transform inside the Docker Network:

https://github.com/aborroy/alf-tengine-markdown/blob/master/ats-transformer-markdown/src/main/java/o...

In order to deploy the Transformer with ACS 6.2, just start the Docker Compose template provided in folder docker:

$ cd docker
$ docker-compose up --build --force-recreate

Testing the Transformer

Once everything is up and ready, you'll be able to test the Markdown to PDF Transfomer in the sample web page available in:

http://localhost:8096

Note that you need to use the exposed port from Docker (8096) instead of the internal Docker Network port (8090) to test the service from your computer.

Sample web page for Transformer testing

Since Share web application is using V0 REST API, PDF renditions for Markdown files will not be applied by default.

But you can test the transformation for any node in your repository by using V1 REST API. In the following line a pdf rendition for node 09359434-5fc5-4e1d-8125-66101747c6e5 is requested:

$ curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
--header 'Authorization: Basic YWRtaW46YWRtaW4=' -d '{"id":"pdf"}' \
'http://127.0.0.1/alfresco/api/-default-/public/alfresco/versions/1/nodes/09359434-5fc5-4e1d-8125-66101747c6e5/renditions'

Share web application expects PDF renditions to be created with the name pdf, so after this request is performed, the preview will be available in Share UI.

A new Children named as cmdf will allow Share to provide the Preview

Using the new Transformer with Share and ACS 6.2

In order to apply transformations from Local Transform Services in Share by default, a simple behaviour can be developed. This behaviour can use the new RenditionService2 to provide a PDF rendition everytime a Markdown content node is created or updated.

The sample project includes a folder named markdown-rendition that includes an Alfresco SDK Repository artifact implementing this behaviour.

https://github.com/aborroy/alf-tengine-markdown/tree/master/markdown-rendition

This addon is deployed together with ACS 6.2 in the Docker Compose template, so when using this project uploaded Markdown content files will be renditioned to PDF by default.

https://github.com/aborroy/alf-tengine-markdown/blob/master/docker/alfresco/Dockerfile#L11

Additional references

https://github.com/Alfresco/acs-packaging/blob/master/docs/custom-transforms-and-renditions.md

https://github.com/Alfresco/alfresco-transform-service/blob/master/docs/custom-t-engine.md

https://github.com/Alfresco/alfresco-transform-service/blob/master/docs/transformer-routes-and-engin...

Available Docker Images

Default Transform Engines

https://hub.docker.com/r/alfresco/alfresco-imagemagick

https://hub.docker.com/r/alfresco/alfresco-libreoffice

https://hub.docker.com/r/alfresco/alfresco-pdf-renderer

https://hub.docker.com/r/alfresco/alfresco-tika

https://hub.docker.com/r/alfresco/alfresco-transform-misc

>> It's time to create your new Transformers or to migrate your legacy Transformer to the new Local Transform Service!