Field mapping

Every input ships with a field mapping: the rules that turn a raw SAP API response into the flat event that is sent to Splunk or Dynatrace. The mapping says where each value is read from, what type it is, and what the field is called in the output.

The built-in mappings cover the standard fields of each API. You only need to edit a mapping when you want something the default does not give you - typically a custom header, a custom field added to an SAP object, or different field names to match an existing index.

Edit it in the UI under Inputs → your input → Mapping

How a mapping is applied

Three things are worth knowing before you change one.

A mapping is an allow-list. The output event contains only the fields the mapping produces. Anything in the API response that is not mapped is discarded - so if you remove a row, you stop indexing that field.

Your mapping replaces the default, it does not merge with it. When you open the Mapping tab the table is pre-filled with the input's built-in mapping; saving stores the whole table. Add to it rather than starting from scratch, and use Reset mapping to go back to the shipped version.

Mapping runs first. Every other transform - lookups, replace-fields, parse-JSON, MD5, add-fields, the timestamp field runs after mapping.

A mapping row

Each row in the Mapping tab is one field:

Rows are applied in order and the last row that produces a value wins, so two rows can write to the same destination - useful for fallbacks. A row whose source is missing writes nothing at all, so it never clobbers an earlier row.

The examples below all run against this response (an SAP CPI message processing log,
abbreviated):

{
  "MessageGuid": "AGj4nLbR",
  "Status": "FAILED",
  "LogStart": "/Date(1726000000000)/",
  "IntegrationArtifact": { "Id": "OrderReplication", "Name": "Order Replication", "Type": "IFlow" },
  "ErrorInformation": { "ErrorMsg": "Connection refused", "LastErrorModelStepId": "CallActivity_12" },
  "CustomHeaderProperties": [
    { "Name": "orderId", "Value": "4711" },
    { "Name": "region",  "Value": "EU" }
  ],
  "Runs": [
    { "Id": "r1", "OverallState": "COMPLETED", "ChildCount": 3 },
    { "Id": "r2", "OverallState": "FAILED",    "ChildCount": 9 }
  ]
}

Source path syntax

There are four forms of source path. Which one is used is decided by what the path
contains, in this order:

Notes and limits:

• A plain field name is matched exactly, including case. Spaces are fine -
  Object Type is a valid source field.

• A dot path walks nested objects only. It cannot index into an array: Runs.0.Id
  and Runs[0].Id both fail. Use a JSON path for that.

• The name[0] form only works on a top-level array and only with a simple name. For anything deeper use a JSON path: $.IntegrationArtifact.Tags[0].

• The form is chosen by the characters in the path, so a field whose real name contains
  a . or a $ cannot be addressed at all - the name is read as a path. Such a field has
  to be reached through its parent, e.g. with $.Parent.* or a List row on the parent.

JSON path

Use a JSON path whenever you need to reach into an array - pick an element, pick across all elements, or select an element by one of its values. A path that cannot be parsed, or that points at nothing, yields no value rather than an error, so a mistake shows up as a missing or empty field in the event and not as a failed collection. Always confirm a new path with Test Input.

Supported

Inside a filter, @ refers to the element being tested. @.Name and @Name both work. A filter also works over an object whose children are objects, not only over an array. The children are tested the same way.

Not supported

Filters and wildcards return a list

[*], [?(…)] and .. always produce a list of matches, even when exactly one
element matches:

So: use String when the match is a single value you want as a scalar, and List when you genuinely want an array. With any other type a filtered value arrives in the index wrapped in an array, which is rarely what you want.

Types

Two places care about the type beyond conversion:

• Timestamp. The Timestamp tab picks the field that becomes the event time, and offers @current_time plus the Date fields of the input's built-in mapping. A newDate field you add under a name of your own will not appear in that list. To use one as the event time, set it over the API, or write your value to the destination name the input already uses for its timestamp.

• List. Only List triggers the nested mapping described next.

What Date accepts

Two consequences to watch for:

