Workflow Messaging
Workflow Messaging Overview
The workflow messaging system has two integration points: (a) WMC for initiating messages to be delivered to the mobile, and (b) ESS for delivering transaction events back to integration. The Qualcomm Service Portal defines the web services used to convey returning event notifications. For more information on how to use these services, please refer to ESS documentation here.
For interacting with workflow, use the WMC SOAP WSDL described here.
This document addresses the overall messaging architecture, the WMC messaging interface, the sequence of specific transactions, and how to handle error situations.
The diagram below covers all the endpoints and message flows that make up WMC messaging. Messages originating from dispatch will use the WMC::send() interface for delivery. Message status is conveyed back through ESS transactions T.6.01.0 and T.6.02.0. Messages originating on the mobile return as T.6.03.0 transactions. Some types of messages dispatched with send() will result in all three transaction types, especially if the forward message type requires anything more than status back from the mobile, or if an mobile error occurs during processing.
Best Practice Message Integration
Workflow mobile messages are defined in a canonical format that can be translated to a generic, hierarchical name/value pair format that is consumed by the mobile workflow engine. Work with Qualcomm Professional Services to get an XML Schema (XSD) to validate and define the canonical format that matches the QFML application, as well as two XML stylesheets (XSL) to translate between canonical forma and name/value format.
The diagram below illustrates how the host integration works with strongly-typed XML, and translates to or from the more generic name/value format used on the mobile. While it is possible to code directly to the name/value pair format, the process below ensures that messages exchanged will conform to the expected formats. In addition, there are XML tools that can be employed to map from canonical format into native coding languages (e.g. Java, C#, etc), or even database tables.
Forward Message Integration
The WMC SOAP web service for sending a forward message consists of a identifier elements and a data/datum payload. The identifier elements are required on ever invocation. Below is a typical SOAP message example (security header omitted).
|
|
The required identifier elements are:
- acctno
- ua
- custMsgId
The acctno element is the NMC number assigned for communication purposes. The ua is the device's unified address (UA) used by Qualcomm to uniquely identify a mobile unit. The custMsgId is assigned by the integration system. It must not be blank, but can be any other positive integer value. This should also be unique for every message sent, which enables message status tracking. While a custMsgId can be re-submitted, WMC will block attempts to use the identifier too frequently, and return a service fault.
The data element is where the message will vary depending on action being performed. This is a hierarchically recursive structure which defines the mobile message itself. The types and structure vary depending on the type of message and associated datum. The content of the data/datum structure is covered elsewhere.
Successful messages will return a sendResponse that looks something like the following:
|
|
Forward Message Types
As seen above, the data/datum structure contains a datum name/value pair that is used to identify the message type (literally "msgType"). The diagram below shows common forward message types in canonical form.
Forward Message Error Handling
As a service method, invocation may fail for any number of reasons. Like any distributed service, the integration client should be coded in a way to account for general service interruptions (HTTP 400 and 500 errors). Consult online SOAP references for best practice HTTP error handling. The integration client should also handle send warnings and errors as described below.
Warnings
It is possible to successful send a forward message and have specific parts fail. The GeoService integration offered with Advanced Workflow behaves this way. If a forward message containing landmarks fails to find them, each landmark that cannot be located is handed back as a geoServiceWarning as part of the sendResponse. In this case, the WMC service will pass on the landmark name with the message, but cannot add the common attributes such as "hours of operation" to each landmark. In many systems, the driver will still have enough information to reach their destination.
|
|
The integration code should process warnings so that appropriate action can be taken to correct the account. For instance, perhaps the landmark in the above example needs to be added under GeoServices.
SOAP Faults
When the integration receives a SOAP Fault, the implementation should assume that the message has not been processed by Qualcomm, no matter what the specific details of the reported error. The integration may wish to record and process the returned <faultcode> and <faultstring> elements which may help Qualcomm in assisting with the reported error.
Security Failure
The WMC web service credentials are the same credentials needed for the WMC web application. The user must be defined for the given company and enabled for basic WMC access using the Qualcomm Service Portal administration. When there is a credential mismatch, the following SOAP fault will be returned:
|
|
WMC uses security mechanisms provided by the Qualcomm Service Portal (QSP). Note that the QSP will block user access on 3 failed login attempts. For system integration with automated calling, this blockage may happen very quickly. Make sure you validate credentials at the UI before attempting access with web services.
The appropriate correction for this error is to review and test credentials on the Qualcomm Services Portal.
Account Verification Failure
If the account number is blank or not assigned for the given portal credentials, WMC will return an account fault. Below is an example for a fictional 'MYCOMPANY' company in which the sender provider an incorrect account number.
|
|
The appropriate action for this error is to review integration configuration to ensure company and company account are the ones assigned for use by your company.
Device Verification Failure
The integration system may only message units owned by the account corresponding to the credentials. Attempt to message non-owned units results in a message similar to the following:
|
|
This error may occur if a device has been removed for repairs, but is still being messaged by integration. Check to ensure that this device is no longer active in the integration system. Contact customer support for assistance if the problem persists.
Message Identifier Failure
The required elements such as message identifier must contain a valid value. For WMC version 1.4 older, this produced the following error:
|
|
WMC version 1.5 and newer will return a fault with a message specific to the missing element. Contact customer support for further assistance.
Invalid Payload Data
The QFML structure is validated at the WMC server to prevent malformed messages from being sent to the mobile device. Failures appear something like the following:
|
|
If you see this message, contact customer support for further assistance.
Infrastructure Error
Qualcomm strives to deliver
In the event that Qualcomm infrastructure is unable to process the message, the integration will receive a message similar to the following (Wording may vary depending on error).
|
|
If you see this message, contact customer support for further assistance.
Message Rejection Conditions
The WMC web service provides custMsgId for identifying and tracking forward messages. A unique custMsgId number must be provided by by the integration system. While failed messages may be resent with the same custMsgId number, attempts to repeatedly send the same number in a short period of time will fail.
Return Message Integration
For a given forward message, the sequence of responses is typically:
- SOAP Response - sendResponse message
- ESS Transaction - T.6.01.0
- ESS Transaction - T.6.02.0
- ESS Transaction - T.6.03.0 - if an error condition exists, or if a non-driver initiated response is expected
The return message definitions can be found on the QSP Under the ESS Transactions. The workflow transactions are:
|
Workflow Transaction
|
Description
|
|---|---|
|
T.6.01.0 |
Message receipt acknowledgement from the NMC |
|
T.6.02.0 |
Message receipt acknowledgement from the MCP unit |
|
T.6.03.0 |
Wrapper transaction for mobile workflow payload data |
These transactions are defined on the QSP Integration Wiki: https://intinfo.myqualcomm.com/display/iWebInt/Notice+of+Scheduled+ESS+Transaction+Type+Schema+Changes . Specifically, the changes are included in Schema v1. 10 (preliminary).
T.6.01.0 Events - NMC Server Receipt
After the SOAP send message request is accepted, the T.6.01.0 transaction indicates whether or not the transaction has been queued on Qualcomm servers for delivery to the mobile device. This message has two primary purposes:
- Verify successful receipt of the message. (e.g. the message has been successfully queued for delivery to the mobile device. Acceptance at the mobile device has not occurred at this point).
- Provide a Qualcomm unique transaction identifier (the GMN) for the customer supplied unique message identifier (custMsgId) so that future messages can be correlated to the customer's original message.
Successful Events
When the workflow message is successfully received at the NMC for delivery to the mobile device, the completionCode is 0 and the custMsgID and GMN are supplied. Note that the custMsgId is the same value that appeared as <seqno> in the WMC 1.0 web service.
|
|
Error Handling
Integration systems should process the <completionCode> element and interpret the completion code as appropriate. Note that certain error conditions may not return information such as the GMN (below). Because of this, we recommend parsing and checking the <completionCode> element first. If it is non-zero, proceed with the handling according to the given status code. The <custMsgID> helps identify the corresponding forward message that was not processed.
|
|
If you see messages similar to this, please contact customer support for further assistance.
Completion Codes
Status values that can occur in response to a send request include the following:
|
Return Code
|
Description
|
|---|---|
|
0 |
Success / OK |
|
1 |
Unknown/Other Error |
|
2 |
NMC Internal Error |
|
3 |
XML Syntax Error |
|
4 |
Missing or Bad XML Element |
|
5 |
Reached NMC Limit |
|
6 |
Invalid element value / validation failure |
Note that only the numeric value is returned. The above description text is presented as an explanation only.
Completion Details
The completionDetails element is optional and is only populated when the completionStatus is 3 or 6. The completionDetails provide additional diagnostic information and should be provided when contacting technical support.
When the completionStatus = 3 , the following completionDetails are expected:
- ACCTNO tag in customer invalid
- UA tag invalid
Other values, while highly unlikely, are possible and should be captured for support diagnostic purposes. These may include (but are not limited to):
- both AAD and PRIORITY tags present
- neither AAD nor PRIORITY tag present or invalid
- VIRTUAL_CHANNEL tag invalid
- RETURN_RECEIPT tag invalid
- both TEXT and BINARY tags present simultaneously
- neither TEXT nor BINARY tag present or invalid
- LENGTH tag in APP_PAYLOAD invalid
- EXTLOC tag in APP_PAYLOAD invalid
- elements in GID tag invalid or missing
- Missing svc_params tag in forward_msg request
- Missing svc_data tag in forward_msg request
- Missing sched_pri tag in forward_msg request
- Missing customer tag in forward_msg request
- Missing app_payload tag in forward_msg request
- QOS INDEX invalid
- Missing svc_params tag before qos tag
- QOS INDEX out of range
- Missing svc_params tag before qos tag
- Group msg cannot override QoS
- QOS HOLD invalid
- QOS HOLD COST out of range
- QOS HOLD entries full
When the completionStatus = 6 , the following completionDetails are expected:
- UA value 0 not allowed
- ACCTNO value does not match UA owner
- UA is not enabled to receive message
- Invalid group number in UA
- No OV units present in group in UA
Other values, while highly unlikely, are possible and should be captured for support diagnostic purposes. These may include (but are not limited to):
- TEXT messages over this interface are presently not supported
- VIRTUAL_CHANNEL value exceeds max allowed value
- BINARY payload present when VIRTUAL_CHANNEL value is 0
- TEXT payload present when VIRTUAL_CHANNEL value is not 0
- AAD value out of bounds
- PRIORITY value out of bounds
- Value in app_payload LENGTH tag does not match TEXT payload size
- Value in app_payload LENGTH tag exceeds maximum allowed
- Gateway type not supported
Fault Recommendations
Use the following guide to implement error handling logic.
|
Status
|
Recommendation
|
|---|---|
|
1 |
Retry the message up to 3 times with the retry interval set to be at least 1X of the max ESS polling interval |
|
2,5 |
Notify technical support |
|
3,4,6 |
Should never be encountered during standard production operation. |
T.6.02.0 Events - Mobile Message Delivery Confirmation
The T.6.02.0 transaction indicates whether or not the transaction has properly delivered to the mobile device.
Successful Events
When the workflow message is successfully received at the mobile device, the completionCode is 3 . Note that the unique transaction identifier is the GMN. This value should be crossreferenced back to the customer unique ID (custMsgID) based on the mapping provided in the T.6.01.0 transaction.
|
|
Error Handling
Integration systems should process the <completionCode> element and interpret the completion code as appropriate.
Completion Codes
Status values that can occur in response to a send request include the following:
|
Return Code
|
Description
|
|---|---|
|
0 |
Message status not available |
|
1 |
Message Queued |
|
2 |
Message Sent OTA, not acknowledged yet |
|
3 |
Message Acknowledged |
|
4 |
Message Sent, reached max transmission count |
|
5 |
Message Sent, not acknowledged yet |
|
6 |
Message NACKed (negative ack) |
|
7 |
Service Unavailable |
|
8 |
Message Canceled |
|
9 |
Message Rejected by gateway |
|
10 |
Message Not Found |
|
11 |
Message Completed |
|
12 |
Message Transport ACKed |
Note that only the numeric value is returned. The above description text is presented as an explanation only.
Completion Details
This optional element is currently unused.
Fault Recommendations
Use the following guide to implement error handling logic. All faults should be recorded for diagnostic purposes.
|
Status
|
Recommendation
|
|---|---|
|
0, 1, 2, 5, 10 |
These scenarios should not occur as they are related to message queries. They should be recorded for diagnostic purposes, but no further action is required. |
|
3 |
Not a fault. This is the expected response code in a majority of cases. |
|
4 |
This is a valid timeout scenario when reaching max transmission count, or the message has been sent as many times as it is supposed to be sent and no ack is expected (typically only true in group messaging which does not apply to workflow at this time). |
|
6, 7 |
These scenarios should not occur. They should be recorded. It indicates the mobile is out of sync with the NMC, or there is an issue at the mobile. |
|
8 |
These scenarios should not occur. 8 - in rare cases it happens when operations cancels a batch of errant messages. |
|
9 |
Indicates a permissions or formatting error. They should be recorded. |
|
11 |
This status should not occur. On the rare occassion when this message is encountered, the message should be retried up to 3 times as it indicates that the message delivery was closed out but NOT guaranteed to have been properly delivered. It should be recorded for diagnostic purposes, but no further action is required. |
|
12 |
Transport ACK was generated by the message gateway to close out the transaction instead of being generated by the mobile device (as is the case with status code 3). It usually indicates that workflow is not present or it is not operating for this device. It should be recorded for diagnostic purposes, but no further action is required unless it is occuring on a regular basis for one or more units. If this status code occurs in numerous cases, contact support. |
T.6.03.0 Events
The T.6.03.0 transaction is used to transport the Driver Workflow application specific messages. The T.6.03.0 is typically NOT a direct response to forward message unless there is an error condition. The workflow payload is contained in a wrapper transaction. T6.0.03 contains a data container and a workflow event time for the specific contained workflow message.
The transactions fall into three general categories:
- Return messages based on driver initiated action - such as Loading, Unloading, NAT/NAL, ETA updates, and other similar driver initiated mobile activities.
- Return messages based on workflow detected and/or initiated events - such as Driver Login, Auto Arrival, etc.
- Return messages indicating that the requested forward message activity could not be completed.
Successful Events
When a return workflow message is received, the workflowEventType can be utilized to determine whether or not it should be treated as an error. If the workflowEventType is anything other than "error", then the data container should map back to the valid return message types as defined by the Workflow.xsd.
|
|
Like the forward messages, the detailed definition of each of these messages types is contained in the included html documentation of the workflow.xsd. To find the details of the specific message, start with the returnMessage element and drill down into the desired message.
The available workflow event types carried as payload in the T.6.03.0 are defined by the returnMessage element in the workflow.xsd.
Fault Recommendations
If the workflowEventType is error, the message payload will have the following format:
|
|
Note that the forwardMessageId is echo'd back from the original payload. By using a unique identifier for the forwardMessageId, errors can be correlated back to the original forward message request. Refer to the XSD for further explanation about the errorCategory, errorType, originalType, etc.