# 7. Content Messages

AMPS provides three types of message that contain message content

- `publish` messages return data from a topic as it is published, in order, whether the data is being published live, or is the result of a replay
- `sow` messages return data from a SOW query. These messages return the state of messages that are current as of the time for the query. By default, the messages are returned without regard to the order in which the messages were published. A query can specify the order of the returned messages based on the data within the message by including the OrderBy header on the SOW query.
- `oof` messages indicate that a content message no longer matches a subscription. These messages are sent to a client in order.

## publish message

### Description

AMPS returns a `publish` message to a client when a new message is published to AMPS that matches one of the subscriptions requested by the client. There are two ways that AMPS can generate publish messages:

- Single-origin messages. For subscriptions to topics where AMPS can identify a single source for a publish message, AMPS provides information from that publish message to the subscriber. This applies to subscriptions to unpersisted topics, SOW topics, and conflated topic replicas. This does not include subscriptions to views (or conflated topics based on views), since views provide the ability to join multiple topics and aggregate over multiple messages. For conflated topic replicas, the header information provided is the information provided with the message published to the subscriber. For messages produced by delta publish, AMPS will use the information provided on the delta publish except as noted in the table below.
- Synthetic messages. In some cases, AMPS must provide a message that is constructed by the server. This happens for views, and for status messages from AMPS.

AMPS provides different values in the header fields depending on the origin of the publish message. For synthetic messages, AMPS does not provide information on the origin of the message, since there may be multiple sources of the message or, in the case of status messages, no external source. Likewise, AMPS does not provide a `CorrelationId`, since that header is set by the publisher for a specific message.

### Header Fields

Table 7.1 contains the header fields returned in a `publish` message.

Field | Description
--- | ---
`Command` | Type of message. Always `publish`, as encoded by the protocol.
`Topic` | The topic the message was published to.
`CorrelationId` | A publisher-provided string that is passed, verbatim, to subscribers. If this header is not present, or the message is a synthetic message as described above, subscribers receive no value for the `CorrelationId`. The contents of this header must consist of characters that are legal in Base64 encoding. For delta publishes, AMPS uses the `CorrelationId` of the delta publish if one is present. If no `CorrelationId` is present on the publish, AMPS uses the `CorrelationId` of the existing message, if one is present. If there is no `CorrelationId` on the publish, and there is no `CorrelationId` for the existing message, AMPS does not provide a `CorrelationId`.
`UserId` | The `UserId` of the client that published the message. An authentication module may choose whether to allow subscribers to receive this information.
`SubIds` | The set of subscription IDs that produced this message. When a message matches multiple subscriptions, AMPS may produce a list of subscription IDs for all matching subscriptions. This header is provided by AMPS. The AMPS Clients process this list and provide a single SubscriptionID for each message provided to message handlers.
`Bookmark` | The bookmark assigned to this message, if the message was persisted to a transaction log.
`TransmissionTime` | An ISO-8601 datetime that notes the time the message was processed by this instance of AMPS. The header is included if the client requested a `timestamp` for the subscription.
`LeasePeriod` | For messages received from a queue, the ISO-8601 datetime that indicates when the lease expires.
`SowKey` | If the message was from a topic that uses a SOW, the message includes the `SowKey` that AMPS uses to uniquely identify the message within the SOW.

Table 7.1: Header fields returned in a publish response

## sow message

### Description

The `sow` message returns a record from the SOW. For more information, see the State of the World and SOW Queries chapters in the AMPS User Guide

### Header Fields

Field | Description
--- | ---
Command | Type of message. Always `sow`, as encoded by the protocol.
    Topic
| The topic from which the records were produced.
`SowKey` | An AMPS-created identifier for this message.
`BatchSize` | The number of records returned in a single `sow` batch.
`Timestamp` | The time at which AMPS generated this message.
`QueryId` | The QueryId of the query that produced this message.
`MsgLen` | The length of the first SOW message in the data portion of this message.

Table 7.2: Header fields supported by sow

### Data

The `sow` message contains data. The data for the message consists of up to `BatchSize` messages, formatted as expected by the protocol. Each message contains its own header, with the following fields:

Field | Description
--- | ---
`SowKey` | An AMPS-created identifier for this message.
`CorrelationId` | A user-provided string that will be passed, verbatim, to subscribers. If this header is not present on the SOW record, subscribers receive no value for the `CorrelationId`. The contents of this header must consist of characters that are legal in Base64 encoding.
`MsgLen` | The length of the next SOW message in the data portion of this message.

Table 7.3: Header fields for messages in sow data

## oof message

### Description

The `oof` message indicates that a previously-received message is no longer in focus. For more information, see the State of the World and SOW Queries chapters in the AMPS User Guide

### Header Fields

Field | Description
--- | ---
`Command` | Type of message. Always `oof`, as encoded by the protocol.
`Topic` | The topic which contained the message that has gone out of focus.
`SowKey` | An AMPS-created identifier for the message that has gone out of focus.
`Reason` | The reason the message has gone out of focus. Valid reasons include `deleted`, `expired`, `match`, and `entitlement`.
`SubIds` | The Subscription Ids of the subscriptions that produced this message. The AMPS clients will provide this message to the handler registered for each of the subscriptions specified.
`CorrelationId` | A user-provided string that will be passed, verbatim, to subscribers. If this header is not present on the SOW record that was deleted, subscribers receive no value for the `CorrelationId`. The contents of this header must consist of characters that are legal in Base64 encoding.

Table 7.4: Header fields provided in oof

### Reason

The `reason` field of the `oof` message explains why the message no longer matches the subscription. Possible values are:

Reason | Description
--- | ---
`deleted` | The message was deleted.
`expired` | The message expired.
`match` | The message no longer matches the filter for the subscription.
`entitlement` | The changed such that the user no longer has permission to receive the message.

Table 7.5: Reason codes provided for oof

### Data

The `oof` message contains the updated message that caused the message to go out of focus, except if the reason is `entitlement`.