An Upstream Application Profile (messagingEndpoints API) is used to define the target application for delivering the IoT message received from device (uplink messages) as well receiving downlink messages to be delivered to the device. Typically the customer target application (upstream application) are in the customer data centre or hosted in the cloud.
An upstream application profile must be configured with the relevant access and credentials parameters valid/accepted on the customer (cloud) application to successfully exchange cloud to device and device to cloud messages.
The upstream application profile in addition serves as the permitted customer application to submit (downlink) messaging data to the customer device via the portal or using the messaging APIs..
A wide variety of upstream applications types are supported for example:
- RESTful APIs
- MQTT or RabbitMq
- AWS SQS
- AWS IoTCore
- Azure IoThub
- SMS/SMPP
- direct to NoSQL Database (please contact us)
See also: Upstream Application Message format documentation.
A device service profile is the entity that binds the defined upstream application profile to a device. Each device is bound to a service profile. In a servce profile configuration, a pre-defined Upstream Application profile can be assigned as the primary upstream application and another upstream profile can be assigned as the Backup upstream application in case the primary is not available. More info on geo-resillient data routing here.
Messages received from the device are sent to the Upstream application endpoints defined in the upstream application profile. Assigning an upstream application profile to a service profile is not mandatory. In fact, defining an Upstream Application is entirely optional if you are only using the IoT Message storage services or the Instant Device Management Service..
Splitting Messages to Upstream Applications
The platform supports instant integration to well known cloud services such as RabbitMQ, AWS cloud workloads, Microsoft Azure IoThub, Telco SMS Gateways/SMSC, any customer bespoke applications and microservices using REST APIs and more.
The platform provides the capability to split/route data to different upstream applications based on rules defined in the device service profile. For example Pre-defined Upstream Application profiles can be set in the Service profiles as the destination for IoT messages received from device on certain Service Access Points or based on the Message Type Indication (mti) parameter in the device message (supplied with SimplyTiny, Custom JSON, Azure IoT JSON, etc), Please refer to SimplyTiny / Split Traffic Routing for more information.
Message Delivery Methods and Formats
The message format structure (data framework/resource model) used in conveying messages between the platform and an upstream application can be either SimplyTiny JSON, Azure IoT Resource Model, BLOB/Opaque, etc. The format used is dependent on the Upstream target Application and or the Upstream Data Framework configuration settings on the Upstream Application Profile. For more information and sample messages please refer to the Upstream Application Message format documentation.
Additional Notes:
RESTful API
- Specify your upstream application RESTful API endpoint information
- The upstream application details are i.e.: IP/hostname/URL, port, authentication method, and credentials required to successfully connect and deliver IoT data to your upstream application.
- Specify your upstream application RESTful API endpoint (web hook) to push notification events to
- Notification events are for example: error notification, message sent notification, delivery confirmation notification, device connect, disconnect, wake-up notifications etc.
- The upstream application details are i.e.: IP/hostname/URL, port, authentication method, and credentials required to successfully connect and deliver notifications to your upstream application.
Inbound Messaging (Receiving downlink data from your application for delivery to your IoT device)
- Define which upstream applications are allowed to use the Messaging API services to perform messaging operations such as message submit for onward delivery to device and message storage query, message retrieve, etc.
- Pre-define the details about your upstream application that should be allowed to perform Inbound Messaging API operations. For additional security, IP white-list enforcement can also be enabled to allow only specific IP addresses of your upstream application to perform Messaging API call using this specific Messaging Profile.
- When making an inbound API call, the Messaging Profile Id (messaging_endpoint_id) with which to authenticate the request must be specified and is part of the URI parameter. Refer to the Messaging API samples documentation for more information.
Upstream Service (MQTT, AWS SQS, AWS IoTCore, Azure IoThub, SMPP, ..)
The integration using the remaining protocols are quick, easy and self explanatory. All you need to do is:
Define a new profile
- Define a new upstream profile (specify a name for it)
- Specify your upstream application type and connection details
- And you are good to go
Please refer to the Device Management Services for additional information on (Azure IoThub) Device Management Upstream profiles.
Note: The IoTGtw cloud service performs the necessary protocol transformations to enable data to be transmitted between the customer devices using any of the supported device protocols and the configured customer upstream application protocols.