Redbooks Paper James Chamberlain David Quenzler System Integrators Guide: Integrating WebSphere Everyplace Device Manager and WebSphere Everyplace Connection Manager Introduction This IBM® Redpaper describes integration scenarios for IBM WebSphere® Everyplace® Device Manager and WebSphere Everyplace Connection Manager. Specifically, the scenarios are leveraging WebSphere Everyplace Connection Manager messaging for WebSphere Everyplace Device Manager notification and the bootstrap of a SyncML device. SyncML is now part of the Open Mobile Alliance (OMA). For details, visit: http://www.openmobilealliance.org/tech/affiliates/syncmlthe © Copyright IBM Corp. 2005. All rights reserved. ibm.com/redbooks 1 Scenario components After you are connected to an internal network by a WebSphere Everyplace Connection Manager mobility client, a device agent can communicate with the WebSphere Everyplace Device Manager server. Figure 1 WebSphere Everyplace Connection Manager overview WebSphere Everyplace Connection Manager messaging enables a Web application server (WebSphere Everyplace Device Manager) to send messages to messaging clients, such as a pager or a telephone using a variety of wireless networks. Messaging services include support for Short Message Service (SMS). Messaging services can also support unconfirmed Wireless Access Protocol (WAP) push delivery when installed with the WAP proxy. Figure 2 Short message delivery 2 Integrating WebSphere Everyplace Device Manager and WebSphere Everyplace Connection Manager WebSphere Everyplace Connection Manager mobile-originated messages, although not applicable to WebSphere Everyplace Device Manager, can be useful when you are accessing other application servers. WebSphere Everyplace Connection Manager gateway changes For the integration scenarios, two changes are required to the WebSphere Everyplace Connection Manager gateway. Authorized Program Analysis Report IY51880 To use WAP Push Version 1.2 to perform notification and bootstrap jobs with SyncML Device Manager devices, Authorized Program Analysis Report (APAR) IY51880 for WebSphere Everyplace Connection Manager Version 5.01 is required. This code fix has been included in the WebSphere Everyplace Connection Manager V5.0.1.2 release. Adding messaging services to WebSphere Everyplace Connection Manager Part of WebSphere Everyplace Connection Manager configuration involves creating a Connection Manager resource. The gatekeeper console Add wizard presents the steps necessary to create the resource, including how to add messaging services to the WebSphere Everyplace Connection Manager. Ensure that messaging services have been added to the WebSphere Everyplace Connection Manager before proceeding. Record the Listen port settings for use in the configuration of the WebSphere Everyplace Device Manager push proxy URL as described in the section that follows. For more details, visit the WebSphere Everyplace Connection Manager Information Center: http://wedm_server/dms/docs/en/InfoCenter Note: To make modifications to the WebSphere Everyplace Connection Manager server, including configuration changes and software updates, you must restart the WebSphere Everyplace Device Manager Server application server (DMS_AppServer). WebSphere Everyplace Device Manager server changes To use WebSphere Everyplace Connection Manager in conjunction with WebSphere Everyplace Device Manager, you must modify the URL for the push proxy gateway to point to the WebSphere Everyplace Connection Manager server. The URL is in the push.properties file on the WebSphere Everyplace Device Manager server: <DMS_AppServer>/dmserver.war/WEB-INF/classes where DMS_AppServer is the directory where the WebSphere Everyplace Device Manager application server is installed. In the push.properties file, change the push.proxy-url parameter to the URL of the connection manager. For example, if the connection manager is wecm.itso.ral.ibm.com and the message services uses a non-secure port number such as 13131, the value of the push.proxy-url parameter would be: push.proxy-url=http://wecm.itso.ral.ibm.com:13131 Integrating WebSphere Everyplace Device Manager and WebSphere Everyplace Connection Manager 3 The port used must match the Listen port settings that are used when you are configuring messaging services for the WebSphere Everyplace Connection Manager. The default non-secure port is 13131. After changing the value for push.proxy-url, stop and restart the WebSphere Everyplace Device Manager server. Scenarios When a person obtains a new mobile device, it might or might not be pre-configured for a particular enterprise or service provider. If the device is not pre-configured, configuration will be one of the first tasks that is performed after an enrolled user connects for the first time and registers the device with the provider. Our integration scenario details the steps required to submit a bootstrap job to an unprovisioned (clean) device that has just authenticated to WebSphere Everyplace Connection Manager. A discussion of additional WebSphere Everyplace Device Manager scenarios can be found in the Product overview section of the WebSphere Everyplace Device Manager Information Center. Bootstrap jobs A bootstrap job is used to: Provide initial access for devices to the WebSphere Everyplace Device Manager server. Restore WebSphere Everyplace Device Manager configuration information to a device that might have inadvertently lost that information such as after a hard reset of the device. Bootstrap jobs are available for SyncML Device Manager devices that support the function. SyncML devices must be pre-enrolled before bootstrapping. The WebSphere Everyplace Device Manager console allows bootstrap jobs for the BaseSyncMLDM device class only. Bootstrap jobs cannot be submitted for Palm, Open Service Gateway Initiative (OSGi) Win32, or WinCE devices. The WebSphere Everyplace Device Manager server must know certain information (for example, the device address, phone number, or some other mechanism for communicating with the device) before initiating the bootstrap. The bootstrap message contains enough information for the device to be authorized and to initiate a session with the WebSphere Everyplace Device Manager server. It typically contains the SyncML Device Manager management object along with a minimum number of parameters needed to communicate with the WebSphere Everyplace Device Manager server. It is a one-time transfer of information, not part of an ongoing session between the device and the WebSphere Everyplace Device Manager server. The WebSphere Everyplace Device Manager server does not expect any return status from the bootstrap message. An implicit acknowledgment of a successful bootstrap occurs when a device connects to the server for its first management session. A bootstrap job is only be sent to a device if the Bootstrapped parameter is set to No in the General Properties tab. 4 Integrating WebSphere Everyplace Device Manager and WebSphere Everyplace Connection Manager Bootstrap jobs can be created for an individual device, several devices in the device class, or all devices in the device class. The job results and details are stored in the WebSphere Everyplace Device Manager database. Submitting a bootstrap job To make a bootstrap job, do the following steps: 1. From the WebSphere Everyplace Device Manager console, select the target device, a group of devices, the device class, or criteria for running the job. 2. Right-click a device or the device class and select Submit Job from the context menu. 3. Use the Attributes window to specify the attributes for this job. The job attributes include the job type, activation date, expiration date, priority, description, and others. Select Bootstrap in the Job Type field. 4. Use the Job Parameters window to specify the account name and security type you want to set for this job: – Account name Specifies the WebSphere Everyplace Device Manager account to create with the bootstrap job – Security type • NETWPIN If the security level is NETWPIN, the shared secret is based on a network-specific shared secret. • USERPIN If the security level is USERPIN, the shared secret is based on a user personal identification number (PIN) value. • None No security is set for the bootstrap job. Click Help for information about using the Parameters window. 5. Use the Submit Job Summary window to review and verify the target devices and the attributes that you specified for this job. Click OK to submit the job. Remember: A bootstrap job will only be sent to a device if the Bootstrapped parameter is set to No in the General Properties tab. If the job is submitted successfully, the administrator receives a message that gives the job ID for the created job. You can use the job ID to do other tasks, such as: View job history View upcoming jobs Exclude the device from jobs Notification jobs A notification job is used to send a message to target devices requesting that they connect to the WebSphere Everyplace Device Manager server. For example, a cell phone is notified by Short Message Service (SMS) of a waiting job. The WebSphere Everyplace Device Manager notification message can be customized using code that implements the administration APIs discussed in the Information Center. See the Integrating WebSphere Everyplace Device Manager and WebSphere Everyplace Connection Manager 5 Information Center for information about Application Programming Interfaces for WebSphere Everyplace Device Manager, specifically the DEVICE_NOTIFICATION_TYPE attribute. Notification jobs can be created for certain SyncML devices and certain OSGi devices. An event notification causes a device to initiate a connection with the WebSphere Everyplace Device Manager server. A notification job can also send a bootstrap message to a device. The WebSphere Everyplace Device Manager console allows notification jobs for the BaseSyncMLDM device class only. Bootstrap jobs cannot be submitted for Palm, OSGi Win32, or WinCE devices. A notification job will only be sent to a device if its Bootstrapped parameter is set to Yes in the General Properties tab. Notification jobs can be created for an individual device, several devices in the device class, or all devices in the device class. The job results and details are stored in the WebSphere Everyplace Device Manager database. Event notification Event notification is a job option for many job types in the Submit Job wizard on the WebSphere Everyplace Device Manager console. Even notification can also be used when submitting jobs with the Care applications and when using the WebSphere Everyplace Device Manager Administration API. When event notification is available, the administrator has the option to provide notification as part of the job that is being submitted. When the notification option is checked, a message is sent to the device that forces the device to connect to the WebSphere Everyplace Device Manager server. For example, after you select the notification option for a job and submit that job, an event is issued to the plug-in and a notification is generated and sent to the device. The notification triggers the device to connect to the WebSphere Everyplace Device Manager server and run jobs that are waiting for the device. Notification Manager The Notification Manager uses a job notification table in the WebSphere Everyplace Device Manager database for processing notifications. The records in the table represent the active jobs that have the event notification check box set to Yes (selected) for the target devices. After the status for a job changes from active state, the job notification record is removed from the job notification table. For example, if event notification is selected for a job that was created for 10,000 target devices, 10,000 records are added to the notification table for that job. Because these devices are not typically connected to the network, the notification for an active job is only sent to the device every few days. Table 1lists the notification intervals. Table 1 WebSphere Everyplace Device Manager notification intervals 6 Job Type Notification Interval Maximum Number of Notifications Sent Bootstrap 6 hours 8 Command script 72 hours 4 Custom command 72 hours 4 Device configuration 72 hours 4 Integrating WebSphere Everyplace Device Manager and WebSphere Everyplace Connection Manager Job Type Notification Interval Maximum Number of Notifications Sent Inventory 72 hours 4 Node discovery 72 hours 4 Notification 1 minute 1 Note: You cannot change the frequency of a notification to a device for an active job. The notification interval is set when the job type is installed and registered with WebSphere Everyplace Device Manager. Submitting a notification job To submit a notification job, follow these steps: 1. From the WebSphere Everyplace Device Manager console, select the target device, a group of devices, the device class, or criteria for running the job. 2. Right-click a device or the device class and select Submit Job from the context menu. 3. Use the Attributes window to specify the attributes for this job. The job attributes include the job type, activation date, expiration date, priority, description, and others. Select Notification in the Job Type field. 4. Use the Submit Job Summary window to review and verify the target devices and attributes you specified for this job. Click OK to submit the job. Remember: A notification job is only sent to a device if the Bootstrapped parameter is set to Yes in the General Properties tab. If the job is submitted successfully, the administrator receives a message that gives the job ID for the created job. You can use the job ID to do other tasks such as: View job history View upcoming jobs Exclude the device from jobs WebSphere Everyplace Device Manager job matrix The scenarios described in this section focus on bootstrap and notification jobs. WebSphere Everyplace Device Manager has several other job types. All job types are not applicable to all device classes (Table 2). Table 2 WebSphere Everyplace Device Manager job matrix OSGi Bootstrap Palm SyncML WinCE Win32 x Bundle Control x Command script x x x x Integrating WebSphere Everyplace Device Manager and WebSphere Everyplace Connection Manager 7 OSGi Palm SyncML WinCE Win32 Custom command x x x Device configuration x x x x x Inventory collection x x x x x Node discovery x x Notification x x Registry editing x Registry retrieval x Software distribution x Software distribution for ECUs x Software list update x Software removal x x x x x x x x Conclusion Integrating WebSphere Everyplace Device Manager with WebSphere Everyplace Connection Manager is a complex endeavor that requires significant planning. The authors were not able to obtain a SyncML device to test notification or bootstrap jobs. There are no SyncML notification or bootstrap simulators available. Many issues remain with respect to the integration of these two WebSphere Everyplace Service Delivery components. Some of these issues are: WebSphere Everyplace Service Delivery Lightweight Directory Access Protocol (LDAP) planning and sharing WebSphere Everyplace Device Manager use of advanced WebSphere Application Server security settings (non-Local OS security) How to enable Java2 security in WebSphere Application Server without breaking the WebSphere Everyplace Device Manager Care Applications with a long LDAP authentication string (current limit is 30 characters) 8 Integrating WebSphere Everyplace Device Manager and WebSphere Everyplace Connection Manager The team that wrote this Redpaper This Redpaper was produced by a team of specialists from around the world working at the International Technical Support Organization (ITSO), Raleigh Center. James Chamberlain is a Senior Software Engineer and certified Senior IT Specialist. He is a project leader at the ITSO, Raleigh Center. He has over 24 years of experience in the IT industry and specializes in pervasive computing technologies. His areas of expertise include e-commerce, pervasive computing, portals, AIX, Linux®, and Java™ programming. He also designs and develops solutions using J2EE, XML, Web Services, and IBM software products such as WebSphere and DB2. Before joining the ITSO, James worked for IBM Global Services on e-commerce system development for IBM Business Partners. He majored in Computer Science at Iowa State University. David Quenzler joined the IBM RS/6000® SP System Test group in 1997. He is an IBM Certified Advanced Technical Expert - RS/6000 AIX, working primarily with runs pertaining to High Availability, SAN, Databases, and Linux. He is now a Software Engineer at the IBM Linux Technology Center. He has a B.S. in Computer Science from the University of Central Florida. Thanks to the following people for their contributions to this project: Benson Chen, Technical Consultant IBM Pervasive Computing Division Kim Foster, Reviewer IBM Sales & Distribution WebSphere Portal Technical Sales Many thanks to the following IBM people for their assistance. Lenore Ramm Mike Seedorf Charles Le Vay Mart Nuttall Tony Wrobel Dale Chamberlain Scott Broussard Gary Craig Robert Sager Dave Heller Lei Lu Dave Pierson Don Watson And a specials thanks to our ITSO support staff at the ITSO, Raleigh Center: Margaret Ticknor Jeanne Tucker Tamika Barrow Linda Robinson Thanks to our ITSO management: Jere Cline And a special thanks to our IBM Pervasive Computing sponsor: Mary Fisher Integrating WebSphere Everyplace Device Manager and WebSphere Everyplace Connection Manager 9 10 Integrating WebSphere Everyplace Device Manager and WebSphere Everyplace Connection Manager Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM's application programming interfaces. © Copyright IBM Corp. 2005. All rights reserved. 11 This document created or updated on November 22, 2005. ® Send us your comments in one of the following ways: Use the online Contact us review redbook form found at: ibm.com/redbooks Send your comments in an email to: redbook@us.ibm.com Mail your comments to: IBM Corporation, International Technical Support Organization Dept. HZ8 Building 662 P.O. Box 12195 Research Triangle Park, NC 27709-2195 U.S.A. Trademarks The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both: Eserver® Eserver® Redbooks (logo) ™AIX® Everyplace® IBM® Redbooks™ RS/6000® WebSphere® The following terms are trademarks of other companies: Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others. 12 Integrating WebSphere Everyplace Device Manager and WebSphere Everyplace Connection Manager