“state”
Set to false to disable this service template this will disable uplink and downlink messaging transmission functions and any uplink or downlink message submit attempt will be rejected.
“service_template_id”
This field is used to specify the unique id with which this service template will be identified on the customer account.
“Messaging Endpoint Profile”
This is the list of pre-configured data endpoints profile which specifies the target upstream application for the messages received from devices attached to the service templates. The fields are optional. If defined the primary profile will be used first, if not available the service will fall back to the secondary profile.
“Service Access Point Permitted”
This field is used to indicate whether to restrict all devices that are associated to this service template to the specifically selected shared or customer dedicated private service access points (SAPs). Leave the field unselected to allow devices of this service template to use any of shared or private SAPs available to your account.
“Device Idle Threshold”
This field is used to set how long device can be idle (since its last uplink/downlink activity) before it is considered as no longer reachable (for example in deep sleep / power saving mode). When a downlink submit message is received, if the message is received within the set threshold period then the message is pushed to the device (device is considered still available). If received outside the idle period then the message is queued until next device wakeup detected. The “Notify on Wakeup” Notification service also relies on this timeout to determine whether a device had been in idle to trigger a new wakeup notification event.
Always Reachable Devices
The Device Idle Threshold field is also used to configure devices of the service template as always reachable devices ready to receive incoming downlink messages at any time and in principle never never go into deep-sleep /switch-off mode. Instant message delivery can be setup for this type of devices as follows:
- In the Service Template set the Device Idle Threshold to 0
- Ensure your current subscription includes high priority messaging service (Priority 1 messaging or Priority 2 Messaging Addon)
Refer to Instant Message Delivery doc for more details about configuring instant delivery.
“Max Msg Per Wakeup”
Indicates the maximum number of messages that may be pushed to a device during each wakeup period. For example if there are 40 downlink messages waiting in the queue prior to device wakeup, if this field is set to 10 then 10 messages based on message priority, queue entry time and SAP restriction settings are earmarked for transmission to the device. The earmarked messages are then transmitted in a controlled way to the device based on the “Delivery Burst” settings.
“Delivery Burst”
This feature provides a flow control mechanism to avoid flooding the device with high volumes of messages (to protect IoT devices that cannot handle such burst). If set to “Concurrent Delivery” all messages ready to be transmitted to the device are simultaneously transmitted to the device.
The option “Wait for Ack. Delivery” is used to indicate to send one message at a time and wait for an ACK response from the device before sending the next downlink message. However this only kicks in if the protocol used supports message acknowledgements and the message acknowledgement service is enabled.
The “X Seconds Interval Delivery” is used to space out the transmission of the downlink messages with set a interval without requiring any ack from the device.
“Delivery Priority”
The delivery priority field is used to set a the max allowed priority for submitting messages to the devices in the service template. The set priority must be within the subscription allowance. The delivery priority field also acts as the default priority to be used when no priority is indicated for a message submited request.
The Delivery priority field can be set to be equal or lower (lower = higher numerical value) than the subscribed priority. If a message is submitted to a device of this service template but with a better priority than the service template allows, the priority is overwriten to the service template value.
Note: Priority 3-n can be used freely and are mainly relevant for message ordering in the device “Pending” Queue. Messages submitted with Priority 1 (highest) or 2 (next best) get routing priority and are delivered instantly if device is awake or always-on.
“Event Notification Service”
This service must be enabled to use the notifcation services. If disabled all notification services (Notify on Delivery, Notify on Error, Notify on Wakeup, etc) will become inactive for this service template.
If this service is not part of your subscription the message [Not Subscribed] will be shown in the field name. Please upgrade your subscription or add the Event Notification Service addon if you see this message and requiire any of the notification services listed below..
“Notify on Msg Sent”
Indicate whether to send out an outbound notification event when a messages has been transmitted to a the device. For example this is useful for devices that do not support acknowledgement and or devices that go to deep sleep for along period of time, your application workflow may require this hook in order to be informed when a queued message has been finally transmitted to the device.
“Notify on Msg Delivery”
Indicate whether to send out an outbound notification event when a transmitted downlink message has been acknowledged by the device.
“Notify on Wakeup”
Indicate whether to send out an outbound notification event when an uplink event is detected from a device that was previously in idle state (see device idle threshold).
“Notify on Connect”
Only applicable for radius enabled accounts. Indicate whether to send out an outbound notification event when a device previously disconnected has established a new connection / successfully authenticated.
“Notify on Disconnect”
Only applicable for radius enabled accounts. Indicate whether to send out an outbound notification event when a device previously connected has closed/lost its connection and or when the connection is considered no longer valid and closed.
“Notify on Error”
Indicate whether to send out an outbound notification event when an error occurs for an uplink event i.e. an uplink message from the device could not be delivered to the data endpoint configured on this service template, or device validation failed, device attempts to use SAP not permitted, for managed_tls and dtls services if device certificate validation fails, etc.
“Events Storage Service”
This services requires that you have the event_notification_service enabled on your account. By default the notifications events generated and sent to your application endpoints are not stored in the device queues. The event storage service adds the capability to store the notification events. The event related to each device will become visible in the device shipped queue or failed queue depending on whether the notification was successfully delivered.
“Payload Limit Per Message (Bytes)”
Restrict the payload size of messages for the devices in this service template. The value must be equal or lower to the account max payload subscription allowance. Messages submitted to/from devices with payload size greater than the set value will be dropped.
“SimplyTiny – Default Field Seperator”
This field can be used to specify the default char to use as header field seperator when constructing a downlink SimplyTiny message.
In the uplink direction, devices using the SimplyTiny message may use any of the valid header field seperator listed in the drop down list. The IoTGtw service will auto-detect the seperator based on the SimplyTiny usage guidance. The detected seperator is also used for constructing an ack response to the received message if applicable.
“Enable Device Initiated Auth Token Update”
To allow devices in this service template to initiate a device authentication token updated request this field must be set to true. If the devices are not allowed to perform such operation then set this field to false. The device authentication token update requires the use of SimplyTiny message.
“Permit Downlink Connection Establishment”
This field is used to indicate whether to permit the IoTGtw service to establish a connection to the device when the device is detected to be awake and there are messages in the queue to be pushed to the device and the current connection is not valid or closed. If permitted a new socket is initiated to the device in order to transmit the pending messages. If set to false then only device initiated connections will be used for delivering messages to the device.
“Messaging Acknowledgement Service”
This service is used to specify whether to allow messsage acknowledgement to be sent to devices that use one of the supported ack capable transmission method / framework.
If this service is not part of your subscription the message [Not Subscribed] will be shown in the field name. Please upgrade your subscription or add the messaging ack service addon if you see this message and requiire the messaging ack service.
“Payload Encoding/Decoding”
This service provide the capability to transform payload to/from deivce between base64, UTF8, ASCII, Hex independently for the uplink and downlink flows between the Device and the IoTGtw Cloud Service (leg 1) and the uplink and downlink flows between IoTGtw and the Customer upstream application (leg 2) The charr set encoding to use for each leg of the flow can be set independently to match your upstream application and device requirements.
The default encoding is UTF8 for both legs.
“Metadata Storage Service”
The Metadata Storage Service can be used to set a tailored message retainment policy for all messages partaining to the devices of the service template.
If meta data storage is set to disabed or if the service is not part of your subscription package/addon then device messages including payload will be retained.
“Metadata Storage Retainment Hours”
If the Metadata storage service is enabled then this field can be used to specify the length of time the device messages should be retained. The policy can be set such that message is stored permanently, destroyed immediately or stored temporarily for a set period before it is destroyed. In any case the set time must be within your subscription allowance.
“Payload Storage Service”
This service requires the “Metadata Storage Service” service to be enabled.
The Payload Storage Service can be used to set a tailored retainment policy specific to the message payload of the devices of the service template. By default Message content data (payload) is destroyed after message delivery.
If payload storage is set to disabed or if the service is not part of your subscription package/addon then message payloads will not be retained after they are transmitted (uplink/downlink).
“Payload Storage Retainment Hours”
If the Payload Storage Service is enabled then this field can be used to specify the length of time message payloads should be retained. The policy can be set such that message payload is stored permanently, destroyed immediately or stored temporarily for a set period before it is destroyed. In any case the set time must be within your subscription allowance.
“Message Queueing Service”
Enable/Disable the Message Queueing service to allow message to devices that are currently not reachable i.e. device in power saving mode to be queued and transmitted to the device when the device is detected to be awake.
“Message Queueing Duration Minutes”
This field can be used to control for how long a message should be queued before expiriing the message. Expired messages are popped out of the device “Pending” messages queue and are moved to “Failed” storage. This ensures that out of date messages are not needlessy transmitted to the device and maintain maximum performance.
A message submitted to the device with a max queue duration higher than what is set on the device template will be reset to the value set on the service template.
The specified queue duration on the service template must be within the current subcription allowance.
“Custom Attribute List”
The service template parameter (custom_attribute_list) allows customer to specify additional attributes to augment to the standard list of attributes sent in uplink message delivery. In addition to the standard attribute name/value list supplied to upstream applications, the following additional attributes can be included in the message under the “custom_attribute” tag name. For more information on the standard and custom attribute list, please refer tot the Upstream Application Message Format description.
“Device Bootstrap Service”
Enable the devices of the service template to perform bootstrap operations.
For security reasons each device object must be explicity set to be in bootstrap mode for a bootstrap request to be accepted.
Bootstrap is permitted if the device bootstrap service on the service template is set to 1 or 2 AND if the device object is also set to bootstrap mode is true.
On receiving a bootstrap request from a device, the service will check if the device service template is in bootstrap mode 1 or 2, then check if the device is in bootstrap mode. If one of both settings is not in bootstrap mode the request is ignored. If in bootstrap mode, the platform will respond with a message containing the bootstrap settings.
- 0 = bootstrap disabled
- 1 = On valid bootstrap request from device, supply device udid and auth token id
- 2 = On valid bootstrap request from device, supply device udid, token id and SAP list.
The SAP list transferred back as part of the bootstrap response (mode 2) can be restricted by the “Service Access Point Permitted” settings (see description above).
The service template level bootstrap control allows the user to easily disable bootstrap for all devices of the service template quickly if no longer needed.
“Message Broadcast Service”
Enable message broadcast service to accept message broadcast request (via broadcast messaging API) to submit a message to be broadcasted to all devices of the (service template).
“Radius Authentication Service”
Provides the capability to authenticate and explicitly issue access-grants (access-accepts) based on the device/service template radius configuration during the device network session setup (prior to accessing the SAP). The radius service also provides benefits of retrieving additional information such as network information, location, allocation of static IP address to devices and auto-detecting dynamically allocated IP address by the device network such as cellular networks, etc.
Customers or network partners such as (Cellular operators) with dedicated IoT APNs to IoTGtw service can make use of the radius authentication service
“Device Assisted Ack (Message Acknowledgement)”
Devices Assisted Ack provides a simple and efficient message acknowledgement capabilities for IoT devices/applications that use protocols such as UDP that do not natively support message acknowledgement. Device Assisted Ack is also a great way of providing simplification of application level message acknowledgment for IoT devices that use UDP, TCP, etc.
Device Assisted Acknowledgement Service is applicable to raw UDP (or even TCP) Private SAP. This type of SAP are used by devices that do not support one of the common application data framework such as MQTTSN, CoAP, SimplyTiny etc. The Device Assisted Ack service provides the capability to generate response messages based on the configured rules to echo back specific string or the packet length of the received uplink message to inform device that its uplink message was received.
- String-Value: This ack method allows you to define a static string to send as the ack response i.e. when device receives the ack message it will know that its previous uplink transmit was successfully received.
- Content-Length: This ack to echo back the payload length of the received message.