Skynax. Push Messaging. Integration Guide

Transcription

1 Skynax Push Messaging Integration Guide

2 Disclaimer Honeywell International Inc. ( HII ) reserves the right to make changes in specifications and other information contained in this document without prior notice, and the reader should in all cases consult HII to determine whether any such changes have been made. The information in this publication does not represent a commitment on the part of HII. HII shall not be liable for technical or editorial errors or omissions contained herein; nor for incidental or consequential damages resulting from the furnishing, performance, or use of this material. HII disclaims all responsibility for the selection and use of software and/or hardware to achieve intended results. This document contains proprietary information that is protected by copyright. All rights are reserved. No part of this document may be photocopied, reproduced, or translated into another language without the prior written consent of HII. Trademarks Wi Fi is a registered certification mark of the Wi Fi Alliance. Microsoft, Windows, Windows Embedded Handheld, Excel and the Windows logo are either registered trademarks or registered trademarks of Microsoft Corporation in the United States and/or other countries. Bluetooth is a trademark of Bluetooth SIG, Inc., U.S.A. microsd and microsdhc are trademarks or registered trademarks of SD 3C, LLC in the United States and/or other countries. Apple, ipad, iphone, itunes, icloud, the Apple logo, the itunes logo, and the icloud logo are registered trademarks of Apple Inc., registered in the U.S. and other countries. IOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license. Google and the Google logo are registered trademarks of Google Inc., used with permission. Android platform is a trademark of Google Inc. Patents For patent information, please refer to Copyright Honeywell International Inc. All rights reserved. ii Skynax Push Messaging Integration Guide

3 Document Change Record This page records changes to this document. The document was originally released as Revision 001. Version Number Date Description of Change 004 3/2016 Updated copyright and customer support information /2014 Revised to support Skynax Release 8.70: Added the spsm_id field. Updated the copyright page and back cover to include information for Intermec by Honeywell /2014 Added the appropriate copyright information to page ii. Revised to include information about Skynax Release 8.60, which supports mobile devices running Microsoft Windows Mobile, Apple ios, or Android. Skynax Push Messaging Integration Guide iii

4 iv Skynax Push Messaging Integration Guide

5 Contents Contents Customer Support vii Product Service and Repair vii Limited Warranty vii Send Feedback vii About This Integration Guide About Skynax Push Messaging Skynax Push Messaging Architecture Deliver a Message What Types of Messages Can You Send? About the Push Messaging Integration Interface Push Messaging Integration Table Field Descriptions Required Fields Optional Fields How Skynax Processes Push Messaging Updates Schedule Push Messaging Updates How to Maintain the Push Messaging Integration Table Skynax Push Messaging Integration Guide v

6 Contents vi Skynax Push Messaging Integration Guide

