Driver Workflow Web Service Integration Guide
Driver Workflow Web Service Integration Guide
Overview
Driver Workflow is both an application on the mobile and a system of integration at the host. Both host and mobile components are required to create a complete system, unlike other applications for which integration may be optional. Driver Workflow also supports a high degree of customization which can be reflected in adapting forms, behavior, and even messaging to specific customer needs.
Driver Workflow Web Service Information Covered
- Best Practice Integration
- WebService Methods
- WebService Security
- Forward Message Samples
- Return Message Samples
Communication Flow
The general flow of these messages starts from the host integration, is sent through the Workflow Management Center (WMC), on to the mobile, and returns as events through the Qualcomm Event Subscription Service (ESS). Messages may also originate on the mobile, return through ESS as events and get processed by host integration. The important point to remember is that all forward (outbound messages to mobile) are processed by WMC, while all return messages (originating at the mobile), are handled by ESS.
The message definition and mobile application are determined by the QFML application which is installed on the mobile. Multiple, dissimilar applications may be installed within the same fleet, depending on business function (e.g. Reefer, Tanker, Long Haul, LTL, etc.). Host integration is responsible for tracking this configuration (via WMC), and constructing or interpreting the appropriate messages for the mobile configuration. The simplest integration case is when all mobile devices in a fleet share the same QFML application.
The workflow host integration involves two (2) URLs: one for forward messaging using WMC, and another for return message processing via ESS. General information about ESS is covered on under Qualcomm Portal Integration documentation. ESS offers a single, generic interface for processing events from many different Qualcomm applications. The portal integration also allows multiple subscribers and tailored event routing.
This document addresses the interfaces present in WMC 1.5 and QSP as of Q1, 2011.
Integration Points:
Both WMC and ESS present SOAP web service interfaces. Together these form a "conduit" between the host integration and the mobile devices. All worfklow communication takes place within this conduit.
Please note that WMC WSDL differs from the 1.0 OVDW WSDL, even though it contains some of the same methods.
Workflow Integration Areas
There are three basic areas of workflow integration:
- Mobile Messaging
- Forward Messaging
- Return Messaging
- Device Management
- Application Management (version 1.5+ only)
Mobile messaging covers the flow of messages to and from the mobile.These are the messages that make up the behavior of the workflow application and how it integrates into dispatch/controlling systems.
Device management allows the integration system(s) to track and modify which mobile devices are currently enabled for workflow. This addresses the status or notification events which are pertinent for classifying how devices interact with workflow.
Application management API's are used to reconfigure the mobile QFML application using web services.
For an effective automated system, integrators must implement areas #1 and #2. Depending on the size and complexity of the fleet, the third area may be managed manually or automated through the given API.
Mobile Messaging
This section provides an brief overview of mobile messaging. Details can be found HERE. Mobile messages are processed using the following API
- Forward via WMC
- WMC::send
- QFML Payload Data
- WMC::send
- Return via ESS
- ESS::dequeue
- T.6.01.0 event
- T.6.02.0 event
- T.6.03.0 event
- ESS::dequeue
Messages directed to the mobile (forward) are delivered using the WMC web service send method. All forward message status and messages originating from the mobile device are delivered as ESS transactions. The diagram below demonstrates how the major components interact to implement mobile messaging.
Device Management
This section provides an brief overview of workflow device management. Details can be found HERE. Device status is processed using the following API
- Forward via WMC
- WMC::queueEnabledUnits
- Return via ESS
- ESS::dequeue
- T.6.04.0 event
- ESS::dequeue
As devices are added or removed from the account, a T.6.04.0 transaction is queued for notification. The web service provides a trigger mechanism to send device status notification for all known devices. The diagram below demonstrates how the major components interact to implement device management.
Application Management
These web services allow the management of which devices will be assigned a specific workflow. Details can be found HERE. Device status is processed using the following API
- Forward via WMC
- WMC::getWorkflows
- WMC::deployWorkflow
- Return via ESS
- ESS::dequeue
- T.6.04.0 event
- ESS::dequeue
Through the WMC web service, the integration is able to get uploaded workflows and assign them to available devices. The status of these assignments is relayed back as ESS T.6.04.0 device updates, which includes the deployed workflow package name, version, and disposition. The diagram below demonstrates how the major components interact to implement application management.
Workflow Security
There are three areas that need to be addressed for workflow security:
- Security Credentials
- Security Role
- SOAP Security Protocol
Security Credentials
Use the Qualcomm Service Portal Administration page to create and manage users and passwords for workflow web services. We recommend creating a dedicated user reserved specifically for web service access.
Make sure you validate the web service login through the normal Qualcomm Service Portal login page before submitting it programmatically. The QSP authentication will block access to any user that fails three login attempts, and with programmatic web services this may happen quickly. If authentication is blocked, contact your company's Qualcomm Service Portal administrator.
Security Role
The user created on the QSP must be enabled for general workflow access. You can test this by logging in with the desired web service credentials and navigating to the "Workflow Management Center" home page. If you do not see the "Workflow Management Center" menu the web service user does not have the appropriate access. Contact your administrator for help in setting up the appropriate access.
Security Protocol
Workflow web services adhere to the SOAP WS Security protocol (WSS), and implement Username Token authentication. The WS security header element requires two nested elements, Timestamp and UsernameToken. Any other elements contained in the security element will result in a failure.
|
|
The UsernameToken is subdivided into two parts: username and password. The username element will be a combination of the web service User ID (created above), and the Company ID. These are the same two fields used for the portal login. The username must be the following form:
|
|
Workflow Integration Tools
There are no required Qualcomm tools to perform workflow integration. As a SOAP compliant web service, any standard SOAP tools will be sufficient to complete the integration. However, there are tool recommendations and a sample client that makes getting started with workflow easier.
You can find more information here.