Remote management of Java applications with Module Services
Tutorial, May 17, 2018 - 1:45pm, 4014 views
This tutorial shows how to remotely manage the Java MIDlets (on the Cinterion modules that support Java). All the functionalities available locally are also accessible remotely. It is possible to upload, install, run, stop, update or uninstall each application. There is also a possibility to see the installed and running apps.
This feature does not use OTAP.
As a precondition, you need to be registered to Module Services. Please see this link for more details: https://developer.gemalto.com/tutorial/how-register-cinterion-module-ser...
The module needs to be provisioned to Cinterion Module Services and The Service Agent needs to be activated on each module. Please see this link for information how to do it: https://developer.gemalto.com/tutorial/how-provision-your-first-els61-mo...
Uploading a Java MIDlet to the repository
Before the application can actually be installed on the module, it needs to be uploaded to the remote repository first. In order to do it, please prepare jar and jad files and log in to Module Services (https://mods.gemalto.io). Then choose ‘Settings’ from the top menu and when it opens, click on ‘File Storage’ on the left menu. Your private file storage will open.
Clicking on the application folder icon will expand the folder contents. To upload the application files, please choose the desired folder and click the upload icon on the right. Then just select the file on your disk and click ‘Open’. Each file in your private file storage can also be deleted or downloaded to your disk. If you are uploading the application with the name that already exists in the repository (for example to update the application), you need to delete the previous version first.
It is also possible to upload the application to the repository directly from ‘Application Management’ screen, which will be shown in the next section.
How to deploy a new application to an empty module
First find the module (the fastest way is to paste the IMEI number to the ‘Search IMEI’ field on the top menu). Then select it (click the round checkbox on the right).
Now there are two ways.
One way is to click on the device which will cause ‘Device Details’ to open.
Then click on ‘Application Manager’ icon on the bottom right. ‘Application Management’ screen will open.
It includes the list of all installed applications with additional information. The details will be covered in the next section.
To make sure that the presented list is up to date, please click ‘Get applications list from device’. It will be executed during the next connection of the device.
Here it is also possible to upload the application to the repository by clicking ‘Upload’ button in ‘Deploy a New Application’ section under the applications list.
Now it is possible to select the desired application from the drop-down list in ‘Deploy a New Application’ section. To finalize the installation process, just select the action from another drop-down list (currently there is only one action available – ‘Download, install, run’) and press ‘OK’.
The result can be traced on ‘Tasks’ panel – to open it, click ‘Tasks’ button on the top menu.
In this case, each task gets the standard name ‘Application manager’. Please note the small refresh button on the right which can be used for refreshing the status of the tasks.
To see more details about the current status of the particular task, please click the circle graph on ‘Execution Status’ area.
Details can be expanded for each module. In case of any error, the task can be retried. To do that – staying on this screen - just click the round checkbox on the right of the desired module and then ‘Retry’ button on the bottom.
For more details about tasks, results and error handling, please see this tutorial about the remote firmware update: https://developer.gemalto.com/tutorial/how-update-module-firmware-module-services
When finished, the application will be shown on the list of ‘Application Management’ screen.
Another way of installing the application is to choose the device (select the round checkbox on the right of the list of ‘Devices’ screen), expand ‘Take an action’ list available over the top of the list of devices and click ‘Application Management’. The following screen will be displayed:
Then you can choose the individual label which you can later use to identify the task on ‘Tasks’ panel (selectable from the top menu). Similarly to point 1, you also have to choose the application and action. Additionally, it is possible to adjust the individual start date and timeout. Then you click ‘OK’ and it’s done – the action will be initiated the next time the device will connect.
The results can be traced on ‘Tasks’ panel in the same way as in variant 1.
Reading out and understanding basic MIDlet information using the Application Manager
After the application is installed, it will be shown on the list of ‘Application Management’ screen. While on ‘Devices’ screen, click on device and then on ‘Application Manager’ icon.
The displayed list includes all the installed applications (including SLAE and JRC). The following information is available:
- Application name
- Auto start - if the app is enabled for automatic start, when the module boots
- Size – the application size in bytes
- Storage – the size of used RecordStore storage (if it’s not used, the size is 0) Please, see Java API for more details
- Status – if the app is currently running or it’s only installed but not running
- Action – here it is possible to change the application status – please, see the next chapter for more
How to control the application (run, stop, delete)
From the applications list on ‘Application Management’ screen it is possible to change the status of already installed applications. The following actions are available:
- Stop – the application will be stopped, but not uninstalled
- Delete – this will uninstall the application from device
To execute any of the above actions, just select it from the list and click ‘Apply’. It will be executed on the device the next time it connects.
How to update an already running application
The following steps are required:
- The new version needs to be loaded to the repository, as it has been described in section Uploading a Java MIDlet to the repository. If file names are the same the old jar and jad files have to be deleted before the new ones are uploaded.
- The running application needs to be stopped before new one can be installed. Please refer to section How to control the application (run, stop, delete).
- Then the new version can be installed on the module, as described in section How to deploy a new application to an empty module. The old application will be replaced with the new one in the same way as it’s done with AT^SJAM command.
The above means that after the device connects to the platform it will receive and execute the prepared tasks in the same order in which the tasks were created. So it will stop the running application first and then it will initiate the download of the new application.
Please note that in case of the default connection rate of 24 hours, the time needed to stop the old MIDlet, and install / run the new one will be of 2 days in the best case. The ‘old’ application will remain in status stopped for 1 full day.
Limitation for Agent versions 2.1.9 and below:
During the remote installation process the jad and jar files are not deleted from the module’s file system so the next attempt of uploading and installation of the files with the same names will not be possible. This does not apply to versions 2.2.0 and higher.
How to update multiple devices at the same time
It can be done in the very similar way as for one device. Just more devices need to be selected on the ‘Devices’ screen (round checkbox on the right of each device). Then the procedure is exactly the same as described in variant 2 for one device.
The results can be traced on ‘Tasks’ screen. When you choose the desired task (created for more than one device) and click the circle graph on ‘Execution Status’ panel, the “Task Execution Status” screen will open and it will contain details for each device (identified by IMEI number) separately.