7 Customer Support Customer Support If you need assistance installing or troubleshooting your product, contact us by using one of these methods: Knowledge Base: Our Knowledge Base provides thousands of immediate solutions. If the Knowledge Base does not help you solve your problem, log into the Technical Support Portal to submit your problem or ask your question. Technical Support Portal: Log into the Technical Support Portal to search our Knowledge Base, submit your problem or question, request a call back, or provide feedback. When filling out one of the forms, provide as much detail as possible. You can even include attachments. Telephone: For our latest contact information, please check our website. Product Service and Repair Honeywell International Inc. provides service for all of its products through service centers throughout the world. To find your service center, go to and select Support > Contact Support > Service and Repair. Contact your service center to obtain a Return Material Authorization number (RMA #) before you return the product. To obtain warranty or non-warranty service, return your product to Honeywell (postage paid) with a copy of the dated purchase record. Limited Warranty For warranty information, go to and click Resources > Warranty. Send Feedback Your feedback is crucial to the continual improvement of our documentation. To provide feedback about this manual, please contact the Technical Communications department directly at ACSHSMTechnicalCommunications@Honeywell.com. Skynax Push Messaging Integration Guide vii

8 Customer Support viii Skynax Push Messaging Integration Guide

9 About This Integration Guide This guide describes how to integrate your business applications with Skynax Push Messaging services to easily manage message delivery and confirmation. Using the Push Messaging integration interface reduces the complexity and scope of work required to implement messaging capabilities in your mobile computing environment. About Skynax Push Messaging Skynax Push Messaging allows you to quickly and easily extend host application events and changing business data to remote mobile devices in near real-time. The Skynax Push Messaging infrastructure can locate remote mobile devices across LAN, WLAN, and WWAN networks and securely deliver push messages generated by the host application to the mobile devices. Note: Skynax Push Messaging is only supported on mobile computers running Microsoft Windows Mobile 2003, 5.0, or 6.1; Windows Embedded Handheld 6.5; or Android. Throughout this guide, Windows Mobile refers to all supported Windows Mobile and Windows Embedded Handheld operating systems. Skynax Push Messaging Architecture Host applications create messages that can be received by mobile business applications and insert those messages as new records in the Push Messaging integration table. Host applications periodically query the table to get message delivery status information and to perform maintenance to remove messages that are no longer relevant. The Skynax Gateway periodically queries the Push Messaging integration table for new message records. The Skynax Gateway also tracks the current network location of each mobile device. Skynax Push Messaging Integration Guide 9

10 Deliver a Message To deliver messages, you need to configure Push Messaging for the Skynax Client in the appropriate Device Set Template. For help, see the Skynax Mobility Management System User Manual. After the Skynax Gateway gets the IP Address of the mobile device to send the message to, message delivery occurs automatically. 1 The Skynax Gateway queries the Skynax database to determine the current IP Address of the mobile device to send the message to. 2 The Skynax Gateway pushes the message through the network to the Skynax Client on the mobile device. 3 The Skynax Gateway listens for a message confirmation from the Skynax Client. On each attempt to deliver a message, the Skynax Gateway updates the message delivery status in the Push Messaging integration table. 4 The Skynax Client sends a periodic heartbeat to the Skynax Gateway and listens for incoming messages on selected network connections. 5 The Skynax Client: receives and validates the incoming message. sends a message to the Skynax Gateway confirming receipt of the message. stores the message in the local message queue on the device. generates an event to tell mobile business applications running on the device that a new message has arrived. 6 The mobile business applications can use Skynax Data Services to access the message queue and retrieve the message. 10 Skynax Push Messaging Integration Guide

11 Host Application Query Message Delivery Status Insert/Update New Messages SQL Server Skynax Database Update Message Delivery Status Query New Messages Skynax Gateway Skynax Client Messaging Heartbeat Send Message Receipt Confirmation Receive New Messages Skynax Client Mobile Device Skynax Push Messaging Architecture Skynax Push Messaging Integration Guide 11

12 What Types of Messages Can You Send? Use Skynax Push Messaging services to deliver short coded messages that: contain business data for a mobile business application. contain instructions that are interpreted by a mobile business application. These instructions may also tell the application to perform a task, such as display the message contents to the mobile device user or send a request to the Skynax Data Service to download a new product catalog file. instruct the Skynax Client to launch an application on the mobile device. are generated internally by the Skynax system and instruct the Skynax Client to perform specific tasks. About the Push Messaging Integration Interface To create messages to deliver to mobile devices, you use a host application (or a proxy for the host application) to establish a standard connection to the SQL Server hosting the Skynax database. You can then modify the information stored within a single Skynax database table. This table, Dat_PushMessage, is located in the Skynax database and serves as the Skynax Push Messaging integration interface. Through this interface, you send messages and message recipient addresses from your host application to Skynax. Note: Each Skynax system has one central Skynax database. If you have more than one Skynax system, make sure that your host application is connected to the appropriate Skynax database. 12 Skynax Push Messaging Integration Guide

13 Database Connection Host Application Database Connection Query Status Information Insert/Update Message Information Database Connection SQL Server Skynax Database Table: Dat_PushMessage Database Connection Skynax System Skynax Push Messaging Integration Process Skynax Push Messaging Integration Guide 13

14 Push Messaging Integration Table The fields in the Push Messaging integration table contain this information: Name: The name of the field in the Push Messaging integration table. Data Type: The type of data that the field accepts. Not Null: Whether the field accepts null values. Note: If any field that requires a value is left blank, you cannot insert new records into the table. Input/Output: Determines if the information is provided as input to Skynax by the host application, as output from Skynax, or as input/ output, where the host application or Skynax updates the information. With input/output fields, the information must be interpreted within the context and purpose of the field. Fields that are not designated for input or output are automatically generated by the rules of the Skynax database. Fields in the Push Messaging Integration Table Name Description Data Type Not Null pshm_id --- int IDENTITY (1, 1) Yes -- sysc_code nvarchar (40) input Message addressed to System Code Input / Output cmpn_oemcode Message addressed to OEM Code nvarchar (50) input pshm_subscriber Identification of the receiving application nvarchar (50) input pshm_messagecode Host application message tracking nvarchar (64) Yes input code pshm_messagedata Message contents nvarchar (256) Yes input pshm_status Message delivery status int Yes output pshm_statusdate Time stamp for message delivery datetime output status pshm_expiration Date and time when message expires datetime input pshm_attempts Delivery attempts to use per round smallint input pshm_rounds Number of delivery rounds to use smallint input pshm_attemptspan Time between delivery attempts smallint input 14 Skynax Push Messaging Integration Guide

15 Fields in the Push Messaging Integration Table (continued) Name Description Data Type pshm_roundspan Time between delivery rounds smallint input pshm_savetolog Logging level for message smallint input services pshm_lastattempt Date and time of last delivery datetime output attempt pshm_attemptcount Attempts completed in current smallint output round pshm_roundcount Number of rounds completed smallint output pshm_createdate Date and time when message was datetime output created spsm_id ID linked to the table of the system int output push messages. Field Descriptions Not Null Input / Output The Skynax Push Messaging integration table contains required and optional fields. Required Fields To use the Skynax Push Messaging integration table, you must provide the appropriate information for each field that requires a value (not null), as well as a value for either the sysc_code field or cmpn_oemcode field. pshm_id The unique identifier for each record in the table. This identifier is generated automatically when a new record is inserted and is only for internal Skynax use. Data Type: int IDENTITY (1, 1) Input/Output: N/A Skynax Push Messaging Integration Guide 15

16 sysc_code The System Code of the intended recipient of the message. If the host application uses a System Code to identify the message recipient, Skynax tries to find the OEM Code of the mobile device that is using the System Code to authenticate to the Skynax system. When Skynax locates the mobile device, Skynax attempts to deliver the message to it. Unlike an OEM Code, a System Code is a virtual identifier that can roam between multiple physical devices. Use a System Code to send a message to a specific person (or person working with a specific set of data) regardless of the mobile device they are using. Note: To successfully send a message to a mobile device, you need to define a value for either the sysc_code field or the cmpn_oemcode field. Data Type: nvarchar (40) Input/Output: input cmpn_oemcode The OEM Code of the intended recipient of the message. If the host application uses an OEM Code to identify the message recipient, Skynax tries to find the specific mobile device in the network and deliver the message to it. The OEM Code must be for the primary device in the Device Set, which is the network addressable CPU of the remote mobile computer. Unlike a System Code, an OEM Code is a constant that identifies a specific physical device. Use an OEM Code to send a message to a specific mobile device, regardless of the person or business data using the device. If the host application provides both a System Code and an OEM Code, Skynax uses the OEM Code. Note: To successfully send a message to a mobile device, you need to define a value for either the sysc_code field or the cmpn_oemcode field. Data Type: nvarchar (50) Input/Output: input 16 Skynax Push Messaging Integration Guide

17 pshm_subscriber Specifies the identification of the mobile device application to receive the push message. If this field is left blank, any application can receive the push message. Data Type: nvarchar (50) Input/Output: input pshm_messagecode The host application message tracking code. The value stored in this field links the message record created by the host application in the Push Messaging integration table to the corresponding business data in the host application central data repositories. The host application can periodically query the Push Messaging integration table and use the message code to determine the delivery status of each message and send the status information to its own system. Push Messaging services attribute special meaning to messages that contain Skynax keywords (starting with character) in the Message Code field. So, push messages that start with character are immediately marked as expired (pshm_status=2) and are not processed and sent to the Skynax Client. One exception is push messages that start with keyword. For example, entering the Skynax in the Message Code field instructs the Skynax Client to run a specific application on the mobile device. You use the Message Data field to specify the full path of the application in quotation marks followed by optional command line parameters. To run the Microsoft Windows Notepad application, you enter this text in the Message Data field: "\Windows\notepad.exe" -f myfile.txt Data Type: nvarchar (64) Input/Output: input pshm_messagedata The primary contents of the message. Data Type: nvarchar (256) Input/Output: input Skynax Push Messaging Integration Guide 17

18 pshm_status The delivery status of the message in the Skynax system. Value Status 0 (default) Message is waiting to be sent to the mobile device. 1 Message was successfully delivered to the mobile device. 2 Message time-to-live has expired before delivery to the mobile device, or all attempts to deliver the message have been exhausted in all message delivery rounds. 3 Message was successfully delivered to the mobile device application as specified in the pshm_subscriber field. If the pshm_subscriber field is not defined in the Push Message table, the status is changed to 3 as soon as any application on the mobile device receives the message. When you insert a new record into the table, the default value 0 is automatically entered in this field. Data Type: int Input/Output: output Optional Fields Use these fields to capture additional message information. pshm_statusdate The date and time the delivery status stored in the pshm_status field was last updated. Data Type: datetime Input/Output: output pshm_expiration The date and time after which an undeliverable message is considered expired and no more delivery attempts will be made. The date and time must be entered as UTC (GMT + 0). The appropriate date and time value for message expiration depends on the business scenario of the messaging service. You can estimate reasonable starting values for date and time expiration for different categories of messages by reviewing the related business processes on a time axis. 18 Skynax Push Messaging Integration Guide

19 For example, in a transport and logistics operation, a message alerting a driver to make an additional parcel pickup may have a default expiration of ten hours from the time the message is created. But, if the parcel pickup must be made before the customer closes, the message expiration should be set to the closing time of the customer. Data Type: datetime Input/Output: input pshm_attempts The number of times the Skynax Gateway attempts to deliver the message for each message delivery round. Data Type: smallint, Default = 10 Input/Output: input pshm_rounds The number of rounds the Skynax Gateway makes before determining that the message is undeliverable. One round consists of the number of attempts defined in the pshm_attempts field. Data Type: smallint, Default = 3 Input/Output: input pshm_attemptspan The amount of time (in seconds) the Skynax Gateway waits between each attempt to deliver the message within a single message delivery round. Data Type: smallint, Default = 5 Input/Output: input pshm_roundspan The amount of time (in seconds) the Skynax Gateway waits before starting the next message delivery round. Data Type: smallint, Default = 300 Input/Output: input Skynax Push Messaging Integration Guide 19

20 pshm_savetolog The log level the Skynax system uses to store events related to the message delivery services when the Skynax Gateway attempts to deliver the message. You can view events logged by Skynax Push Messaging services in the Skynax Manager log modules. Log Level Description 0 Do not log message delivery attempts. 1 Log message delivery attempts that are unsuccessful because: Skynax could not identify the mobile device using the System Code. Skynax could not acquire the IP Address of the mobile device. Skynax logs these events after making all delivery attempts in all rounds. 2 Log successful message delivery attempts. 3 Log unsuccessful message delivery attempts, including events described in log level 1. 4 (default) Log each round of unsuccessful message delivery attempts and each successful message delivery attempt. 5 Log all message delivery attempts, successful and unsuccessful, in all rounds. This log level is the most comprehensive and is useful for: integration and pilot testing. diagnosing a suspected message delivery problem. Note: As you increase the log level, the number of stored events and the size of the Skynax database also increase. For daily operations, log level 4 provides the level of log detail needed for system administration while minimizing Skynax database storage requirements. Data Type: smallint Input/Output: input 20 Skynax Push Messaging Integration Guide

21 pshm_lastattempt The date and time of the last message delivery attempt. Data Type: datetime Input/Output: output pshm_attemptcount A counter that Skynax updates indicating the number of message delivery attempts that have been made in the current round. Data Type: smallint Input/Output: output pshm_roundcount A counter that Skynax updates indicating the number of completed message delivery rounds. Data Type: smallint Input/Output: output pshm_createdate The date and time the message record was created in the table. This value is automatically generated when a new record is inserted in the table. Values are stored in this field as UTC (GMT + 0). Data Type: datetime Input/Output: output spsm_id ID linked to the table of the system push messages. Do not modify or delete the contents of this field. Data Type: int Input/Output: output Skynax Push Messaging Integration Guide 21

22 How Skynax Processes Push Messaging Updates Skynax uses a Skynax Gateway to process the Push Messaging integration table based on the settings in Skynax Manager. So, you need to make sure that at least one Skynax Gateway is running. During each process cycle, the Skynax Gateway steps through all of the records in the Push Messaging integration table that have not been processed in ascending order based on the pshm_createdate field. The Skynax Gateway reads the OEM Code or the System Code for each message to determine the IP Address of the corresponding mobile device and starts the first message delivery round. After each message delivery attempt, the Skynax Gateway updates the output fields for the record in the Push Messaging integration table. The host application can periodically query the Push Messaging integration table and read the value of the output fields to determine the delivery status of each message. Round 1 of x Attempt 1 Attempt 2 Attempt 5 of y Attempt 4 Attempt 3 Push Messaging Process: The number of message delivery attempts and rounds is defined by the pshm_attempts and pshm_rounds fields, respectively. 22 Skynax Push Messaging Integration Guide

23 Schedule Push Messaging Updates You configure the frequency at which Skynax automatically processes the Push Messaging integration table in Skynax Manager. 1 Start Skynax Manager. 2 Select the Skynax Infrastructures tab. 3 Click Push Messaging. 4 Set values for Mobile Device IP Address Expiration Parameters, Push Messaging Operating Parameters, and Push Messaging for Active Device Management. Note: You should schedule a reasonable time interval for this process to provide timely updates without unnecessary use of the SQL Server. 5 Click OK. Skynax Push Messaging Integration Guide 23

24 How to Maintain the Push Messaging Integration Table You must perform regular maintenance on the Push Messaging integration table to keep the number of records to a reasonable and manageable amount: Configure the host application to: delete expired undeliverable messages when the application add records to the table. determine when records are no longer relevant and periodically delete them. Only delete records with a pshm_status of 1, 2, or 3. Deleting messages with a pshm_status of 0 may interfere with the Skynax Gateway processing the Push Messaging integration table and delay message delivery. Schedule a reasonable time interval for maintenance activities to minimize the amount of time the Push Messaging integration table is locked for maintenance purposes. Caution: If the Push Messaging integration table becomes too large, it may impact the push messaging functionality or performance of the Skynax Gateway. 24 Skynax Push Messaging Integration Guide

25

26 Honeywell Copyright 2016 Honeywell International Inc. All rights reserved. Skynax Push Messaging Integration Guide * * P/N