Mobile Labs Plugin for IBM Urban Code Deploy Thank you for deciding to use the Mobile Labs plugin to IBM Urban Code Deploy. With the plugin, you will be able to automate the processes of installing or removing apps from the deviceconnect app database, and you can optionally automate the process of installing and removing apps from mobile devices attached to and managed by deviceconnect. Requirements To use the Mobile Labs IBM Urban Code Deploy plugin, you will need: The.zip file containing the plugin code (dc_ucd_plugin.zip). An installed version of the Mobile Labs deviceconnectcli program. A deviceconnect installation IBM Urban Code Deploy, server and agent The plugin install file can be downloaded from the Mobile Labs customer portal. The deviceconnectcli program can be downloaded from the deviceconnect Web UI. The deviceconnectcli interpreter is a Microsoft Windows command- line program that can be dispatched by an IBM Urban Code Deploy Agent on Windows or on a Linux or Mac OS system. Either the Linux or the Mac OS system requires the mono package in order to run deviceconnectcli through agents on those systems. On Linux, both mono and the deviceconnectcli program must be reachable through the PATH environment variable. On Windows, where mono is not required, the program must be available through the PATH variable. Once mono and the deviceconnectcli program are installed, install the Mobile Labs plugin using the Web UI of IBM Urban Code Deploy. Supported Automation Steps The plugin supports four discrete automation steps: Install app into the deviceconnect data base (UploadApp) Remove app from the deviceconnect data base (DeleteApp) Install app onto a device (InstallApp) Remove app from a device (UninstallApp) Note that an app must first be loaded into the deviceconnect database before it can be moved onto a device. To automate the process of moving a new app build (for Android, an.apk file and for ios, an.ipa file) you can design a component process that performs these steps: 1. Remove old app version from device (UninstallApp) 2. Upload new app version to deviceconnect data base (UploadApp) 3. Install new app version to device (InstallApp)
Common Required Properties All properties passed to the plugin are simple text fields. All steps require the following properties: host the fully- qualified domain name of the deviceconnect host or its IP address username the login id of a deviceconnect administrator password the password for that account Step- Specific Properties For UploadApp only you must additionally supply the file name (fully- qualified path name) for the app to be uploaded. For DeleteApp you must additionally specify the app name as displayed on the deviceconnect app screen (as set by the developer). In the example below, the app name is Geocoder For InstallApp, and UninstallApp you must specify the app name and the name of a device as displayed on the deviceconnect devices screen. In the example below, the device name is 5SiPhone. Release Notes for Version 1 The version 1 plugin is restricted to device names and app names that do not have imbedded spaces.
Configuring and Installing the Plugin The plugin can be used on either Linux or Windows- based agents. Mobile Labs strongly recommends that you use a Windows- based agent. This is because the plugin calls the deviceconnectcli program - - which is a.net- based Windows command- line executable. In order for a Linux agent to run this program, the Linux system must have the mono package installed. To install an IBM Urban Code Deploy agent for Windows, download the agent from the IBM Urban Code Deploy Web user interface as explained in the IBM documentation. It may be easier to start the agent from the command line rather than start the agent as a Windows service because the agent may not pick up changes in environment variables unless you do. We also found it necessary to open certain ports on the agent system in order for the IBM Urban Code Deploy server to successfully retrieve messages that may occur while the plugin is running. Consult with IBM for the port numbers that must be opened for an agent. Example Deployment In the following section we document how to install and configure the plugin so that it can call the deviceconnectcli program on Windows. We used a Windows 8.1 Enterprise desktop running in a virtual machine. Once the IBM Urban Code Deploy agent is installed and running on the Windows system, you can download the Mobile Labs deviceconnectcli program from the deviceconnect web user interface. To do so, log into deviceconnect as an administrator and select the download option from the menu tab in the upper right- hand corner of the screen. Click the tab and a drop- down menu will appear: (shown below): For our example, we created a ucd directory in the logged- in user s home directory, in this case:- C:\Users\mlabs\ucd. When we installed the IBM Urban Code Deploy agent, we installed it in C:\Users\mlabs\ucd\agent. We selected the Download deviceconnect CLI option and were prompted for a location to save the deviceconnectcli.zip file. We used save as to place the zip
file in the C:\Users\mlabs\ucd folder. We then right- clicked on the deviceconnectcli.zip file and selected extract all. This created a subdirectory, C:\Users\mlabs\ucd\deviceConnectCLI that contains the executable for deviceconnectcli (MobileLabs.DeviceConnect.Cli.exe). We had previously set up the IBM Urban Code Deploy agent on this system, meaning that we had installed JAVA, set the JAVA_HOME environment variable, and installed the agent (which meant we also set GROOVY_HOME and included the groovy program in the system path). We added the deviceconnectcli directory to the system path. This is critical so that the plugin can find the executable and associated libraries. These are the relevant variables on our Windows desktop: Path=C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows \System32\WindowsPowerShell\v1.0\;C:\Users\mlabs\ucd\deviceConnectCLI;C :\ibm-java-jre-70-winx86_64\jre\bin;c:\users\mlabs\ucd\agent\opt\groovy-1.8.8\bin C:\Users\mlabs\ucd\deviceConnectCLI is included so that the plugin can call the deviceconnectcli program. C:\ibm-java-jre-70-win-x86_64\jre\bin is the path for JAVA. C:\Users\mlabs\ucd\agent\opt\groovy-1.8.8\bin is the path for groovy. We set the following additional environment variables: JAVA_HOME=C:\ibm-java-jre-70-win-x86_64\jre GROOVY_HOME=C:\Users\mlabs\ucd\agent\opt\groovy-1.8.8 After extracting the files in the deviceconnectcli directory, we deleted the downloaded zip file. Installing an invocation script - Windows Because the plugin can support both Windows and Linux agents, the plugin always calls the following script in order to invoke the deviceconnectcli program: mldc_invoke.cmd In Windows, this script can be created with Notepad; we placed ours in the deviceconnectcli directory where it can be invoked through PATH. The script contains only one line. On Windows, this is the content: MobileLabs.DeviceConnect.Cli.exe %*
We used Notepad to create this one- line script file in the C:\Users\mlabs\ucd\deviceConnectCLI directory. When the plugin executes mldc_invoke.cmd, it passes parameters from IBM Urban Code Deploy. The one- line script calls deviceconnectcli and passes any/all parameters along in the process (the meaning of %* ). Installing an invocation script Linux If you are installing the agent on Windows, you can skip this section. If you are installing the agent on Linux, the script command is slightly different. The script must still be named mldc_invoke.cmd and must be marked executable (you can also create a symbolic link named mldc_invoke.cmd). The script in Linux is also only one line long and looks like this: #!/bin/bash mono MobileLabs.DeviceConnect.Cli.exe "$@" On Linux, we named this file mldc_invoke.sh, gave it execute permission, included its subdirectory in the PATH, and made a symbolic link, mldc_invoke.cmd. Here is a console session where we created the symbolic link: [root@ucdserver bin]# ln -s mldc_invoke.sh mldc_invoke.cmd [root@ucdserver bin]# ls -l lrwxrwxrwx. 1 root root 14 Jun 5 10:36 mldc_invoke.cmd -> mldc_invoke.sh -rwxr-xr-x. 1 root root 77 May 13 09:13 mldc_invoke.sh Checking the script Before attempting to install or run the plugin, we checked whether the deviceconnectcli program was properly executable via PATH. To do this, we opened a command- line window and ran the script. Note that we did not run the script with the deviceconnectcli directory as the current directory. This ensured that the mldc_invoke.cmd script and the MobileLabs.DeviceConnect.Cli.exe program are properly reached through the PATH variable. This is what you should see: C:\Users\ryan>mldc_invoke.cmd 10.1.10.54 mike@ml.sys password -devicelist simple 5SiPhone Amazon_B0C91004245300T4 Amazon_B0C91004245614QW Apple ipad asus_015d32492608260d asus_05e89b1a IPhone 4S 01 MLiPadMini-F4KJMG New iphone 5C Amazon_D025A0A030270852 C:\Users\ryan> Of course you must substitute the host address, username, and password that are appropriate for your installation.
Ready to go Finally, we started the agent on the Windows system and turned our attention to IBM Urban Code Deploy. Using the Plugin in IBM Urban Code Deploy To begin using the plugin with IBM Urban Code Deploy, we downloaded the distributable, which is a zip file ready for loading into the server. In our case, the distributable was: Once loaded, the plugin appears in the list of plugins: We built an application process that moves an ios app from the Windows file system into the deviceconnect database and then replaces the app on a mobile device by deleting the old version and installing the new version. You can see this script in action in a video associated with a blog post on the Mobile Labs website:- http://mobilelabsinc.com/mobile- labs- partners- with- ibm- for- mobile- devops/
The screen capture below shows the IBM Urban Code Deploy application process for our app. It has three steps. The first step uninstalls the current version of the app from the real device. The second step uploads a new version of the app to the deviceconnect application database. The third step installs that new version to the real device where the old version was just removed. Parameters for these processes are attached to the component processes referenced by the app process. The dialog below shows an example of the parameters for the Install step:
Here, we named the process InstallApp and the remaining required parameters are the items needed by deviceconnectcli in order to carry out the app install. The deviceconnect server is at 10.1.10.54; the device on which we install the app is named 5SiPhone ; the app is called Geocoder. The remaining two parameters are the user and password to be used to authenticate the operation. In order to use such a process, of course, you will need to substitute values that are appropriate for your organization.