White Paper R APPLE PUSH NOTIFICATION IN EMC R DOCUMENTUM MOBILE APPLICATION Abstract This white paper explains the Integration of Apple push notification service in EMC Documentum Mobile application. The paper explains brief about the Apple push notification, How EMC Documentum Mobile Application leverages this, customer use cases, configuration steps and troubleshooting check list which helps customers in configuring and trouble shooting. December 2012
Copyright 2012 EMC Corporation. All Rights Reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. The information in this publication is provided as is. EMC Corporation makes no representations or warranties of any kind with respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. Part Number H11392 Apple Push Notification in EMC Documentum Mobile App 2
Table of Contents Executive summary... 4 Audience... 4 Apple Push Notifications... 4 Overview... 4 Apple Push Notification service (APNS)... 5 Feedback Service... 5 Push Notifications in EMC Documentum Mobile Application... 6 How Notifications fits in EMC Documentum Mobile App... 6 Implementation in EMC Documentum Mobile Application... 6 Customer use cases... 6 Implementation Overview... 7 Dm methods used in Push notifications... 7 IT challenges... 8 Configuring Documentum Content Server for Push Notification... 8 Configuring the EMC Documentum Mobile App to receive notifications... 9 Configuring the EMC Documentum Mobile server for Apple push Notifications... 9 Mobile User receives and views the Push Notifications... 10 Troubleshooting... 10 Conclusion... 12 References... 12 Apple Push Notification in EMC Documentum Mobile App 3
Executive summary The Apple push Notifications are small text messages informs the user about a particular event occurred in the server side. When the user s device receives the push notification, it shows an alert, plays a sound and/or updates the app s icon. The user can launch the app from the alert. The app is given the contents of the push notification and can handle it as it sees fit. EMC Documentum Mobile Application leverages Apple Push Notification service to intimate the mobile users when a task got assigned to that user or when favorite item properties got changed for which the user is subscribed to. The Mobile User will be able to launch the Mobile application from the notification and can perform action intend to do. Paper explains how Push notification works in IOS context and brief about its various components and explains the business use cases in the Documentum context. Explains how EMC Documentum Mobile App achieves this and helps the user in configuring to receive the notifications in the EMC Mobile Application. Trouble shooting section eventually explains a check list of various tests to be performed so that users can resolve issues systematically. Audience This white paper is intended for the Mobile Users to get an understanding of the Apple Push Notifications in the EMC Documentum Application context and helps in configuring and troubleshooting to receive notifications in the Apple Devices. Apple Push Notifications Overview Notifications are a way for ios apps to provide alerts and related information. When using ios 5 or later, user can view notifications in the Notification Center. In ios, apps can t do a lot in the background. Apps are only allowed to do limited set of activities so battery life is conserved. But what if some interesting event happens and let the user know about this, even if they re not currently using the app in the apple device. Apple has a solution for this instead of the app continuously checking for events or doing work in the background, you can write a server-side component to do this instead. And when an event of interest occurs, the server-side component can send the app a push notification. Apple achieves this by using the APNS (Apple push notification Services). Apple Push Notification in EMC Documentum Mobile App 4
Apple Push Notification service (APNS) Apple Push Notification service is the centerpiece of the push notifications feature. A notification is a short message consisting of two major pieces of data: the device token and the payload. The device token is analogous to a phone number; it contains information that enables APNs to locate the device on which the client application is installed. APNs also use it to authenticate the routing of a notification. The payload is a JSON-defined property list that specifies how the user of an application on a device is to be alerted. The flow of remote-notification data is oneway. The provider composes a notification package that includes the device token for a client application and the payload. The provider sends the notification to APNs which in turn pushes the notification to the device. The flow of remote-notification data is one-way. The provider composes a notification package that includes the device token 1 for a client application and the payload 2. The provider sends the notification to APNs which in turn pushes the notification to the device. device token 1 : is analogous to a phone number; it contains information that enables APNs to locate the device on which the client application is installed. This is not same as the apple device id. payload 2 : is a JSON-defined property list that specifies how the user of an application on a device is to be alerted. The payload specifies how users are to be alerted to the data waiting to be downloaded to the client application. The maximum size allowed for a notification payload is 256 bytes; Apple Push Notification Service refuses any notification that exceeds this limit. Remember that delivery of notifications is best effort and is not guaranteed and provider should not depend on the remotenotifications facility for delivering critical data to an application via the payload. And never include sensitive data in the payload. You should use it only to notify the user that new data is available. Feedback Service Sometimes device repeatedly refused the notifications while APNs tries to deliver and this happens when the target application is deleted from the device. In this case APNs maintains a list of devices per application for which there were recent, repeated failed attempts to deliver notifications and provider should stop sending notifications to them. Apple Push Notification in EMC Documentum Mobile App 5
Push Notifications in EMC Documentum Mobile Application The Documentum Mobile users whom are subscribed for Push notifications will receive notifications when a specific event happened in the Documentum repository. EMC Documentum Mobile Application leverages Apple push notification in the following business for which the users are alerted with a notification. When a Mobile User receives a new task When a favorite item got changed. How Notifications fits in EMC Documentum Mobile App 1. The App registers for Push Notification ios ios a ios asks for a device token EMC Documentum Mobile application -App ID -Provisioning Profile 2. App receives device token 5. APNS pushes notifications to device APNS Server 3. The mobile app sends the Device token to the Server EMC Mobile App Server 4. When MU receives a task or favorite item got changed, server sends notifications to APNS Implementation in EMC Documentum Mobile Application Customer use cases Use case 1: When a Mobile user is working on his ipad/iphone/itouch and not on EMC Documentum Mobile and when an important task got assigned which needs the user s immediate attention, the Mobile User will be alerted about the task so that the task can be addressed immediately. Apple Push Notification in EMC Documentum Mobile App 6
Use case 2: When a favorite item got changed in the Documentum Repository for which the User is subscribed to and the same will be alerted to the user with the notification. Implementation Overview The mobile application server is not continuously polling the content server to get the task assignment or favorite item change. The Mobile Application server will get the list of assigned tasks and favorite item with the help a dm_method called MobilePushNotificationmethod. A table mobile_user_info also got created which stores the user information and device token and the active status of the users subscribed for push notifications. Dm methods used in Push notifications The following two methods are created in the content server when emc mobile dar is installed which helps in implementing the Push notification service in Documentum. MobilePushNotificationmethod This dm method polls the respective tables in the content server to get the list of tasks assigned and favorite item changes which will be passed on to the mobile server. AppleFeedBackServiceInvoker This method regularly polls the APNS to get the list of inactive users for which notification delivery failed after repeated attempts by the APNS and these users are deleted from the mobile_user_info table. Organization Network (inside Firewall) Pushes notifications and polls for failed deliveries CONTENT SERVER Task for MU1 EMC Documentum Mobile Server Task for MU3 FI change for MU2 Task for MU2 ch ipad Apple Push Notification in EMC Documentum Mobile App 7
IT challenges The provider(here The EMC Mobile App server) communicate with Apple Push Notification service over a binary interface and the same for production environment is available through gateway.push.apple.com, port 2195; the binary interface of the sandbox (development) environment is available through gateway.sandbox.push.apple.com, port 2195. The user may establish multiple, parallel connections to the same gateway or to multiple gateway instances. The Mobile Server and ios devices are often behind firewalls so open the TCP port 2195(outbound) for sending the notification to the APNS and 2196(inbound and outbound) for feedback service. The IP address range for the push service is subject to change and it uses a load balancing scheme and the entire 17.0.0.0/8 address block is assigned to Apple, so can specify that range in your firewall rules accordingly. Configuring Documentum Content Server for Push Notification Follow the steps to configure Push Notifications for EMC Documentum Mobile Application. 1. Install the emc-documentum-mobile.dar to the docbase. 2. Configure the dm methods with Documentum Administrator as follows. 2.1 Configure the MobilePushNotificationmethod Login to Documentum Administrator as an Administrator. Navigate to Administration > Job Management > Jobs. Select MobilePushNotificationJob in the Jobs list page and go to Properties page. Navigate to the Method tab, and click the Edit link in the Arguments field. Enter -mobileserverurl <mobile application server web address> in the Enter new value field of the dialog box that opens, and click Add as follows -mobileserverurl http://<hostname:port>/<mobileservercontext> Eg : -mobileserverurl http://documentum.com/glass Note: Mobile server supports https protocol also. Select Pass standard arguments in the Method tab, and click OK. The method looks as follows after making the changes. Apple Push Notification in EMC Documentum Mobile App 8
2.2 Configure the AppleFeedBackServiceInvoker in the same way as in step 2.1 and looks like the following after making the changes. Configuring the EMC Documentum Mobile App to receive notifications 1. The apple device should be registered with apple and Notifications should be enabled and can be done in the following ways. While opening up the EMC Documentum Mobile for the first time, prompt the Users to enable notifications. User can explicitly turn on the notifications from device Settings-> Notifications and tap the Documentum under In Notification Center. 2. Should create a profile with Show Notification ON. If this is OFF user won t receive any Notifications even if Server pushes notifications to APNS. Configuring the EMC Documentum Mobile server for Apple push Notifications 1. The Mobile Application server should be installed where the notification ports (2195 and 2196) are opened outside the organization firewall. 2. The following property has to be set to true in mobile-client-settings.xml to enable the Show Notifications option in the EMC Documentum Mobile Apps Settings screen. <property name="allow.savepassword" value="true"/> If this is not set to true, the MOBILE USER won t be able to create a profile or modify the existing profile with Show Notifications option ON. Apple Push Notification in EMC Documentum Mobile App 9
Mobile User receives and views the Push Notifications The Mobile user can receive the notifications in the following ways. a. As an alert b. As a Banner Mobile User can tap the banner or click on OK button to view the notification content. The app will automatically opens up if not running in the foreground. The user can pull the notifications screen to view all the available notifications. User can configure the way the notifications should appear in the device as shown above from Device settings->notifications->emc Documentum Mobile. Troubleshooting Even if APNS does not guarantee the delivery of the notifications, the MOBILE USERS can try the following if notifications are not received. 1. Check whether the device is connected to Wi-Fi or 3G network. If the device is not connected to the internet, won t be able to receive the notifications. The APNS will attempt to deliver the notifications a number of times and eventually marks a failure status. This in turn deactivates the user and further EMC Documentum Mobile server won t send notifications until and unless the user comes to Active state. The deactivated users can be made as effective by revisiting profile in the settings screen and turn ON the Show Notifications and save the profile which results in changing the user status active. 2. Check the user profile is created with Show Notifications ON. Go to Settings page in the EMC Documentum Mobile Application and tap the arrow next to the user profile. 2.1 Check whether the Show Notifications set to ON. Turn this to ON if this is off. Apple Push Notification in EMC Documentum Mobile App 10
2.2 If this is option is not activated, perform step 2 in section Configuring the EMC Documentum Mobile server for Apple push notifications for enabling the same. 3. Check whether the EMC Documentum Mobile App is listed in the Apple Device Notifications center. 3.1 Navigate to the Settings screen in the device, tap Notifications. In the Notifications screen Documentum should be listed as follows. 3.2 If the Documentum App is not listed under In Notification Center, then it will be available in No in Notification center. Tap the arrow next to Documentum and turn ON. This resulted in moving the Documentum under In Notification Center list and subsequently EMC Documentum Mobile App will be able to receive push notifications. 4. Check whether the Mobile User is active to receive notifications Query the mobile_user_info table through DQL editor with the following query Select isactive from mobile_user_info where user_name= <user name> If the query returns value 1 implies the user is still active and able to receive notifications. If the query returns value 0 implies the user is not active and won t be able to receive notifications. In this case the MOBILE USER has to revisit profile in the settings screen and turn ON the Show Notifications and save the profile which results in changing the user status active. Run the same query to ensure the user status turned to active. Apple Push Notification in EMC Documentum Mobile App 11
5. Check whether the Notification ports are opened Ensure that the Push Notification and Feedback service ports are opened outside organizational network firewall to contact the APNS server in the EMC Documentum Mobile server machine. 5.1 Push Notification Ports Open a command prompt and type the following telnet gateway.push.apple.com 2195 telnet feedback.push.apple.com 2196 If both are connecting, Mobile User can ensure that the ports are opened and Mobile Server is able to communicate with APNS Server. 5.2 If the above step is failing then do an nlslookup for the both the Apple gateways (gateway.push.apple.com andfeedback.push.apple.com) to get the IP ranges in which Apple allows the connection to the gateway. And ensure with IT security team that the ports are opened to these IP range. Apple periodically changes the IP ranges for security reasons. Conclusion The users would be able to get an understanding of the Apple Push Notification Services and how it is being implemented in the EMC Documentum Context. Explains the customer use cases in which Documentum leveraged the Apple Push Notification services which help in understanding the context of notifications in the Documentum. Briefly tells how to set up the devices to receive notifications and different ways the Mobile Users can receive the notifications. Trouble shooting section helps the users to rectify the common issues in the Push notifications. References APNS http://developer.apple.com/library/mac/#documentation/networkinginternet/conce ptual/remotenotificationspg/applepushservice/applepushservice.html EMC Documentum Mobile 1.2 Installation Guide (http://powerlink.emc.com click on Support > Technical Documentation and Advisories > Software ~ D ~ Documentation > Documentum D > Documentum Mobile > 1.x) Apple Push Notification in EMC Documentum Mobile App 12