• A date without a Z is passed through as text, so it will not be a usable timestamp
  in the index. There is no format option in the mapping; either let the input's own handling deal with it, or map it as String and accept that it is text.

• A string of digits is always read as milliseconds. An API that returns epoch seconds as a string therefore lands in 1970. It needs a numeric field, orEpochMillis/EpochNanos where the unit matches.

Nested objects and arrays

A row with type List keeps the nested structure. What happens to the fields inside it depends on whether the mapping has a step with the same name as the source field.

Without a matching step the nested objects are passed through untouched, with the
field names SAP returned:

{ "runs": [ { "Id": "r1", "OverallState": "COMPLETED", "ChildCount": 3 }, … ] }

With a matching step each element is mapped by that step, so the inner fields get
renamed and typed too. In the UI each step is a tab inside the Mapping tab; the first tab
is the top-level step and the others are named after the source field they map:

Tab MessageProcessingLog (top level)

Tab Runs

{ "message_guid": "AGj4nLbR",
  "runs": [ { "id": "r1", "state": "COMPLETED" }, { "id": "r2", "state": "FAILED" } ] }

Steps can nest further - a List row inside the Runs step can point at a Steps step - and a step also works when the source is a single object rather than an array.

Two restrictions:

• A step is found by the List row's source name, so that source has to be a plain
  field name (or dot path). A JSON path such as $.Runs[*] does not resolve to a step
  named Runs; the elements are passed through unmapped.

• Inside a step, the source fields are the raw SAP names of the nested object, not the
  destination names of the level above.

Empty values

Omit if empty (version 9.2.0 onwards) (skip-empty) controls what happens when a source yields nothing usable: an empty list - which is what a JSON path filter returns when nothing matches - or
a blank string.

Without it, an unmatched filter still writes a field, and with type String that field is an empty string:

Tick it for any field that is only present on some events, and always tick it when a filtered row is a fallback for an earlier row - otherwise the empty result overwrites the good value. A source field that is simply absent is skipped either way; the flag is about values that are present but empty.

Use cases

Promote a custom header to a top-level field

The one most customers want. CPI custom header properties arrive as a list of name/value pairs, which is awkward to search. Pull the one you care about out into its own field:

{ "order_id": "4711" }

Add one row per header you want promoted. Keep the original CustomHeaderProperties row
as well if you still want the full list indexed.

Use a business key as the trace/correlation id, with a fallback

Two rows to the same destination: the technical id first, the business key second so it wins when present. Omit if empty on the second row is what makes the fallback hold.

With the header present: {"trace_id": "4711"}. Without it: {"trace_id": "AGj4nLbR"}.

Flatten a nested object

Match your existing index's field names

Only the Destination Field column changes - point the same sources at the names your dashboards and correlation rules already use. A dotted destination builds the nesting a target platform might expect:

{ "error": { "message": "Connection refused" } }

Summarise a list into one searchable field

{ "run_ids": "r1, r2" }

Flag events by a condition in a nested list

Record which elements met a condition, not just that some did:

Parse a JSON string field

Some SAP APIs return a details field containing JSON as text. Parsed into real structure,
its keys become searchable fields instead of one long string; text that is not valid JSON
is kept as-is rather than dropped.

In the UI, map the field normally and add parse-json for the destination name on the
Transforms tab:

Over the API the mapping can do it in one step, with type Json:

{ "src": "DETAILS", "type": "Json", "dst": "details" }

Pick a value out of a deeply nested response

When the value is always called the same thing but its position varies, recursive descent saves you from spelling out the path:

Use it deliberately: it matches the field at every depth, so if more than one object in the response has it, a String result is all of them joined together.

Reduce event size

Delete the rows you do not need - large payload and attachment fields are the usual candidates. Nothing you remove is indexed, which is the cheapest way to cut volume.

Testing a mapping

Use the Test Input tab on the input. It runs a real collection and applies the full transform chain -mapping included - returning the first few events exactly as they would be indexed. This is the fastest way to confirm a JSON path matches, and the only reliable way to check a filter against real data.

If a field is missing from the test output: