Custom Application Updates

Overview

An application update (AU) is used to deploy custom code (Processes, Java) contained in jar files and any relevant associated dependencies to an Enactor deployed POS, PDP Server or PDC in the custom-lib folder. It is a zip file with files laid out in a specific structure.

What You Will Learn

This training task describes how to create such an application update and deploy it to a remote system.

Pre-Requisites

• A functioning Estate Manager to deploy the Application Update from
• A functioning remote system to deploy the created Application Update to.

Application Update Process

The following process is used when a target system applies a custom application update of this type.

• The device is notified that an update is available and downloads it.
• It extracts the update zip and confirms that the version listed in the UpdatePackage.xml file is greater than the version in the device's manifest.xml.
• It then executes the application updater which performs the remaining steps.
• The relevant Enactor services are stopped and any Enactor UI is killed.
• Files in the custom-lib directory matching a configured set of prefixes are removed in order to remove old versions of the updated files.
• The new files in the update are copied to the custom-lib directory.
• The machine is restarted. When it comes back up the new jars are available on the Enactor classpath.

Instructions

Creating the Maven Project structure

The application update project should contain the following files

• pom.xml - The Maven project file which creates the update zip.
• assemble-update.xml - A Maven Assembly Plugin configuration file which packages the various files into an update zip.
• UpdatePackage.xml - A descriptor for an Enactor application update, which tells the system what version the update applies to and contains configuration options for the update.
• RunCustomUpgrade_1.0.xml and RunCustomUpgradeRollback_1.0.xml - Enactor Processes that actually execute the steps required to update the target device, and rollback if a failure occurs.
• Various jars that are required to be deployed to the custom-lib folder on the target system.

Creating the POM

The pom needs to list the Maven dependencies corresponding to the jars, dlls or other files you need to be deployed.

<dependencies>
    <dependency>
        <groupId>com.enactor.template-customer</groupId>
        <artifactId>template-react-pos</artifactId>
        <version>${project.version}</version>
    </dependency>
    <dependency>
        <groupId>com.enactor.template-customer</groupId>
        <artifactId>template-common-data</artifactId>
        <version>${project.version}</version>
    </dependency>
    <dependency>
        <groupId>com.enactor.template-customer</groupId>
        <artifactId>template-pos-customisation</artifactId>
        <version>${project.version}</version>
    </dependency>
</dependencies>

The Maven Assembly Plugin is used to download and extract the Application Updater jar from the Enactor Platform version, which contains the RunCustomUpgrade_1.0.xml and RunCustomUpgradeRollback_1.0.xml processes that are required to execute the update.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <executions>
        <execution>
            <id>unpack-application-updater-jar</id>
            <phase>process-resources</phase>
            <goals>
                <goal>unpack</goal>
            </goals>
            <configuration>
                <artifactItems>
                    <artifactItem>
                        <groupId>com.enactor.core</groupId>
                        <artifactId>application-updater</artifactId>
                        <version>${platform.version}</version>
                        <type>jar</type>
                    </artifactItem>
                </artifactItems>
                <outputDirectory>${project.build.directory}/application-updater-jar</outputDirectory>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <dependency>
              <groupId>com.enactor.core</groupId>
            <artifactId>application-updater</artifactId>
            <version>${platform.version}</version>
          </dependency>
    </dependencies>
</plugin>

Finally the Maven Assembly plugin is executed to package the dependencies, the required processes and the UpdatePackage.xml file into a zip.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <executions>
        <execution>
            <id>make-update-assembly</id>
            <phase>package</phase>
            <goals>
                <goal>single</goal>
            </goals>
            <configuration>
                <descriptors>
                    <descriptor>assemble-update.xml</descriptor>
                </descriptors>
            </configuration>
        </execution>
    </executions>
</plugin>

Creating the Assembly file

The assembly file in this case is called assemble-update.xml and contains two main sections. The first packages the RunCustomUpgrade_1.0.xml and RunCustomUpgradeRollback_1.0.xml from the extracted Application Updater jar.

<!-- Upgrade file -->
<file>
    <source>target/application-updater-jar/META-INF/deployments/Process/ApplicationUpdater/RunCustomUpgrade_1.0.xml</source>
    <outputDirectory>ApplicationUpdater</outputDirectory>
</file>
<!-- Rollback file -->
<file>
    <source>target/application-updater-jar/META-INF/deployments/Process/ApplicationUpdater/RunCustomUpgradeRollback_1.0.xml</source>
    <outputDirectory>ApplicationUpdater</outputDirectory>
</file>

It also packages the UpdatePackage.xml file and applies filtering so placeholders for various Maven properties are resolved

<!-- Update package -->
<file>
    <source>src/main/resources/META-INF/updates/UpdatePackage.xml</source>
    <filtered>true</filtered>
</file>

Finally, dependencies are included in the zip.

<dependencySets>
    <dependencySet>
        <includes>
            <include>com.enactor.template-customer:template-react-pos:*:jar</include>
            <include>com.enactor.template-customer:template-common-data:*:jar</include>
            <include>com.enactor.template-customer:template-pos-customisation:*:jar</include>
        </includes>
    </dependencySet>
</dependencySets>

Customising the UpdatePackage.xml file

The UpdatePackage.xml file should be modified to define the enactor.applicationUpdater.DeleteFilesPrefixes update parameter. The parameter lists the prefixes that should be deleted from the custom-lib directory on the target system.

<!-- OPTIONAL: A comma-separated list of file prefixes for jar files to delete
			 For example, setting this to 'test,file' would delete all files with filenames that
			 start with 'test' or 'file' in the custom-lib directory -->
<core:value name="enactor.applicationUpdater.DeleteFilesPrefixes">template-pos,template-react-pos,template-common-data,template-pos-customisation</core:value>

Uploading and Broadcasting the Update

The Application Update should be uploaded to the Estate Manager using the Application Update Maintenance page. This will parse the update and add it to the Application Update Broadcaster page for future broadcast.

Once the update has been broadcast, the Broadcast History page can be used to confirm that it has been applied successfully.

See Also

• Customer Extensions