URL Encode

Convert

Synopsis

Percent-encodes a string so it can be carried safely inside a URL. Arrays of strings are encoded element by element.

Schema

- urlencode:
    field: <ident>
    space_as_plus: <boolean>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>
    target_field: <ident>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
field	Y	-	Field containing the string, or array of strings, to encode
space_as_plus	N	false	Encode a space as + instead of %20
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	See Handling Failures
ignore_missing	N	false	If true, quietly exit if field doesn't exist
on_failure	N	-	See Handling Failures
on_success	N	-	See Handling Success
tag	N	-	Identifier
disabled	N	false	When true, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration
target_field	N	field	Field to store the encoded value. Defaults to field, encoding in place

Details

The space is the only difference between the two modes, and it is the setting that matters. Query-string encoding traditionally writes a space as +, while path segments and most modern APIs expect %20. The default is %20, which is safe in both positions; set space_as_plus: true only when the receiving system specifically expects the older form.

Everything else is encoded the same way in both modes: reserved and non-ASCII characters become percent-escapes, and unreserved characters are left alone.

An array of strings is encoded element by element and stays an array. Any other value — a number, an object, a mixed array — is an error.

This processor is the inverse of URL Decode.

Examples

Encoding a Query Value

Making a search term safe to place in a URL...	{ "term": "user id=42 & status=active" } - urlencode: field: term target_field: term_encoded
with spaces as %20:	{ "term": "user id=42 & status=active", "term_encoded": "user%20id%3D42%20%26%20status%3Dactive" }

Form Encoding

Where the receiver expects the older query-string form...	{ "term": "failed login" } - urlencode: field: term space_as_plus: true target_field: term_encoded
spaces become +:	{ "term": "failed login", "term_encoded": "failed+login" }

Encoding an Array

Every element of a string array is encoded...	{ "tags": ["needs review", "high/priority"] } - urlencode: field: tags
and the result stays an array:	{ "tags": ["needs%20review", "high%2Fpriority"] }