The main filter criteria parameter is the message_queue

• message_queue (required)
  Specify which device queues to look in and whether to retrieve uplink only, downlink only, uplink + downlink and the field sets to retrieve i.e. all meta data fields and payload or all meta data fields but no payload, etc.
  the message_queue parameter can be one of the enum:
  • “all_queues” – Search in all queues/storage and retrieve the uplink and or downlink messages.
    “pending” – Only retrieve from the device messaging queue holding the pending (undelivered) uplink and downlink messages.
  • “pending_uplink” – Only retrieve from the device messaging queue holding the pending (undelivered) messages, filter by uplink messages received from device
  • “pending_downlink” – Only retrieve from the device messaging queue holding the pending (undelivered) messages, filter by submitted messages waiting to be transmitted to device.
  • “shipped” – Only retrieve from the device messaging storage holding the successfully delivered uplink and downlink messages.
  • “shipped_uplink” – Only retrieve from device messaging storage holding the successfully delivered messages, filter by uplink.
  • “shipped_downlink” – Only retrieve from device messaging storage holding the successfully delivered messages, filter by downlink.
  • “failed” – Only retrieve from the device messaging storage holding the failed uplink and downlink messages that could not be delivered.
  • “failed_uplink” – Only retrieve from device messaging storage holding the failed messages, filter by uplink.
  • “failed_downlink” – Only retrieve from device messaging storage holding the failed messages, filter by downlink.
• fieldset:
  Each message record is made up of meta-data fields and payload fields totalling up to 100 fields for each message record. To enhance performance and avoid retrieving unnecessary bulky fields it is possible to specify using the “fieldset” parameter the exact fields to return or to specify to return all fields except payload (meta-data only) or retrieve the entire message record including payload.
  This fieldset parameter accepts the following fieldset profiles (each profile returns a pre-defined set of fields).
  • “all_fields” – This option will cause the complete fieldset of message records including actual payload to be returned. The max number of messages returned per requet/per page is 100.
  • “all_fields_except_payload”  – This option returns the complete field set except the payload (excludes payload.data). The max number of message records that can be retrieved with this option is 1,000,000 per request.
  • “msg_stats_1” –  This option will return key meta-data fields required for i.e. creating messaging usage charts/stats. It does not return actual payload but will return i.e. payload_size information. The max records that can be retrieved with this option is 1,000,000 per request. This is the default operation if none specified.
  • Specific fields – You may also specify the specific fields to return by supplying an array of required field names to be returned example: [“transaction_id”, “udid”, “payload.data”]
• group_by_queue
  Only applicable when the message_queue parameter is set to “all_queues”. When set to true the returned messages are grouped. For example the messages are grouped into the arrays: shipped_messages[], pending_messages[] and failed_messages[]. If set to false, the returned messages are returned without the grouping (flat structure). By default, the returned messages are grouped as described above.

The filter criteria can be further narrowed down to return message records matching a list of message transaction_id or narrow down to specific device with the following parameter:

• transaction_id_list (optional)
  Specify the actual messages to be retrieved by providing their transaction_id in an array list. A transaction_id is always returned as a response after each message submit from customer upstream application. And a transaction_id is generated for every message received from device for upstream delivery or storage.
• imsi – Restrict the queues/storage search to a specific device identified by the specified imsi
• udid – Restrict the queues/storage search to a specific device identified by the specified udid
• device_id – Restrict the queues/storage search to a specific device identified by the specified device_id
• device_ip – Restrict the queues/storage search to a specific device identified by the device’s IP address the device’s service_template_id.
• Service_access_point
  Restrict the queues/storage search to a specific SAP this option is only available to customers with private SAPs with access attempt loggin feature enabled. Where applicable this option  allows customer to retrieve all messages including failed access attempts and records of dropped messages to the specific private SAP. This filter option is can be very useful for troubleshooting and diagnostics.The device_ip may also be specified when using the SAP based filter to allow to narrow down to a specific device messaging and access attempts activities on the SAP.
• start_date
  Filter the messages to be retrieved by the specified start date i.e. return only newer messages. If no end_date specified with this parameter then only messages from within 1 hour timeframe of the specified start date will be returned.
• end_date (conditional)
  The time difference between start_date and end_date must be 7 days or less. The platform will only return maximum the first 7 days after specified start time even if longer end date specified.

/rawSubmit

• The /submit endpoint can be used to submit the payload and supplier device identifier, service access point, etc using the IoTGtw JSON structure. (the payload data parameter of the JSON remains opaque).
• The /rawSubmit endpoint can be used to submit payload with the actual payload posted as the request POST DATA (so entire message body is handled as opaque and will be transmitted to device as is. The device identifiers and other required parameters are to be provided in the request headers.

The messages are moved to the appropriate queue (Shipped Queue for successfully sent messages and Failed Queue for failed/expired messages) depending on the operation result.

The flush endpoint provides the capability to trigger a manual flush operation to flush all messages (uplink and downlink) from the “pending” queue to the submitted queue (completed) of a specific device object. The queue of a specific device to be flushed can be identified by the device identifier which are either (udid or imsi or device_id or device_ip + service_template_id).

Alternatively, specific message(s) can be flushed from the “pending” queue of one or more devices by specifying only the transaction_id(s) in the transaction_id_list array parameter.

Note: Flush operation should be understood as a manual request to (force) move message(s) from the “pending” queue to “submitted” queue.

The submitted payload is broadcasted to the messaging queues of all the IoT devices in the specified service template. When the payload is submitted into each device messaging queue it is processed as described in the /submit endpoint.