Skip to main content

Customer Extension Development

Overview​

The Enactor product supports a wide variety of modifications to the standard Enactor workflow and functionality, some of which are described in the training documents on this site. This page describes the standard practice for setting up Maven projects in a structure that allows for easy Enactor development and deployment of custom processes and code onto customer systems.

If you are an Enactor customer interested in developing your own processes, you should have been provided with a workspace based on our template customer workspace. This page describes the layout and functionality of this customer development workspace.

What You Will Learn​

  • The default structure for customer extension projects
  • How to build customer extension projects

Requirements​

It is expected that customers will maintain their code in a source control (SCM) system such as Git or Subversion.

Eclipse is required for most Enactor development as access to the Enactor Tools plugin is recommended. Developer machines should have Eclipse and a locally-installed database, preferably MariaDB or MySQL.

The customer development workspace is built using Apache Maven and does not require any further software to be available on CI/CD environments.

Instructions​

The projects in the customer development workspace are described in the following sections.

Some of these projects are optional and may not have been configured for you if the functionality they provide is not currently required.

Root POM​

The Root POM is a Maven POM containing all of the project modules, and the managed versions for;

  • Enactor dependencies
  • Certain third-party dependencies
  • Maven plugin versions

The POM is intended as a starting point and customers can add their own settings and features as appropriate.

Setup Projects​

These projects are used to set up external dependencies and tools required for Enactor development.

GeneralRuntimeDependencies​

This project downloads various dependencies required for a runtime development environment (for example axis2, tomcat, Enactor licence code) and places them into the workspace so they can be used by Eclipse to execute the Enactor codebase.

This project can either be executed directly using Maven, or via the runtime-dependencies profile in the root POM.

It creates two directories in the workspace; EnactorHome and Software. The EnactorHome directory includes some runtime dependencies for the Enactor environment, including the licence manager and a MySQL JDBC driver. The Software directory includes software used by the Enactor environment such as Tomcat and Axis2.

Configuration Projects​

These projects package configuration into a format which is deployable to an Enactor development, test or production environment.

Configuration​

The configuration project gives a place for customer-specific configuration to be stored. The Maven build here zips this configuration and generates artifacts that are suitable for manual import into the Enactor Estate Manager (EM), for broadcast to the wider Estate.

[Customer]CommonData​

This contains the source for customer-specific data files, such as process connection diagrams or configuration exports, that are required to be included in a runtime distribution.

It is included in the Application Update zip and referenced in the POS run configuration.

Customisation Projects​

These projects allow customers to modify or extend the functionality of the Enactor software.

[Customer]PosCustomisation​

This contains the source code for customer classes, page definitions, processes and other files that are required during POS runtime.

It creates a jar file which is deployed to development, test and production systems as part of the application update zip and referenced in the execution projects.

[Customer]ReactPos​

The React POS contains all of the customer code required for customisations to the Enactor React POS screens and functionality.

It creates a jar file which is deployed to development, test and production systems as part of the application update zip and referenced in the execution projects.

Execution Projects​

The following projects are used to consolidate Enactor and Customer dependencies into a single project that can be executed using Eclipse for development purposes. They are intended for development machines only as a way of more easily executing this functionality within Eclipse

  • [Customer]PosSwingUI - This represents a (Swing) POS that can be executed using the Eclipse UI.
  • [Customer]ThinClient - This represents a (Swing) PDP Thin Client that can be executed using the Eclipse UI.
  • [Customer]ThinServer - This represents a PDP Server that can be executed using the Eclipse UI.
  • [Customer]WebPos - This project creates a WAR file that can be deployed to Tomcat using the Eclipse UI. It is used to support the React POS.
  • [Customer]WebMaintenance - This project creates a WAR file that can be deployed to Tomcat using the Eclipse UI. It is used to provide the web interface for the development EM.
  • [Customer]WebRetailProcessing - This project creates a WAR file that can be deployed to Tomcat using the Eclipse UI. It is used for processing operations on the development EM.

Deployment Projects​

The following projects create artifacts for deployment onto test and production systems.

DeployBuild​

This project packages all of the generated customer-specific artifacts into a folder structure suitable for deployment onto a remote file server or file share, if required.

The project builds the following folder structure, which can be modified as appropriate.

  • target\release\[Customer]\[Version] This contains the POS, Thin Client and Thin Server jar packages deployable to a development or test machine.
  • target\release\[Customer]\[Version]\Updates This contains the application update zip distributable.
  • target\release\[Customer]\[Version]\Configuration This contains configuration zip files importable into the EM.
  • target\release\[Customer]\[Version]\WebApplications This contains war files deployable to a development or test Tomcat server.
[Customer]ApplicationUpdate​

This project contains files required to package the customer-specific jars into an application update zip suitable for deployment from the Enactor Estate Manager to the estate.

For further information about this project, see Custom Application Updates

Other Projects​

It is recommended to create other projects to differentiate between different areas of your system's functionality, or for different teams to work on different features.

In order to work with the existing workspace, dependencies to these new projects need to be added to the following projects;

  • DeployBuild
  • [Customer]ApplicationUpdate
  • [Customer]PosSwingUI / [Customer]ThinServer (as appropriate)

Building​

The workspace can be built entirely using Apache Maven. You can either build the entire workspace in one go or build components separately. Builds are executed from the root directory.

Standard Build​

To execute a build run the following Maven command

mvn clean install

The Maven build requires access to Enactor's public Artifactory server https://artifactory.enactorondemand.com which contains the Maven dependencies for the Enactor Platform release the build uses. This requires that your Apache Maven configuration includes the credentials and repository configuration details that you have been provided by Enactor.

React POS Build​

The React POS is not included in the standard build as it takes some time to execute. In order to include it, add the npm-maven-integration Maven profile to the build.

mvn clean install -Pnpm-maven-integration

The React POS build requires access to Enactor's Verdaccio server (https://dev.enactor.co.uk:4874), which contains the React dependencies for the Enactor Platform release the build uses. This requires access credentials to be defined which can be done in a number of ways;

  • The [Customer]ReactPos\pom.xml file can be edited to define the npm.registry.username and npm.registry.password properties.
  • The credentials can be defined on the build command line by adding -Dnpm.registry.username=[username] -Dnpm.registry.password=[password]
  • Enactor can add your office/VPN IP addresses to a whitelist that can bypass the need for authentication from developer and CI/CD environments.
  • You can run your own Verdaccio (or other) proxy registry and proxy the Enactor Verdaccio server. The [Customer]ReactPos\pom.xml file should be edited with the correct npm.registry.url property.

Updating the Enactor Platform Version​

Your customer development workspace will have been configured to build using a certain version of the Enactor Platform. When you have been provided with a new Enactor release you will need to update the Enactor dependencies in the development workspace to match the version provided.

In order to do this, follow the process below.

  • Edit the root pom.xml file and change the platform.version property to the new Enactor Platform version.
  • Edit the GeneralRuntimeDependencies\pom.xml file and change the platform.version property to the new Enactor Platform version.
  • From the root folder, execute the following Maven command, which will automatically edit the relevant NPM configuration and download the latest runtime dependencies for the new Platform version. mvn clean install -Pupdate-npm-project-versions,runtime-dependencies -Denv-deploy-general-runtime-dependencies
  • Ensure you commit any changes the build has made to your source control system.

See Also​