Add Stitch support to plugins

Custom or community plugins that want to support the transform of artifacts using Stitch rules, must call the Stitch Engine transformer.

There are two ways to call the Stitch Engine transformer:

• either by using the Stitch DSL
• or, by directly calling the Artifact Transformer through the Deployment Context

This documentation section covers both the methods.

Note: Once the plugin is Stitch enabled and deployed on a Deploy instance (with Stitch installed on it), Stitch rules can be applied to your custom deployable types.

Enabling Stitch in plugin using DSL

The Stitch DSL can be used exclusively with Jython plugins. To do so, simply use the stitch(inputStream, transformer_context = {}) function registered in the classpath through the dsl.py file in the Stitch JAR. The stitch function returns the input stream with a new Stitch transformed JSON or YAML.

To use the stitch function, simply provide an input stream (java.io.InputStream) for any JSON or YAML that needs to be transformed with Stitch in given context e.g.:

transformedContent = stitch(source)

In the above example, source is the input stream having the JSON or YAML content that needs to be transformed using the Stitch rules and the transformedContent is the result JSON or YAML after the rules have been applied.

In case any Stitch related error occurrs during the execution of a Stitch transformation, a WARN message will be logged in the logs with the original exception message.

Additionally, if you want to use a plugin in both: a Stitch enabled as well as a normal Deploy environment you can use the following check:

if "stitch" in dir():
    ### Code using the Stitch enabled DSL goes here

Note: You can use the above check only if the stitch function is registered on your classpath.

Enabling Stitch through context

You can enable Stitch inside of a plugin using the deployment context in any type of plugin by simply fetching the Artifact Transformer stitchEngine and calling following method:

InputStream transform(InputStream source, Map<String, Object> transformationContext)

The above method will return transformed source input stream with all the applied Stitch rules applicable for the given deployed.

While processing, if any Stitch related error occurs the system throws a ArtifactTransformerException.

The following example shows the usage of the Deployment context while fetching the stitchEngine and calling the above transform method:

try {
    Map<String, Object> transformerContext = Collections.emptyMap()
    return context.getArtifactTransformer("stitchEngine").transform(source, transformer_context)
} catch(ArtifactTransformerError e) {
    // handle Stitch Error here
}

Note: If the Stitch Engine is missing (e.g. Stitch JAR is not added to the Deploy lib directory) both the DSL or the calling transformer through the context, it will throw an ArtifactTransformerNotDefinedException exception.

###Transformation Context The second argument to the Stitch transformation is transformationContext. By default, it is an empty map, but it can be used to pass variables to the Stitch engine.

Other relevant variables are:

• format - it can be used to indicate the input/output format of the file provided to the Stitch engine. If no file format is specified, it is resolved from the file name extension of the 'from deployed'.
• preProcessingTransformation - a flag indicating whether to trigger a preprocessing Stitch transformation or a regular one, see Stitch preprocessing transformation
• postProcessingTransformation - a flag indicating whether to trigger a postprocessing Stitch transformation or a regular one, see Stitch preprocessing transformation
• invocationName - used to set the label for the stitch invocation, which will be used on the Stitch Preview. If not set, the default label, Untitled transformation, is used.