# Unflatten

## Purpose

`<result> = unflatten(<source-tree>, <key-separator-character>);`

This function unflattens keys in a JSON object. It provides a way to expand dot-separated fields.

It allows for instance to produce this:

  `{ "source": { "ip": "1.2.3.4", "port": 443 } }`

from this source data:

  `{ "source.ip": "1.2.3.4", "source.port": 443 }`

## Example

Here is a sample use case:

    module(load="fmunflatten")

    # Say you have the following tree, obtained for instance with mmnormalize.
    set $!source.ip = "1.2.3.4";
    set $!source.bytes = 3258;
    set $!source.geo.country_iso_code = "FR";
    set $!destination.ip = "4.3.2.1";

    # Now unflatten the keys in the $! tree.
    set $.unflatten = unflatten($!, ".");

    # You may do this to set back safely the result in $! because the function could
    # return a default dummy value of 0 (rsyslog number) if $! was not touched (it
    # would evaluate to an empty rsyslog string, which is not a JSON datatype).
    if (script_error() == 0) then {
        unset $!;
        set $! = $.unflatten;
        unset $.unflatten;
    }

An output of `$!` would give this, in pretty-print:

    {
      "source": {
        "ip": "1.2.3.4",
        "bytes": 3258,
        "geo": {
          "country_iso_code": "FR"
        }
      },
      "destination": {
        "ip": "4.3.2.1"
      }
    }

See also

Help with configuring/using `Rsyslog`:

- Mailing list - best route for general questions

- GitHub: rsyslog source project - detailed questions, reporting issues that are believed to be bugs with `Rsyslog`

- Stack Exchange (View, Ask) - experimental support from rsyslog community

See also

Contributing to `Rsyslog`:

- Source project: rsyslog project README.

- Documentation: rsyslog-doc project README

Copyright 2008-2020 Rainer Gerhards (Großrinderfeld), and Others.