This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-kamelets.git
The following commit(s) were added to refs/heads/main by this push:
new 6b6cbdfa6 chore: describe the template, crypto and PDF Kamelets for
people and AI assistants (#3143)
6b6cbdfa6 is described below
commit 6b6cbdfa6a3a9ad34c370f51d849e1fdaf47d0c6
Author: Claus Ibsen <[email protected]>
AuthorDate: Tue Nov 17 11:25:57 2026 +0100
chore: describe the template, crypto and PDF Kamelets for people and AI
assistants (#3143)
* chore: describe the template, crypto and PDF Kamelets for people and AI
assistants
Rewrites the descriptions and options of 10 Kamelets to the standard of
docs/modules/ROOT/pages/documenting.adoc (#3140): freemarker, velocity,
mvel and string-template template actions, jolt-transformation-action,
jslt-action, xj-identity-action, crypto-encrypt-action,
crypto-decrypt-action and pdf-action. Each was run, on Camel 4.24 and
4.23, to check what it says: the syntax with which each template language
reads the body and the headers, and what it does with a missing value; the
kind of body each JSON action accepts and gives; the key lengths of the
crypto actions; and the font names pdf-action accepts.
chunk-template-action and xj-template-action are left out: their templates
do not work as written, and they will be described with their fixes.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
* chore: escape a brace before a name in Kamelet descriptions
The documentation page renders descriptions and partial pages as
AsciiDoc, where {body} is an attribute reference that fails the
documentation check: write $\{body}, as the Camel documentation does.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
---------
Co-authored-by: Claude Opus 5.5 <[email protected]>
---
kamelets/crypto-decrypt-action.kamelet.yaml | 15 ++++++--
kamelets/crypto-encrypt-action.kamelet.yaml | 15 ++++++--
kamelets/freemarker-template-action.kamelet.yaml | 13 +++++--
kamelets/jolt-transformation-action.kamelet.yaml | 17 ++++++---
kamelets/jslt-action.kamelet.yaml | 13 +++++--
kamelets/mvel-template-action.kamelet.yaml | 13 +++++--
kamelets/pdf-action.kamelet.yaml | 19 +++++++---
kamelets/string-template-action.kamelet.yaml | 13 +++++--
kamelets/velocity-template-action.kamelet.yaml | 13 +++++--
kamelets/xj-identity-action.kamelet.yaml | 11 ++++--
.../main/resources/META-INF/kamelets-index.json | 40 +++++++++++-----------
.../kamelets/crypto-decrypt-action.kamelet.yaml | 15 ++++++--
.../kamelets/crypto-encrypt-action.kamelet.yaml | 15 ++++++--
.../freemarker-template-action.kamelet.yaml | 13 +++++--
.../jolt-transformation-action.kamelet.yaml | 17 ++++++---
.../resources/kamelets/jslt-action.kamelet.yaml | 13 +++++--
.../kamelets/mvel-template-action.kamelet.yaml | 13 +++++--
.../resources/kamelets/pdf-action.kamelet.yaml | 19 +++++++---
.../kamelets/string-template-action.kamelet.yaml | 13 +++++--
.../kamelets/velocity-template-action.kamelet.yaml | 13 +++++--
.../kamelets/xj-identity-action.kamelet.yaml | 11 ++++--
21 files changed, 252 insertions(+), 72 deletions(-)
diff --git a/kamelets/crypto-decrypt-action.kamelet.yaml
b/kamelets/crypto-decrypt-action.kamelet.yaml
index 30d181a8c..d3174a96a 100644
--- a/kamelets/crypto-decrypt-action.kamelet.yaml
+++ b/kamelets/crypto-decrypt-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "Crypto Decrypt Action"
- description: Decrypt the payload using the Java Cryptographic Extension
(JCE) and a fixed key.
+ description: |-
+ Decrypts the body of each message that `crypto-encrypt-action`
encrypted, with the same algorithm and secret key.
+
+ Use it to get back the original data that was encrypted with
`crypto-encrypt-action`, for example after reading it from storage or receiving
it from another system.
+
+ Input: the encrypted data exactly as `crypto-encrypt-action` produced
it, as bytes or a stream. If it was encoded on the way, for example in Base64,
decode it first.
+
+ Output: the body is the original data, as bytes (a stream). The headers
are kept.
+
+ Good to know: data that was changed, or a different `algorithm` or `key`
than when encrypting, fails the message with "Message authentication failed".
The key is a secret; keep it in a vault or a secret, not in plain configuration.
required:
- algorithm
- key
@@ -38,12 +47,12 @@ spec:
properties:
algorithm:
title: Algorithm
- description: The JCE algorithm name indicating the cryptographic
algorithm that will be used.
+ description: "The name of the encryption algorithm the data was
encrypted with, such as `AES`, or `DESede` for Triple DES. Give the name alone:
a full form such as `AES/CBC/PKCS5Padding` fails each message."
type: string
example: "AES"
key:
title: Secret Key
- description: The secret key to use to decrypt the payload. The length
must match the requirements of the selected algorithm (for example 16, 24 or 32
bytes for AES).
+ description: "The secret key the data was encrypted with, as text. Its
length must fit the algorithm: for `AES`, 16, 24 or 32 characters (plain ASCII
characters count as one byte each), and for `DESede`, 24."
type: string
format: password
x-descriptors:
diff --git a/kamelets/crypto-encrypt-action.kamelet.yaml
b/kamelets/crypto-encrypt-action.kamelet.yaml
index 49a785d14..756129ff3 100644
--- a/kamelets/crypto-encrypt-action.kamelet.yaml
+++ b/kamelets/crypto-encrypt-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "Crypto Encrypt Action"
- description: Encrypt the payload using the Java Cryptographic Extension
(JCE) and a fixed key.
+ description: |-
+ Encrypts the body of each message with a secret key, such as an AES key,
for `crypto-decrypt-action` to decrypt later with the same key.
+
+ Use it to protect sensitive data, such as personal or payment details,
before it is stored or sent through a system you do not fully trust, and
decrypt it later with `crypto-decrypt-action` and the same `algorithm` and
`key`.
+
+ Input: text or bytes.
+
+ Output: the body is the encrypted data, as bytes (a stream), a little
longer than the input. It is not text: to send it where only text fits, encode
it, for example in Base64. The headers are kept.
+
+ Good to know: the key is a secret; anyone who has it can decrypt the
data, so keep it in a vault or a secret, not in plain configuration. The
encrypted data carries a check value, so `crypto-decrypt-action` fails on data
that was changed or decrypted with another key. A key of the wrong length fails
each message, not the start.
required:
- algorithm
- key
@@ -38,12 +47,12 @@ spec:
properties:
algorithm:
title: Algorithm
- description: The JCE algorithm name indicating the cryptographic
algorithm that will be used.
+ description: "The name of the encryption algorithm, such as `AES`, or
`DESede` for Triple DES. Give the name alone: a full form such as
`AES/CBC/PKCS5Padding` fails each message. Use the same value in
`crypto-decrypt-action`."
type: string
example: "AES"
key:
title: Secret Key
- description: The secret key to use to encrypt the payload. The length
must match the requirements of the selected algorithm (for example 16, 24 or 32
bytes for AES).
+ description: "The secret key, as text. Its length must fit the
algorithm: for `AES`, 16, 24 or 32 characters (plain ASCII characters count as
one byte each), and for `DESede`, 24. Use the same key in
`crypto-decrypt-action`."
type: string
format: password
x-descriptors:
diff --git a/kamelets/freemarker-template-action.kamelet.yaml
b/kamelets/freemarker-template-action.kamelet.yaml
index eec62844a..2ac812947 100644
--- a/kamelets/freemarker-template-action.kamelet.yaml
+++ b/kamelets/freemarker-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "Freemarker Template Action"
- description: Apply a Freemarker Template.
+ description: |-
+ Builds a new message body from a FreeMarker template, filling in values
from the incoming message.
+
+ Use it to turn data into text for people or for another system, such as
an email, a report or a small XML or JSON document, when you already have
FreeMarker templates or need its loops and conditions. For simple templates,
`mustache-template-action` is an alternative; to reshape JSON into other JSON,
`jslt-action` is often simpler.
+
+ Input: any body. The template sees the body as `$\{body}` and a header
as `${headers.name}`, for example `Dear ${headers.customer}, your order
$\{body} has shipped.`
+
+ Output: the body is the text the template produced. The headers are kept.
+
+ Good to know: a value the template uses that is missing, such as a
header that is not set, fails the message; give a default with
`${headers.customer!""}`. A template file that cannot be found fails the
message too. The template is loaded from a file, the classpath or a URL given
by the `template` option; it cannot come from the message.
required:
- template
type: object
@@ -39,7 +48,7 @@ spec:
title: Template
description: "Where to load the FreeMarker template from, not the
FreeMarker template itself: `file://` followed by the path of a file,
`classpath://` followed by a resource in the application, or an `http://` or
`https://` URL."
type: string
- example: "file:////template.ftl"
+ example: "file:///opt/templates/order.ftl"
pattern: "^(http|https|file|classpath|ref|bean)://.*"
dependencies:
- "camel:freemarker"
diff --git a/kamelets/jolt-transformation-action.kamelet.yaml
b/kamelets/jolt-transformation-action.kamelet.yaml
index d6e122884..bcf5c7f26 100644
--- a/kamelets/jolt-transformation-action.kamelet.yaml
+++ b/kamelets/jolt-transformation-action.kamelet.yaml
@@ -30,20 +30,29 @@ metadata:
spec:
definition:
title: "Jolt Transformation Action"
- description: Apply a Jolt Transformation.
+ description: |-
+ Reshapes each JSON message into other JSON, as a Jolt specification
describes: moves, renames, removes fields or adds defaults.
+
+ Use it to map the JSON of one system to the JSON another system expects,
for example to rename fields or move them into a nested object, when you
already have Jolt specifications. `jslt-action` does the same with a query
language, and is often easier to write.
+
+ Input: parsed JSON, a Map (or a List). Since Camel 4.24, JSON text,
bytes and a stream work too. With older versions they do not fail but give an
empty body, and so does the parsed JSON of `json-deserialize-action`.
+
+ Output: the body is the result as parsed JSON, a Map (or a List), not
JSON text. Add `json-serialize-action` after it to get JSON text. The headers
are kept.
+
+ Good to know: the specification cannot read headers, only the body. It
is loaded from a file, the classpath or a URL given by the `template` option;
it cannot come from the message.
required:
- template
type: object
properties:
template:
title: Template
- description: "Where to load the Jolt specification from, not the Jolt
specification itself: `file://` followed by the path of a file, `classpath://`
followed by a resource in the application, or an `http://` or `https://` URL."
+ description: "Where to load the Jolt specification from, not the Jolt
specification itself: `file://` followed by the path of a file, `classpath://`
followed by a resource in the application, or an `http://` or `https://` URL.
With the default `transform`, the file holds a JSON array of steps, such as
`[{\"operation\": \"shift\", \"spec\": {\"name\": \"customer.fullName\"}}]`."
type: string
- example: "file:////template.json"
+ example: "file:///opt/templates/order-spec.json"
pattern: "^(http|https|file|classpath|ref|bean)://.*"
transform:
title: Transform DSL
- description: Specifies the Transform DSL of the endpoint resource. If
none is specified, Chainr is used.
+ description: "The kind of Jolt specification in the `template` file.
`Chainr`, the default, is a list of steps, each with an `operation` (such as
`shift`, `default` or `remove`) and a `spec`. The others take the spec of one
operation alone: `Shiftr` moves and renames fields, `Defaultr` adds default
values, `Removr` removes fields, and `Sortr` sorts the fields by name."
type: string
default: "Chainr"
enum: ["Chainr", "Shiftr", "Defaultr", "Removr", "Sortr"]
diff --git a/kamelets/jslt-action.kamelet.yaml
b/kamelets/jslt-action.kamelet.yaml
index 2658082b9..32c8e9b40 100644
--- a/kamelets/jslt-action.kamelet.yaml
+++ b/kamelets/jslt-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "JSLT Action"
- description: Apply a JSLT query or transformation on JSON.
+ description: |-
+ Turns each JSON message into new JSON with a JSLT transformation, a
query language for JSON that picks, renames and computes fields.
+
+ Use it to map the JSON of one system to the JSON another system expects,
for example to keep only some fields, rename them or count the items of an
order. To build text rather than JSON, use `mustache-template-action`;
`jolt-transformation-action` reshapes JSON with Jolt specifications instead.
+
+ Input: JSON text, bytes or a stream. The transformation sees the body as
`.` and a header as `$headers.name`, for example `{"customer": .name, "items":
size(.items), "source": $headers.origin}`.
+
+ Output: the body is the result as JSON text. The headers are kept.
+
+ Good to know: parsed JSON (a Map or a JsonNode, such as the output of
`json-deserialize-action`) fails the message: give the JSON as text. A field
whose value is missing, such as a header that is not set, is left out of the
result. The transformation is loaded from a file, the classpath or a URL given
by the `template` option; it cannot come from the message.
required:
- template
type: object
@@ -39,7 +48,7 @@ spec:
title: Template
description: "Where to load the JSLT transformation from, not the JSLT
transformation itself: `file://` followed by the path of a file, `classpath://`
followed by a resource in the application, or an `http://` or `https://` URL."
type: string
- example: "file://template.json"
+ example: "file:///opt/templates/order.jslt"
pattern: "^(http|https|file|classpath|ref|bean)://.*"
dependencies:
- "camel:jslt"
diff --git a/kamelets/mvel-template-action.kamelet.yaml
b/kamelets/mvel-template-action.kamelet.yaml
index 215a4bb83..bc32eb5bf 100644
--- a/kamelets/mvel-template-action.kamelet.yaml
+++ b/kamelets/mvel-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "Mvel Template Action"
- description: Apply a Mvel Template.
+ description: |-
+ Builds a new message body from an MVEL template, filling in values from
the incoming message.
+
+ Use it to turn data into text for people or for another system, such as
the text of an email or a small XML or JSON document, when you already have
MVEL templates. For simple templates, `mustache-template-action` is an
alternative; to reshape JSON into other JSON, `jslt-action` is often simpler.
+
+ Input: any body. The template sees the body as `@\{body}` and a header
as `@{headers.name}`, for example `Dear @{headers.customer}, your order
@\{body} has shipped.`
+
+ Output: the body is the text the template produced. The headers are kept.
+
+ Good to know: a header the template uses that is not set fails the
message, and so does a template file that cannot be found. The template is
loaded from a file, the classpath or a URL given by the `template` option; it
cannot come from the message.
required:
- template
type: object
@@ -39,7 +48,7 @@ spec:
title: Template
description: "Where to load the MVEL template from, not the MVEL
template itself: `file://` followed by the path of a file, `classpath://`
followed by a resource in the application, or an `http://` or `https://` URL."
type: string
- example: "file:////template.mvel"
+ example: "file:///opt/templates/order.mvel"
pattern: "^(http|https|file|classpath|ref|bean)://.*"
dependencies:
- "camel:mvel"
diff --git a/kamelets/pdf-action.kamelet.yaml b/kamelets/pdf-action.kamelet.yaml
index d0ddc4a5b..93d5a7593 100644
--- a/kamelets/pdf-action.kamelet.yaml
+++ b/kamelets/pdf-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "PDF Action"
- description: Create a PDF.
+ description: |-
+ Turns the text of each message into a PDF document, with one font, font
size and page size for the whole text.
+
+ Use it to produce a simple printable document, such as a receipt, a
report or a log, that is then stored as a file or sent by email. To lay out the
text first, put a template action before it, such as `mustache-template-action`.
+
+ Input: the body is the text to write, as text. Each line of the text
starts a new line in the PDF, and a new page starts when a page is full.
+
+ Output: the body is the PDF document, as bytes. The headers are kept as
they are; a `Content-Type` header set before is not changed to PDF.
+
+ Good to know: long lines are not wrapped; they run past the right edge
of the page. Set `font` to one of the names its description lists, such as
`HELVETICA`: the default value `Helvetica` fails each message.
required:
- font
- fontSize
@@ -39,19 +48,21 @@ spec:
properties:
font:
title: Font
- description: The font to use while generating the PDF. One of Courier,
Courier-Bold, Courier-Oblique, Courier-BoldOblique, Helvetica, Helvetica-Bold,
Helvetica-Oblique, Helvetica-BoldOblique, Times-Roman, Times-Bold,
Times-Italic, Times-BoldItalic, Symbol, ZapfDingbats
+ description: "The font of the whole text, one of the standard PDF
fonts: `COURIER`, `COURIER_BOLD`, `COURIER_OBLIQUE`, `COURIER_BOLD_OBLIQUE`,
`HELVETICA`, `HELVETICA_BOLD`, `HELVETICA_OBLIQUE`, `HELVETICA_BOLD_OBLIQUE`,
`TIMES_ROMAN`, `TIMES_BOLD`, `TIMES_ITALIC`, `TIMES_BOLD_ITALIC`, `SYMBOL` or
`ZAPF_DINGBATS`. Write the name in capitals with underscores: `Helvetica` or
`Times-Roman` fails each message."
type: string
default: HELVETICA
+ example: "HELVETICA"
fontSize:
title: Font Size
- description: The Font size to use while generating the PDF
+ description: "The size of the text, in points, such as `12` or `10.5`.
72 points make one inch."
type: string
default: 14.0
pageSize:
title: Page Size
- description: The Page size to use while generating the PDF. One of
LETTER, LEGAL, A0, A1, A2, A3, A4, A5, A6
+ description: "The size of the pages: `A0` to `A6` (`A4` is 210 by 297
millimetres), `LETTER` (8.5 by 11 inches) or `LEGAL` (8.5 by 14 inches)."
type: string
default: A4
+ enum: ["LETTER", "LEGAL", "A0", "A1", "A2", "A3", "A4", "A5", "A6"]
dependencies:
- "camel:pdf"
- "camel:kamelet"
diff --git a/kamelets/string-template-action.kamelet.yaml
b/kamelets/string-template-action.kamelet.yaml
index ea14a4148..3604580ba 100644
--- a/kamelets/string-template-action.kamelet.yaml
+++ b/kamelets/string-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "String Template Action"
- description: Apply a String Template.
+ description: |-
+ Builds a new message body from a StringTemplate template, filling in
values from the incoming message.
+
+ Use it to turn data into text for people or for another system, such as
the text of an email or a small XML or JSON document, when you already have
StringTemplate templates. For simple templates, `mustache-template-action` is
an alternative; to reshape JSON into other JSON, `jslt-action` is often simpler.
+
+ Input: any body. The template sees the body as `<body>` and a header as
`<headers.name>`, for example `Dear <headers.customer>, your order <body> has
shipped.`
+
+ Output: the body is the text the template produced. The headers are
kept, and a `CamelStringTemplateResourceUri` header is added with the location
of the template.
+
+ Good to know: a header the template uses that is not set gives nothing
in the text. A template file that cannot be found fails the message. The
template is loaded from a file, the classpath or a URL given by the `template`
option; it cannot come from the message.
required:
- template
type: object
@@ -39,7 +48,7 @@ spec:
title: Template
description: "Where to load the StringTemplate template from, not the
StringTemplate template itself: `file://` followed by the path of a file,
`classpath://` followed by a resource in the application, or an `http://` or
`https://` URL."
type: string
- example: "file:////template.tm"
+ example: "file:///opt/templates/order.st"
pattern: "^(http|https|file|classpath|ref|bean)://.*"
dependencies:
- "camel:stringtemplate"
diff --git a/kamelets/velocity-template-action.kamelet.yaml
b/kamelets/velocity-template-action.kamelet.yaml
index 1658ebc48..7e87edd85 100644
--- a/kamelets/velocity-template-action.kamelet.yaml
+++ b/kamelets/velocity-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "Velocity Template Action"
- description: Apply a Velocity Template.
+ description: |-
+ Builds a new message body from an Apache Velocity template, filling in
values from the incoming message.
+
+ Use it to turn data into text for people or for another system, such as
an email, a report or a small XML or JSON document, when you already have
Velocity templates or need its loops and conditions. For simple templates,
`mustache-template-action` is an alternative; to reshape JSON into other JSON,
`jslt-action` is often simpler.
+
+ Input: any body. The template sees the body as `$\{body}` and a header
as `${headers.name}`, for example `Dear ${headers.customer}, your order
$\{body} has shipped.`
+
+ Output: the body is the text the template produced. The headers are kept.
+
+ Good to know: a value the template uses that is missing, such as a
header that is not set, stays in the text as written, for example
`${headers.customer}`; write `$!{headers.customer}` to get nothing instead. A
template file that cannot be found fails the message. The template is loaded
from a file, the classpath or a URL given by the `template` option; it cannot
come from the message.
required:
- template
type: object
@@ -39,7 +48,7 @@ spec:
title: Template
description: "Where to load the Velocity template from, not the
Velocity template itself: `file://` followed by the path of a file,
`classpath://` followed by a resource in the application, or an `http://` or
`https://` URL."
type: string
- example: "file:////template.vm"
+ example: "file:///opt/templates/order.vm"
pattern: "^(http|https|file|classpath|ref|bean)://.*"
dependencies:
- "camel:velocity"
diff --git a/kamelets/xj-identity-action.kamelet.yaml
b/kamelets/xj-identity-action.kamelet.yaml
index 739cb2ba2..afd7547d6 100644
--- a/kamelets/xj-identity-action.kamelet.yaml
+++ b/kamelets/xj-identity-action.kamelet.yaml
@@ -31,14 +31,21 @@ metadata:
spec:
definition:
title: "XJ Identity Action"
- description: Apply the XJ Identity Transformation to transform JSON to XML
and XML to JSON.
+ description: |-
+ Converts each message from XML to JSON, or from JSON to XML, with a
fixed mapping and no template to write.
+
+ Use it to pass XML to a system that expects JSON, or the other way
round, when the default mapping is good enough. To control the result, such as
the names of the elements or which fields to keep, use `xj-template-action`
with an XSLT stylesheet.
+
+ Input: XML or JSON as text, bytes or a stream, as `direction` says.
Parsed JSON, such as a Map, fails the message.
+
+ Output: the body is JSON text or XML text. From XML, the root element is
dropped, its attributes and child elements become fields, repeated elements
become an array, and all values are text: `<order id="7"><qty>2</qty></order>`
gives `{"id":"7","qty":"2"}`. To XML, each JSON value becomes an `object`
element that keeps its name and type in `xj:name` and `xj:type` attributes,
such as `<object xj:name="qty" xj:type="int">2</object>`. The headers are kept.
required:
- direction
type: object
properties:
direction:
title: Direction
- description: The transform direction.
+ description: "Which way to convert: `XML2JSON` turns XML into JSON,
and `JSON2XML` turns JSON into XML."
type: string
enum: ["XML2JSON", "JSON2XML"]
dependencies:
diff --git
a/library/camel-kamelets/src/main/resources/META-INF/kamelets-index.json
b/library/camel-kamelets/src/main/resources/META-INF/kamelets-index.json
index d6b42583c..4739111ed 100644
--- a/library/camel-kamelets/src/main/resources/META-INF/kamelets-index.json
+++ b/library/camel-kamelets/src/main/resources/META-INF/kamelets-index.json
@@ -654,8 +654,8 @@
"type" : "action",
"supportLevel" : "Stable",
"title" : "Crypto Decrypt Action",
- "summary" : "Decrypt the payload using the Java Cryptographic Extension
(JCE) and a fixed key.",
- "description" : "Decrypt the payload using the Java Cryptographic
Extension (JCE) and a fixed key.",
+ "summary" : "Decrypts the body of each message that
`crypto-encrypt-action` encrypted, with the same algorithm and secret key.",
+ "description" : "Decrypts the body of each message that
`crypto-encrypt-action` encrypted, with the same algorithm and secret
key.\n\nUse it to get back the original data that was encrypted with
`crypto-encrypt-action`, for example after reading it from storage or receiving
it from another system.\n\nInput: the encrypted data exactly as
`crypto-encrypt-action` produced it, as bytes or a stream. If it was encoded on
the way, for example in Base64, decode it first.\n\nOutput: the body [...]
"group" : "Actions",
"namespace" : "Transformation",
"provider" : "Apache Software Foundation"
@@ -664,8 +664,8 @@
"type" : "action",
"supportLevel" : "Stable",
"title" : "Crypto Encrypt Action",
- "summary" : "Encrypt the payload using the Java Cryptographic Extension
(JCE) and a fixed key.",
- "description" : "Encrypt the payload using the Java Cryptographic
Extension (JCE) and a fixed key.",
+ "summary" : "Encrypts the body of each message with a secret key, such as
an AES key, for `crypto-decrypt-action` to decrypt later with the same key.",
+ "description" : "Encrypts the body of each message with a secret key, such
as an AES key, for `crypto-decrypt-action` to decrypt later with the same
key.\n\nUse it to protect sensitive data, such as personal or payment details,
before it is stored or sent through a system you do not fully trust, and
decrypt it later with `crypto-decrypt-action` and the same `algorithm` and
`key`.\n\nInput: text or bytes.\n\nOutput: the body is the encrypted data, as
bytes (a stream), a little longer [...]
"group" : "Actions",
"namespace" : "Transformation",
"provider" : "Apache Software Foundation"
@@ -894,8 +894,8 @@
"type" : "action",
"supportLevel" : "Stable",
"title" : "Freemarker Template Action",
- "summary" : "Apply a Freemarker Template.",
- "description" : "Apply a Freemarker Template.",
+ "summary" : "Builds a new message body from a FreeMarker template, filling
in values from the incoming message.",
+ "description" : "Builds a new message body from a FreeMarker template,
filling in values from the incoming message.\n\nUse it to turn data into text
for people or for another system, such as an email, a report or a small XML or
JSON document, when you already have FreeMarker templates or need its loops and
conditions. For simple templates, `mustache-template-action` is an alternative;
to reshape JSON into other JSON, `jslt-action` is often simpler.\n\nInput: any
body. The template se [...]
"group" : "Actions",
"namespace" : "Transformation",
"provider" : "Apache Software Foundation"
@@ -1414,8 +1414,8 @@
"type" : "action",
"supportLevel" : "Stable",
"title" : "Jolt Transformation Action",
- "summary" : "Apply a Jolt Transformation.",
- "description" : "Apply a Jolt Transformation.",
+ "summary" : "Reshapes each JSON message into other JSON, as a Jolt
specification describes: moves, renames, removes fields or adds defaults.",
+ "description" : "Reshapes each JSON message into other JSON, as a Jolt
specification describes: moves, renames, removes fields or adds
defaults.\n\nUse it to map the JSON of one system to the JSON another system
expects, for example to rename fields or move them into a nested object, when
you already have Jolt specifications. `jslt-action` does the same with a query
language, and is often easier to write.\n\nInput: parsed JSON, a Map (or a
List). Since Camel 4.24, JSON text, bytes an [...]
"group" : "Actions",
"namespace" : "Transformation",
"provider" : "Apache Software Foundation"
@@ -1424,8 +1424,8 @@
"type" : "action",
"supportLevel" : "Stable",
"title" : "JSLT Action",
- "summary" : "Apply a JSLT query or transformation on JSON.",
- "description" : "Apply a JSLT query or transformation on JSON.",
+ "summary" : "Turns each JSON message into new JSON with a JSLT
transformation, a query language for JSON that picks, renames and computes
fields.",
+ "description" : "Turns each JSON message into new JSON with a JSLT
transformation, a query language for JSON that picks, renames and computes
fields.\n\nUse it to map the JSON of one system to the JSON another system
expects, for example to keep only some fields, rename them or count the items
of an order. To build text rather than JSON, use `mustache-template-action`;
`jolt-transformation-action` reshapes JSON with Jolt specifications
instead.\n\nInput: JSON text, bytes or a stream. [...]
"group" : "Actions",
"namespace" : "Transformation",
"provider" : "Apache Software Foundation"
@@ -1864,8 +1864,8 @@
"type" : "action",
"supportLevel" : "Stable",
"title" : "Mvel Template Action",
- "summary" : "Apply a Mvel Template.",
- "description" : "Apply a Mvel Template.",
+ "summary" : "Builds a new message body from an MVEL template, filling in
values from the incoming message.",
+ "description" : "Builds a new message body from an MVEL template, filling
in values from the incoming message.\n\nUse it to turn data into text for
people or for another system, such as the text of an email or a small XML or
JSON document, when you already have MVEL templates. For simple templates,
`mustache-template-action` is an alternative; to reshape JSON into other JSON,
`jslt-action` is often simpler.\n\nInput: any body. The template sees the body
as `@\\{body}` and a header as [...]
"group" : "Actions",
"namespace" : "Transformation",
"provider" : "Apache Software Foundation"
@@ -1974,8 +1974,8 @@
"type" : "action",
"supportLevel" : "Stable",
"title" : "PDF Action",
- "summary" : "Create a PDF.",
- "description" : "Create a PDF.",
+ "summary" : "Turns the text of each message into a PDF document, with one
font, font size and page size for the whole text.",
+ "description" : "Turns the text of each message into a PDF document, with
one font, font size and page size for the whole text.\n\nUse it to produce a
simple printable document, such as a receipt, a report or a log, that is then
stored as a file or sent by email. To lay out the text first, put a template
action before it, such as `mustache-template-action`.\n\nInput: the body is the
text to write, as text. Each line of the text starts a new line in the PDF, and
a new page starts when [...]
"group" : "PDF",
"namespace" : "Transformation",
"provider" : "Apache Software Foundation"
@@ -2424,8 +2424,8 @@
"type" : "action",
"supportLevel" : "Stable",
"title" : "String Template Action",
- "summary" : "Apply a String Template.",
- "description" : "Apply a String Template.",
+ "summary" : "Builds a new message body from a StringTemplate template,
filling in values from the incoming message.",
+ "description" : "Builds a new message body from a StringTemplate template,
filling in values from the incoming message.\n\nUse it to turn data into text
for people or for another system, such as the text of an email or a small XML
or JSON document, when you already have StringTemplate templates. For simple
templates, `mustache-template-action` is an alternative; to reshape JSON into
other JSON, `jslt-action` is often simpler.\n\nInput: any body. The template
sees the body as `<body>` [...]
"group" : "Actions",
"namespace" : "Transformation",
"provider" : "Apache Software Foundation"
@@ -2544,8 +2544,8 @@
"type" : "action",
"supportLevel" : "Stable",
"title" : "Velocity Template Action",
- "summary" : "Apply a Velocity Template.",
- "description" : "Apply a Velocity Template.",
+ "summary" : "Builds a new message body from an Apache Velocity template,
filling in values from the incoming message.",
+ "description" : "Builds a new message body from an Apache Velocity
template, filling in values from the incoming message.\n\nUse it to turn data
into text for people or for another system, such as an email, a report or a
small XML or JSON document, when you already have Velocity templates or need
its loops and conditions. For simple templates, `mustache-template-action` is
an alternative; to reshape JSON into other JSON, `jslt-action` is often
simpler.\n\nInput: any body. The templat [...]
"group" : "Actions",
"namespace" : "Transformation",
"provider" : "Apache Software Foundation"
@@ -2574,8 +2574,8 @@
"type" : "action",
"supportLevel" : "Stable",
"title" : "XJ Identity Action",
- "summary" : "Apply the XJ Identity Transformation to transform JSON to XML
and XML to JSON.",
- "description" : "Apply the XJ Identity Transformation to transform JSON to
XML and XML to JSON.",
+ "summary" : "Converts each message from XML to JSON, or from JSON to XML,
with a fixed mapping and no template to write.",
+ "description" : "Converts each message from XML to JSON, or from JSON to
XML, with a fixed mapping and no template to write.\n\nUse it to pass XML to a
system that expects JSON, or the other way round, when the default mapping is
good enough. To control the result, such as the names of the elements or which
fields to keep, use `xj-template-action` with an XSLT stylesheet.\n\nInput: XML
or JSON as text, bytes or a stream, as `direction` says. Parsed JSON, such as a
Map, fails the mess [...]
"group" : "Actions",
"namespace" : "Transformation",
"provider" : "Apache Software Foundation"
diff --git
a/library/camel-kamelets/src/main/resources/kamelets/crypto-decrypt-action.kamelet.yaml
b/library/camel-kamelets/src/main/resources/kamelets/crypto-decrypt-action.kamelet.yaml
index 30d181a8c..d3174a96a 100644
---
a/library/camel-kamelets/src/main/resources/kamelets/crypto-decrypt-action.kamelet.yaml
+++
b/library/camel-kamelets/src/main/resources/kamelets/crypto-decrypt-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "Crypto Decrypt Action"
- description: Decrypt the payload using the Java Cryptographic Extension
(JCE) and a fixed key.
+ description: |-
+ Decrypts the body of each message that `crypto-encrypt-action`
encrypted, with the same algorithm and secret key.
+
+ Use it to get back the original data that was encrypted with
`crypto-encrypt-action`, for example after reading it from storage or receiving
it from another system.
+
+ Input: the encrypted data exactly as `crypto-encrypt-action` produced
it, as bytes or a stream. If it was encoded on the way, for example in Base64,
decode it first.
+
+ Output: the body is the original data, as bytes (a stream). The headers
are kept.
+
+ Good to know: data that was changed, or a different `algorithm` or `key`
than when encrypting, fails the message with "Message authentication failed".
The key is a secret; keep it in a vault or a secret, not in plain configuration.
required:
- algorithm
- key
@@ -38,12 +47,12 @@ spec:
properties:
algorithm:
title: Algorithm
- description: The JCE algorithm name indicating the cryptographic
algorithm that will be used.
+ description: "The name of the encryption algorithm the data was
encrypted with, such as `AES`, or `DESede` for Triple DES. Give the name alone:
a full form such as `AES/CBC/PKCS5Padding` fails each message."
type: string
example: "AES"
key:
title: Secret Key
- description: The secret key to use to decrypt the payload. The length
must match the requirements of the selected algorithm (for example 16, 24 or 32
bytes for AES).
+ description: "The secret key the data was encrypted with, as text. Its
length must fit the algorithm: for `AES`, 16, 24 or 32 characters (plain ASCII
characters count as one byte each), and for `DESede`, 24."
type: string
format: password
x-descriptors:
diff --git
a/library/camel-kamelets/src/main/resources/kamelets/crypto-encrypt-action.kamelet.yaml
b/library/camel-kamelets/src/main/resources/kamelets/crypto-encrypt-action.kamelet.yaml
index 49a785d14..756129ff3 100644
---
a/library/camel-kamelets/src/main/resources/kamelets/crypto-encrypt-action.kamelet.yaml
+++
b/library/camel-kamelets/src/main/resources/kamelets/crypto-encrypt-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "Crypto Encrypt Action"
- description: Encrypt the payload using the Java Cryptographic Extension
(JCE) and a fixed key.
+ description: |-
+ Encrypts the body of each message with a secret key, such as an AES key,
for `crypto-decrypt-action` to decrypt later with the same key.
+
+ Use it to protect sensitive data, such as personal or payment details,
before it is stored or sent through a system you do not fully trust, and
decrypt it later with `crypto-decrypt-action` and the same `algorithm` and
`key`.
+
+ Input: text or bytes.
+
+ Output: the body is the encrypted data, as bytes (a stream), a little
longer than the input. It is not text: to send it where only text fits, encode
it, for example in Base64. The headers are kept.
+
+ Good to know: the key is a secret; anyone who has it can decrypt the
data, so keep it in a vault or a secret, not in plain configuration. The
encrypted data carries a check value, so `crypto-decrypt-action` fails on data
that was changed or decrypted with another key. A key of the wrong length fails
each message, not the start.
required:
- algorithm
- key
@@ -38,12 +47,12 @@ spec:
properties:
algorithm:
title: Algorithm
- description: The JCE algorithm name indicating the cryptographic
algorithm that will be used.
+ description: "The name of the encryption algorithm, such as `AES`, or
`DESede` for Triple DES. Give the name alone: a full form such as
`AES/CBC/PKCS5Padding` fails each message. Use the same value in
`crypto-decrypt-action`."
type: string
example: "AES"
key:
title: Secret Key
- description: The secret key to use to encrypt the payload. The length
must match the requirements of the selected algorithm (for example 16, 24 or 32
bytes for AES).
+ description: "The secret key, as text. Its length must fit the
algorithm: for `AES`, 16, 24 or 32 characters (plain ASCII characters count as
one byte each), and for `DESede`, 24. Use the same key in
`crypto-decrypt-action`."
type: string
format: password
x-descriptors:
diff --git
a/library/camel-kamelets/src/main/resources/kamelets/freemarker-template-action.kamelet.yaml
b/library/camel-kamelets/src/main/resources/kamelets/freemarker-template-action.kamelet.yaml
index eec62844a..2ac812947 100644
---
a/library/camel-kamelets/src/main/resources/kamelets/freemarker-template-action.kamelet.yaml
+++
b/library/camel-kamelets/src/main/resources/kamelets/freemarker-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "Freemarker Template Action"
- description: Apply a Freemarker Template.
+ description: |-
+ Builds a new message body from a FreeMarker template, filling in values
from the incoming message.
+
+ Use it to turn data into text for people or for another system, such as
an email, a report or a small XML or JSON document, when you already have
FreeMarker templates or need its loops and conditions. For simple templates,
`mustache-template-action` is an alternative; to reshape JSON into other JSON,
`jslt-action` is often simpler.
+
+ Input: any body. The template sees the body as `$\{body}` and a header
as `${headers.name}`, for example `Dear ${headers.customer}, your order
$\{body} has shipped.`
+
+ Output: the body is the text the template produced. The headers are kept.
+
+ Good to know: a value the template uses that is missing, such as a
header that is not set, fails the message; give a default with
`${headers.customer!""}`. A template file that cannot be found fails the
message too. The template is loaded from a file, the classpath or a URL given
by the `template` option; it cannot come from the message.
required:
- template
type: object
@@ -39,7 +48,7 @@ spec:
title: Template
description: "Where to load the FreeMarker template from, not the
FreeMarker template itself: `file://` followed by the path of a file,
`classpath://` followed by a resource in the application, or an `http://` or
`https://` URL."
type: string
- example: "file:////template.ftl"
+ example: "file:///opt/templates/order.ftl"
pattern: "^(http|https|file|classpath|ref|bean)://.*"
dependencies:
- "camel:freemarker"
diff --git
a/library/camel-kamelets/src/main/resources/kamelets/jolt-transformation-action.kamelet.yaml
b/library/camel-kamelets/src/main/resources/kamelets/jolt-transformation-action.kamelet.yaml
index d6e122884..bcf5c7f26 100644
---
a/library/camel-kamelets/src/main/resources/kamelets/jolt-transformation-action.kamelet.yaml
+++
b/library/camel-kamelets/src/main/resources/kamelets/jolt-transformation-action.kamelet.yaml
@@ -30,20 +30,29 @@ metadata:
spec:
definition:
title: "Jolt Transformation Action"
- description: Apply a Jolt Transformation.
+ description: |-
+ Reshapes each JSON message into other JSON, as a Jolt specification
describes: moves, renames, removes fields or adds defaults.
+
+ Use it to map the JSON of one system to the JSON another system expects,
for example to rename fields or move them into a nested object, when you
already have Jolt specifications. `jslt-action` does the same with a query
language, and is often easier to write.
+
+ Input: parsed JSON, a Map (or a List). Since Camel 4.24, JSON text,
bytes and a stream work too. With older versions they do not fail but give an
empty body, and so does the parsed JSON of `json-deserialize-action`.
+
+ Output: the body is the result as parsed JSON, a Map (or a List), not
JSON text. Add `json-serialize-action` after it to get JSON text. The headers
are kept.
+
+ Good to know: the specification cannot read headers, only the body. It
is loaded from a file, the classpath or a URL given by the `template` option;
it cannot come from the message.
required:
- template
type: object
properties:
template:
title: Template
- description: "Where to load the Jolt specification from, not the Jolt
specification itself: `file://` followed by the path of a file, `classpath://`
followed by a resource in the application, or an `http://` or `https://` URL."
+ description: "Where to load the Jolt specification from, not the Jolt
specification itself: `file://` followed by the path of a file, `classpath://`
followed by a resource in the application, or an `http://` or `https://` URL.
With the default `transform`, the file holds a JSON array of steps, such as
`[{\"operation\": \"shift\", \"spec\": {\"name\": \"customer.fullName\"}}]`."
type: string
- example: "file:////template.json"
+ example: "file:///opt/templates/order-spec.json"
pattern: "^(http|https|file|classpath|ref|bean)://.*"
transform:
title: Transform DSL
- description: Specifies the Transform DSL of the endpoint resource. If
none is specified, Chainr is used.
+ description: "The kind of Jolt specification in the `template` file.
`Chainr`, the default, is a list of steps, each with an `operation` (such as
`shift`, `default` or `remove`) and a `spec`. The others take the spec of one
operation alone: `Shiftr` moves and renames fields, `Defaultr` adds default
values, `Removr` removes fields, and `Sortr` sorts the fields by name."
type: string
default: "Chainr"
enum: ["Chainr", "Shiftr", "Defaultr", "Removr", "Sortr"]
diff --git
a/library/camel-kamelets/src/main/resources/kamelets/jslt-action.kamelet.yaml
b/library/camel-kamelets/src/main/resources/kamelets/jslt-action.kamelet.yaml
index 2658082b9..32c8e9b40 100644
---
a/library/camel-kamelets/src/main/resources/kamelets/jslt-action.kamelet.yaml
+++
b/library/camel-kamelets/src/main/resources/kamelets/jslt-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "JSLT Action"
- description: Apply a JSLT query or transformation on JSON.
+ description: |-
+ Turns each JSON message into new JSON with a JSLT transformation, a
query language for JSON that picks, renames and computes fields.
+
+ Use it to map the JSON of one system to the JSON another system expects,
for example to keep only some fields, rename them or count the items of an
order. To build text rather than JSON, use `mustache-template-action`;
`jolt-transformation-action` reshapes JSON with Jolt specifications instead.
+
+ Input: JSON text, bytes or a stream. The transformation sees the body as
`.` and a header as `$headers.name`, for example `{"customer": .name, "items":
size(.items), "source": $headers.origin}`.
+
+ Output: the body is the result as JSON text. The headers are kept.
+
+ Good to know: parsed JSON (a Map or a JsonNode, such as the output of
`json-deserialize-action`) fails the message: give the JSON as text. A field
whose value is missing, such as a header that is not set, is left out of the
result. The transformation is loaded from a file, the classpath or a URL given
by the `template` option; it cannot come from the message.
required:
- template
type: object
@@ -39,7 +48,7 @@ spec:
title: Template
description: "Where to load the JSLT transformation from, not the JSLT
transformation itself: `file://` followed by the path of a file, `classpath://`
followed by a resource in the application, or an `http://` or `https://` URL."
type: string
- example: "file://template.json"
+ example: "file:///opt/templates/order.jslt"
pattern: "^(http|https|file|classpath|ref|bean)://.*"
dependencies:
- "camel:jslt"
diff --git
a/library/camel-kamelets/src/main/resources/kamelets/mvel-template-action.kamelet.yaml
b/library/camel-kamelets/src/main/resources/kamelets/mvel-template-action.kamelet.yaml
index 215a4bb83..bc32eb5bf 100644
---
a/library/camel-kamelets/src/main/resources/kamelets/mvel-template-action.kamelet.yaml
+++
b/library/camel-kamelets/src/main/resources/kamelets/mvel-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "Mvel Template Action"
- description: Apply a Mvel Template.
+ description: |-
+ Builds a new message body from an MVEL template, filling in values from
the incoming message.
+
+ Use it to turn data into text for people or for another system, such as
the text of an email or a small XML or JSON document, when you already have
MVEL templates. For simple templates, `mustache-template-action` is an
alternative; to reshape JSON into other JSON, `jslt-action` is often simpler.
+
+ Input: any body. The template sees the body as `@\{body}` and a header
as `@{headers.name}`, for example `Dear @{headers.customer}, your order
@\{body} has shipped.`
+
+ Output: the body is the text the template produced. The headers are kept.
+
+ Good to know: a header the template uses that is not set fails the
message, and so does a template file that cannot be found. The template is
loaded from a file, the classpath or a URL given by the `template` option; it
cannot come from the message.
required:
- template
type: object
@@ -39,7 +48,7 @@ spec:
title: Template
description: "Where to load the MVEL template from, not the MVEL
template itself: `file://` followed by the path of a file, `classpath://`
followed by a resource in the application, or an `http://` or `https://` URL."
type: string
- example: "file:////template.mvel"
+ example: "file:///opt/templates/order.mvel"
pattern: "^(http|https|file|classpath|ref|bean)://.*"
dependencies:
- "camel:mvel"
diff --git
a/library/camel-kamelets/src/main/resources/kamelets/pdf-action.kamelet.yaml
b/library/camel-kamelets/src/main/resources/kamelets/pdf-action.kamelet.yaml
index d0ddc4a5b..93d5a7593 100644
--- a/library/camel-kamelets/src/main/resources/kamelets/pdf-action.kamelet.yaml
+++ b/library/camel-kamelets/src/main/resources/kamelets/pdf-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "PDF Action"
- description: Create a PDF.
+ description: |-
+ Turns the text of each message into a PDF document, with one font, font
size and page size for the whole text.
+
+ Use it to produce a simple printable document, such as a receipt, a
report or a log, that is then stored as a file or sent by email. To lay out the
text first, put a template action before it, such as `mustache-template-action`.
+
+ Input: the body is the text to write, as text. Each line of the text
starts a new line in the PDF, and a new page starts when a page is full.
+
+ Output: the body is the PDF document, as bytes. The headers are kept as
they are; a `Content-Type` header set before is not changed to PDF.
+
+ Good to know: long lines are not wrapped; they run past the right edge
of the page. Set `font` to one of the names its description lists, such as
`HELVETICA`: the default value `Helvetica` fails each message.
required:
- font
- fontSize
@@ -39,19 +48,21 @@ spec:
properties:
font:
title: Font
- description: The font to use while generating the PDF. One of Courier,
Courier-Bold, Courier-Oblique, Courier-BoldOblique, Helvetica, Helvetica-Bold,
Helvetica-Oblique, Helvetica-BoldOblique, Times-Roman, Times-Bold,
Times-Italic, Times-BoldItalic, Symbol, ZapfDingbats
+ description: "The font of the whole text, one of the standard PDF
fonts: `COURIER`, `COURIER_BOLD`, `COURIER_OBLIQUE`, `COURIER_BOLD_OBLIQUE`,
`HELVETICA`, `HELVETICA_BOLD`, `HELVETICA_OBLIQUE`, `HELVETICA_BOLD_OBLIQUE`,
`TIMES_ROMAN`, `TIMES_BOLD`, `TIMES_ITALIC`, `TIMES_BOLD_ITALIC`, `SYMBOL` or
`ZAPF_DINGBATS`. Write the name in capitals with underscores: `Helvetica` or
`Times-Roman` fails each message."
type: string
default: HELVETICA
+ example: "HELVETICA"
fontSize:
title: Font Size
- description: The Font size to use while generating the PDF
+ description: "The size of the text, in points, such as `12` or `10.5`.
72 points make one inch."
type: string
default: 14.0
pageSize:
title: Page Size
- description: The Page size to use while generating the PDF. One of
LETTER, LEGAL, A0, A1, A2, A3, A4, A5, A6
+ description: "The size of the pages: `A0` to `A6` (`A4` is 210 by 297
millimetres), `LETTER` (8.5 by 11 inches) or `LEGAL` (8.5 by 14 inches)."
type: string
default: A4
+ enum: ["LETTER", "LEGAL", "A0", "A1", "A2", "A3", "A4", "A5", "A6"]
dependencies:
- "camel:pdf"
- "camel:kamelet"
diff --git
a/library/camel-kamelets/src/main/resources/kamelets/string-template-action.kamelet.yaml
b/library/camel-kamelets/src/main/resources/kamelets/string-template-action.kamelet.yaml
index ea14a4148..3604580ba 100644
---
a/library/camel-kamelets/src/main/resources/kamelets/string-template-action.kamelet.yaml
+++
b/library/camel-kamelets/src/main/resources/kamelets/string-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "String Template Action"
- description: Apply a String Template.
+ description: |-
+ Builds a new message body from a StringTemplate template, filling in
values from the incoming message.
+
+ Use it to turn data into text for people or for another system, such as
the text of an email or a small XML or JSON document, when you already have
StringTemplate templates. For simple templates, `mustache-template-action` is
an alternative; to reshape JSON into other JSON, `jslt-action` is often simpler.
+
+ Input: any body. The template sees the body as `<body>` and a header as
`<headers.name>`, for example `Dear <headers.customer>, your order <body> has
shipped.`
+
+ Output: the body is the text the template produced. The headers are
kept, and a `CamelStringTemplateResourceUri` header is added with the location
of the template.
+
+ Good to know: a header the template uses that is not set gives nothing
in the text. A template file that cannot be found fails the message. The
template is loaded from a file, the classpath or a URL given by the `template`
option; it cannot come from the message.
required:
- template
type: object
@@ -39,7 +48,7 @@ spec:
title: Template
description: "Where to load the StringTemplate template from, not the
StringTemplate template itself: `file://` followed by the path of a file,
`classpath://` followed by a resource in the application, or an `http://` or
`https://` URL."
type: string
- example: "file:////template.tm"
+ example: "file:///opt/templates/order.st"
pattern: "^(http|https|file|classpath|ref|bean)://.*"
dependencies:
- "camel:stringtemplate"
diff --git
a/library/camel-kamelets/src/main/resources/kamelets/velocity-template-action.kamelet.yaml
b/library/camel-kamelets/src/main/resources/kamelets/velocity-template-action.kamelet.yaml
index 1658ebc48..7e87edd85 100644
---
a/library/camel-kamelets/src/main/resources/kamelets/velocity-template-action.kamelet.yaml
+++
b/library/camel-kamelets/src/main/resources/kamelets/velocity-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
spec:
definition:
title: "Velocity Template Action"
- description: Apply a Velocity Template.
+ description: |-
+ Builds a new message body from an Apache Velocity template, filling in
values from the incoming message.
+
+ Use it to turn data into text for people or for another system, such as
an email, a report or a small XML or JSON document, when you already have
Velocity templates or need its loops and conditions. For simple templates,
`mustache-template-action` is an alternative; to reshape JSON into other JSON,
`jslt-action` is often simpler.
+
+ Input: any body. The template sees the body as `$\{body}` and a header
as `${headers.name}`, for example `Dear ${headers.customer}, your order
$\{body} has shipped.`
+
+ Output: the body is the text the template produced. The headers are kept.
+
+ Good to know: a value the template uses that is missing, such as a
header that is not set, stays in the text as written, for example
`${headers.customer}`; write `$!{headers.customer}` to get nothing instead. A
template file that cannot be found fails the message. The template is loaded
from a file, the classpath or a URL given by the `template` option; it cannot
come from the message.
required:
- template
type: object
@@ -39,7 +48,7 @@ spec:
title: Template
description: "Where to load the Velocity template from, not the
Velocity template itself: `file://` followed by the path of a file,
`classpath://` followed by a resource in the application, or an `http://` or
`https://` URL."
type: string
- example: "file:////template.vm"
+ example: "file:///opt/templates/order.vm"
pattern: "^(http|https|file|classpath|ref|bean)://.*"
dependencies:
- "camel:velocity"
diff --git
a/library/camel-kamelets/src/main/resources/kamelets/xj-identity-action.kamelet.yaml
b/library/camel-kamelets/src/main/resources/kamelets/xj-identity-action.kamelet.yaml
index 739cb2ba2..afd7547d6 100644
---
a/library/camel-kamelets/src/main/resources/kamelets/xj-identity-action.kamelet.yaml
+++
b/library/camel-kamelets/src/main/resources/kamelets/xj-identity-action.kamelet.yaml
@@ -31,14 +31,21 @@ metadata:
spec:
definition:
title: "XJ Identity Action"
- description: Apply the XJ Identity Transformation to transform JSON to XML
and XML to JSON.
+ description: |-
+ Converts each message from XML to JSON, or from JSON to XML, with a
fixed mapping and no template to write.
+
+ Use it to pass XML to a system that expects JSON, or the other way
round, when the default mapping is good enough. To control the result, such as
the names of the elements or which fields to keep, use `xj-template-action`
with an XSLT stylesheet.
+
+ Input: XML or JSON as text, bytes or a stream, as `direction` says.
Parsed JSON, such as a Map, fails the message.
+
+ Output: the body is JSON text or XML text. From XML, the root element is
dropped, its attributes and child elements become fields, repeated elements
become an array, and all values are text: `<order id="7"><qty>2</qty></order>`
gives `{"id":"7","qty":"2"}`. To XML, each JSON value becomes an `object`
element that keeps its name and type in `xj:name` and `xj:type` attributes,
such as `<object xj:name="qty" xj:type="int">2</object>`. The headers are kept.
required:
- direction
type: object
properties:
direction:
title: Direction
- description: The transform direction.
+ description: "Which way to convert: `XML2JSON` turns XML into JSON,
and `JSON2XML` turns JSON into XML."
type: string
enum: ["XML2JSON", "JSON2XML"]
dependencies: