branch

BETA: This component is experimental and therefore subject to change outside of major version releases.

The branch processor allows you to create a new request message via a Bloblang mapping, execute a list of processors on the request messages, and, finally, map the result back into the source message using another mapping.

# Config fields, showing default values
branch:
request_map: ""
processors: []
result_map: ""

This is useful for preserving the original message contents when using processors that would otherwise replace the entire contents.

Metadata

Metadata fields that are added to messages during branch processing will not be automatically copied into the resulting message. In order to do this you should explicitly declare in your result_map either a wholesale copy with meta = meta(), or selective copies with meta foo = meta("bar") and so on.

Error Handling

If the request_map fails the child processors will not be executed. If the child processors themselves result in an (uncaught) error then the result_map will not be executed. If the result_map fails the message will remain unchanged. Under any of these conditions standard error handling methods can be used in order to filter, DLQ or recover the failed messages.

Conditional Branching

If the root of your request map is set to deleted() then the branch processors are skipped for the given message, this allows you to conditionally branch messages.

Fields

request_map

A Bloblang mapping that describes how to create a request payload suitable for the child processors of this branch. If left empty then the branch will begin with an exact copy of the origin message (including metadata).

Type: string
Default: ""

# Examples
request_map: |-
root = {
"id": this.doc.id,
"content": this.doc.body.text
}
request_map: |-
root = if this.type == "foo" {
this.foo.request
} else {
deleted()
}

processors

A list of processors to apply to mapped requests. When processing message batches the resulting batch must match the size and ordering of the input batch, therefore filtering, grouping should not be performed within these processors.

Type: array
Default: []

result_map

A Bloblang mapping that describes how the resulting messages from branched processing should be mapped back into the original payload. If left empty the origin message will remain unchanged (including metadata).

Type: string
Default: ""

# Examples
result_map: |-
meta foo_code = meta("code")
root.foo_result = this
result_map: |-
meta = meta()
root.bar.body = this.body
root.bar.id = this.user.id
result_map: |-
root.enrichments.foo = if errored() {
throw(error())
} else {
this
}

Examples

This example strips the request message into an empty body, grabs an HTTP payload, and places the result back into the original message at the path repo.status:

pipeline:
processors:
- branch:
request_map: 'root = ""'
processors:
- http:
url: https://hub.docker.com/v2/repositories/jeffail/benthos
verb: GET
result_map: root.repo.status = this