HCMS Schema - Transformations

Transformations are (together with webhooks) the primary way to extend HCMS API by a custom-implemented business logic and conceptually correspond to the often-requested ability to add scripting language (like XSLT in the censhare Classic).

The most important difference is that HCMS does not allow any turing-complete code to be defined as part of its schemas; instead, transformations are implemented as an external service and invoked as HTTP requests (also known as "webhooks").
These external services can be implemented in any programming language on any platform, but some kind of "lambda-function" (AWS lambda, knative and similar) are especially convenient.

Definition in schema

Transformations are defined by a top-level property "cs:transformation" ("cs:transformations" is also accepted as a typo). It must be a JSON object, with transformation ID as a key and JSON object as a value.

Each transformation as a single property: "url" with the endpoint used as a transformation endpoint.

JSON

{
    "cs:transformation": {
        "x1": {
            "url": "<http://localhost:8080/hcms/v4.0/transformation/sample/add-string-property/x1/aaa>"
        },
        "x2": {
            "url": "<http://localhost:8080/hcms/v4.0/transformation/sample/add-string-property/x2/aaa>"
        }
    }
}

Invocation

In the current version, transformed entity can be obtained only via REST API endpoint for one single entity: /entity/{name}/transformation/{transformationId}

Configuration

Configuration in the HeadlessCMS XML configuration file is completely optional. It allows configuration of timeouts and base URL (which allows relative paths in the schema).

XML

        <transformations>
            <http connection-timeout="1001" timeout="500">
              <base-url><http://localhost:8080/</base-url>>
            </http>
        </transformations>