As already described, Apama events are rigidly structured and need to comply with a precise event type definition. This describes the structure of a particular event: in particular its name, as well as the order, name, type and number of its constituent fields.

By contrast, external events, even when they are of the same "type" or nature (for example, all Trade events or News headlines) might vary in format and structure, even when originating from the same source or feed.

In order to accommodate this, Apama provides an optional payload field in Apama events. The payload field, typically the last field in an event type definition, can embed any number of additional optional fields in addition to the always-present primary fields.

For example, consider an external message that can appear in several guises, but where each always consists of a particular subset of critical fields together with a variable number of additional optional fields.

If it is desired that these varying guises are mapped to a single Apama event type, then this needs to be defined so that its fields correspond to the subset of critical (and always present) fields, followed by a payload field into which the additional (and optional) fields are embedded.

When so configured, the Semantic Mapper will transparently create a payload field in an event.

As described in Event mappings configuration, one of the attributes of the event-mapping element <event> is copyUnmappedToDictionaryPayload.

The copyUnmappedToDictionaryPayload attribute defines what the Semantic Mapper should do with any fields in the incoming messages that do not match with any field mapping, i.e. if there are no rules that specifically copy their contents into a field within the Apama event being generated.

If this attribute is set to false, any unmapped fields are discarded.

If this attribute is set to true, unmapped fields will be packaged into a payload field, called __payload, set to be the last field of the Apama event type generated by the Semantic Mapper.

Using copyUnmappedToDictionaryPayload puts all the payload fields in a standard EPL dictionary.