actico rules - builder builder user guide · 3. a maven repository such as apache archiva or...

ACTICO Rules - Builder

Builder User Guide

Version 6.8

ACTICO GmbH

www.actico.com

Builder User Guide: Version 6.8Builder User Guide, Version 6.8

© ACTICO GmbH. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as well as inthe event of applications for industrial property rights.

Builder User Guide

Copyright © ACTICO GmbH iii

Table of Contents

1. Introduction ........................................................................................................................ 11.1. Configuring the License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2. Contents of the Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2. Using Maven ....................................................................................................................... 32.1. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2. Setting up the ACTICO Builder Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2.1. Installing Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2.2. Installing Maven . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2.3. Configuring a Maven Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.2.4. Installing ACTICO Builder Maven Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.3. Example Movie Ticket Pricing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.3.1. First Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.3.2. Importing the supplied Maven Example Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.3.3. Project Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.3.4. Configuring the pom.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.3.5. Building the Provided Maven Example Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.3.6. Deploying Rule Artifacts for Usage in ACTICO Modeler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.4. Maven Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.4.1. Configuring the License File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.4.2. Validating Rule Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.4.3. Testing Rule Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.4.4. Generating Documentation of Test Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.4.5. Generating Java Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.4.6. Generating Web Service Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.4.7. Generating Manifest File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.4.8. Validating Rule Models, Generating Java Source Code, Web Service Interface and Manifest File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.4.9. Checking in Files and Directories to an ACTICO Team Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.4.10. Checking out Rule Projects from an ACTICO Team Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.4.11. Creating and Populating a Branch in the ACTICO Team Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.4.12. Creating a tag in the ACTICO Team Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.4.13. Deploying to ACTICO Execution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.4.14. Generate Rules Archive (VRA) files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.4.15. Generating an ACTICO Rules Project Dependency Report or Maven Project Report . . . . . . . . . . . . 27

3. Using the Ant Tasks ........................................................................................................ 293.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293.2. Running the Example Ant Build Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293.3. Setting up the Ant Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313.4. Generating Java Rule Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.5. Compiling Java Rule Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333.6. Executing Rule Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333.7. Checking out Rule Projects from an ACTICO Team Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353.8. Checking in Files and Directories to an ACTICO Team Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.9. Creating and Populating a branch in the ACTICO Team Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.10. Creating a tag in the ACTICO Team Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373.11. Deploying Rule Artifacts to ACTICO Execution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.12. Deploying Rules Archive (VRA) Files to ACTICO Execution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Chapter 1. Introduction

Copyright © ACTICO GmbH 1

Chapter 1. IntroductionThe ACTICO Builder distribution is used to setup an automated rule change, test and deployment process. Theautomation is done using either Ant or Maven, two popular build automation tools for the Java platform.

The Builder distribution contains Maven plugins for the following:

• Validate rule models

• Test rules

• Generate documentation of test results

• Generate Java code from rule models

• Generate a web service interface

• Generate Manifest files

• Check in/out files to/from an ACTICO Team Server

• Create branches and tags on an ACTICO Team Server

• Deploy rule artifacts to an ACTICO Execution Server

• Generate Rule Archive (VRA) files

Further information about Maven is available on the internet at http://maven.apache.org/

The Builder distribution contains the following Ant tasks:

• Generation of Java code from rule models (including validation, WSDL and Manifest)

• Test rules

• Check in/out rule projects to/from an ACTICO Team Server

• Create branches and tags on an ACTICO Team Server

• Deploy rule artifacts to an ACTICO Execution Server

• Deploy a Rules Archive (VRA) to an ACTICO Execution Server

Further information about Ant is available on the internet at http://ant.apache.org/.

1.1. Configuring the License

The Builder components require a valid license. If the file containing the license resides in the default location,which is the .visualrules6 folder in the current user's home directory, no additional configuration isnecessary. Otherwise each task or plugin must be configured to read the license from a specified location. Seethe reference of either the Ant tasks or the Maven plugins for details.

1.2. Contents of the Distribution

The Builder components are distributed as a ZIP file with the following contents:

http://maven.apache.org/

http://ant.apache.org/

Chapter 1. Introduction


Table 1.1. Contents of the distribution

Folder Contents Usage

doc Manuals (German and English)

examples Examples Section 3.2, “Running the ExampleAnt Build Script”

Section 2.3.5, “Building theProvided Maven Example Project”

legalnotice License agreements,

list of 3rd party software

visualrules-ant-tasks Ant-tasks and their dependencies Chapter 3, Using the Ant Tasks

Section 3.3, “Setting up the AntTasks”

visualrules-maven-plugins Maven-plugins, theirdependencies, and installationscript

Chapter 2, Using Maven

Section 2.2.4, “Installing ACTICOBuilder Maven Plugins”

visualrules-runtime ACTICO Rules Runtime libraries Section 3.5, “Compiling Java RuleCode”

Section 3.6, “Executing Rule Tests”

Section 3.11, “Deploying RuleArtifacts to ACTICO ExecutionServer”

Chapter 2. Using Maven



2.1. Miscellaneous

The ACTICO Builder distribution contains different Maven Plugins for different purposes. For example thesePlugins can be used to test or build Rule Projects, to deploy Rule Projects to the ACTICO Execution Server orto checkout some projects from the ACTICO Team Server. The complete set of Maven Plugins can be foundin chapter Section 2.4, “Maven Plugins” . Some of these Plugins are used in the example Movie Ticket Pricingwhich is part of the ACTICO Builder distribution (see chapter Section 2.3, “Example Movie Ticket Pricing” ).To use this example the ACTICO Builder distribution has to be set up first. This is described in the followingchapter Section 2.2, “Setting up the ACTICO Builder Distribution”

2.2. Setting up the ACTICO Builder Distribution

Here is an overview of the steps that are necessary to setup the ACTICO Builder Distribution:

1. Installing the latest Java Development Kit (see: Section 2.2.1, “Installing Java”).

2. Installing the latest Maven (see: Section 2.2.2, “Installing Maven”).

3. A Maven Repository such as Apache Archiva or Artifactory can be used to provide ACTICO Builder MavenPlugins. Section Section 2.2.3, “Configuring a Maven Repository” describes how to configure Maven and theMaven Repository.

4. Finally section Section 2.2.4, “Installing ACTICO Builder Maven Plugins” explains how the Maven Plugins ofthe ACTICO Builder Distribution can be deployed to the repository.

2.2.1. Installing Java

To use the Maven Plugins or run the example of the ACTICO Builder distribution you need to have a JavaDevelopment Kit (JDK) installed and configured correctly. Please refer to the Builder System Requirementsdocument for supported versions. To download a JDK or to consult the documentation visit http://www.oracle.com. If you have already installed a JDK, please run following command to check if it is ready touse:

$java -version

If this command can not be executed successfully please verify if the environment variableJAVA_HOME is set and points to your local Java installation for example JAVA_HOME = C:\Programme\Java\jdk

2.2.2. Installing Maven

To use the ACTICO Rules Maven Plugins or run the example of the ACTICO Builder Distribution you need to havea Maven installed and configured properly. Please refer to the Builder System Requirements document forsupported versions. To download Maven or to consult the documentation visit http://maven.apache.org. If youhave already installed Maven, please run the following command to check if it is ready to use:

$mvn --version

If this command can not be executed successfully please verify if the environment variableM2_HOME is set and points to your local Maven installation for example M2_HOME = C:\Programme\Maven\apache-maven

http://www.oracle.com

http://www.oracle.com

http://maven.apache.org



2.2.3. Configuring a Maven Repository

The ACTICO Builder Maven Plugins and their dependencies must be accessible from a Maven repository such asApache Archiva or Artifactory. It must allow release type uploads and be able to host normal artifacts as wellas plugins and their dependencies.

In this manual it is assumed that there is already a local Artifactory installation for testing purposes. Detailedinformation concerning installing and configuring Artifactory can be found at http://www.jfrog.com/.

The following entries of your Maven settings file (settings.xml) have to be adapted so that the ACTICOBuilder Distribution can access Artifactory. The first entry is the remote repository which has to be added asnormal and as plugin repository. The other information is the server with username and password which needsto be added als well.

...<server> <id>localhost</id> <username>XXXXX</username> <password>XXXXX</password></server>...<repository> <id>releaseRepositoryID</id> <url>http://localhost:47080/artifactory/releases</url> <releases> <enabled>true</enabled> <updatePolicy>always</updatePolicy> </releases> <snapshots> <enabled>true</enabled> <updatePolicy>always</updatePolicy> </snapshots></repository>...

After these adaptions you can start installing the ACTICO Builder Maven Plugins. This is described below inSection 2.2.4, “Installing ACTICO Builder Maven Plugins”.

2.2.4. Installing ACTICO Builder Maven Plugins

The ACTICO Builder Maven Plugins must be accessible from a Maven repository. For this purpose the Builderdistribution contains a script to deploy the plugins to a Maven repository. The script is called deploy.cmd forusage on Windows based systems and deploy.sh for usage on Unix based systems.

The distribution and use of the ACTICO Builder Maven Plugins may only be carried out withrespect to the licence terms.

Before the deployment script can be used, it has to be edited in order to add or adapt some requiredinformation. The first five lines of the script are variable definitions. Informations about the used remoterepository have to be entered here. This example for the Windows script assumes running Artifactoryon the local machine (localhost) listening on port 47080 with a default configuration and an id calledreleaseRepositoryID as specified in the settings.xml of Maven.

set REPOSITORY_ID=releaseRepositoryIDset REPOSITORY_LAYOUT=defaultset URL=http://localhost:47080/artifactory/releasesset UNIQUE_VERSION=falseset GOAL=deploy:deploy-file

http://www.jfrog.com/



Table 2.1. Variables for the deployment script

Variable Description

REPOSITORY_ID The id of the remote repository. This has to be the same as configured in themaven settings in the <servers> section.

REPOSITORY_LAYOUT Whether this repository uses the default layout or the legacy layout.

URL URL of the Maven repository into which the artifact will be deployed.

UNIQUE_VERSION Whether to deploy snapshots with a unique version or not.

GOAL If you set GOAL to install:install-file, the Maven plugins will be installedinto the local Maven repository only. The default is deploy:deploy-file,which installs them into the repository specified by the URL above.

The artifacts in the Builder distribution are in the Maven 2 default layout. You can directly copythe artifacts into a Maven 2 repository to use them.

After these adjustments, the deployment of the ACTICO Builder Maven Plugins can be performed using thefollowing command:

$deploy.cmd$ set REPOSITORY_ID=releaseRepositoryID

$ set REPOSITORY_LAYOUT=default

$ set URL=http://localhost:47080/artifactory/releases

$ set UNIQUE_VERSION=false

$ set GOAL=deploy:deploy-file

$ REM set GOAL=install:install-file

...

2.3. Example Movie Ticket Pricing

2.3.1. First Steps

Before the Movie Ticket Pricing Maven example can be used the ACTICO Builder Distribution has to beinstalled and configured properly (see: Section 2.2, “Setting up the ACTICO Builder Distribution” ). Further theexample itself must be prepared. All necessary steps are described in the following chapters:

1. Importing the Movie Ticket Pricing Maven example (see Section 2.3.2, “Importing the suppliedMaven Example Project”)

2. Configuring the Maven Project Object Model (POM) (see Section 2.3.4, “Configuring the pom.xml”)

3. Building the provided Maven Example Project (see Section 2.3.5, “Building the Provided Maven ExampleProject”)

4. Deploying Rule Artifacts for Usage in ACTICO Modeler (see: Section 2.3.6, “Deploying Rule Artifacts for Usagein ACTICO Modeler”)

2.3.2. Importing the supplied Maven Example Project

To import the included sample project into the ACTICO Modeler, go to File -> Import and select "ExistingProjects into Workspace". Then click on "Next". In the following page choose "Select root directory" and openthe file open dialog. Navigate to the example folder of your installed ACTICO Builder Distribution. After you



confirm the selection the example project Movie Ticket Pricing Maven should be listed and checkedunder "Projects". Click on "Finish" to complete the import. Further details and a description of the projectstructure can be found at Section 2.3.3, “Project Structure”.

2.3.3. Project Structure

The Movie Ticket Pricing Maven example is structured differently than a "normal" rule project. Therule model and its files are found in the source folder src/main/rules. For the model to be included in theartifact, it is advisable to move them to a directory that does not conflict with the compiled byte code. For thisthe pom.xml contains the following configuration:

<project ...> ... <build> <resources> <resource> <targetPath>META-INF/visualrules/models</targetPath> <directory>src/main/rules</directory> </resource> </resources> ... </build> ... </project>

After a mvn package command, the model files will be found in the folder META-INF/visualrules/modelsin the JAR.

It is strongly advised that model files do not reside directly under src/main/rules or src/main/resources without the configuration mentioned above. In that case it is likely thatthe model folders and the packages of the generated code are conflicting in regard to casesensitivity, which will lead to an unusable rule artifact.

Another thing to notice is the target folder where Maven puts all created files as well as the compiled bytecode. In the example, the code generator is configured to use target/generated-sources/visualrulesas target folder. It is a source folder, so it can be used within Eclipse as well as in a Maven build.

After a successful build using the mvn package command, the created rule artifact can also be found in thetarget folder.

2.3.4. Configuring the pom.xml

The example Movie Ticket Pricing Maven demonstrates how Rule Projects are validated and Java sourcecode is generated. Furthermore it shows how the resulting artifacts are deployed onto the ACTICO Team Serverand ACTICO Execution Server. To demonstrate that the pom.xml needs to be adapted as follows:

1. Setting the backend URL and login data to the ACTICO Team Server and ACTICO Execution Server. Thismight look like the following example:

<properties> ... <teamserver_backend_url>http://localhost:8282/teamserver</teamserver_backend_url> <executionserver_url>http://localhost:8282/visualrules-executionserver</executionserver_url> <demoUserName>Guest</demoUserName> <demoPassword>XXXXX</demoPassword> <demoTenant>TEST</demoTenant> <demoOwnerTenant>TEST</demoOwnerTenant> ...</properties>

2. Setting the ACTICO Team Server Repositories. In this step the entry <repository>repo1</repository>of the visualrules-team-maven-plugin Plugin configuration needs to be set to the existingrepository in the Team Server. This affects the Maven goals: checkin, checkout, branch and tag. In thefollowing example this is shown for the Maven goal checkin:



<destination>Movie Ticket Pricing Maven</destination> ...<repository>repo1</repository><commitComment>example commit</commitComment><fileset>...

3. Finally a Maven Repository (see: Section 2.2.3, “Configuring a Maven Repository”) has to be configuredso that a build process can provide the generated Maven artifacts. The following excerpt shows how thismight look for a default Artifactory installation. It defines two Maven Repositories. One for snapshots andone for releases. This is a concept of Maven, which is further explained in the documentation at http://maven.apache.org.

<distributionManagement> <snapshotRepository> <id>releaseRepositoryID</id> <uniqueVersion>false</uniqueVersion> <url>http://localhost:47080/artifactory/snapshots/</url> </snapshotRepository> <repository> <id>releaseRepositoryID</id> <url>http://localhost:47080/artifactory/releases/</url> </repository></distributionManagement></screen>

2.3.5. Building the Provided Maven Example Project

The following examples use Maven on the command line. For this a command prompt is required. This isspecific for the used operating system and is not explained here.

Open a command prompt and navigate to your workspace. Change the directory to Movie Ticket PricingMaven and enter mvn package in the prompt.

Maven will start the build process that will use Maven Plugins for Validation and Generation of Java sourcecode, WSDL, XML schema files and meta information. The result of the build is a Jar file that is usable as ruleartifact in ACTICO Modeler and on the Execution Server.

Additionally, a Rules Archive (VRA) file will be created. Besides the rule artifact, the VRA file contains allrequired dependencies. Please refer to Section 2.4.14, “Generate Rules Archive (VRA) files” and Section 3.12,“Deploying Rules Archive (VRA) Files to ACTICO Execution Server” for further information.

In order to execute the install phase, an ACTICO Execution Server and ACTICO Team Server isrequired. Please ensure that your servers are fully configured and running. If not, please deletethe corresponding entries in the pom.xml file.

Furthermore, the pom.xml file has to be adapted to your servers. The most important settingscan be done in the <properties> element at the top of the file. However, some settings alsoneed to be done in the corresponding <plugin> elements, e.g. the specification of a repositorywhich has to exist on your ACTICO Team Server.

The calls of visualrules-team-maven-plugin are for ACTICO Team Server and demonstrate the functionsdescribed in the following sections:

• Section 2.4.9, “Checking in Files and Directories to an ACTICO Team Server”

• Section 2.4.10, “Checking out Rule Projects from an ACTICO Team Server”

• Section 2.4.11, “Creating and Populating a Branch in the ACTICO Team Server”

• Section 2.4.12, “Creating a tag in the ACTICO Team Server”

The calls of visualrules-deploy-maven-plugin are for ACTICO Execution Server and demonstrate thefunctions described in the following sections:

• Section 2.4.13, “Deploying to ACTICO Execution Server”

The pom.xml in the example project is configured to deploy the rule artifact to a default installation of anACTICO Execution Server. Before proceeding make sure the server is running. The Maven Deploy Plugin is





executed during the install build phase. By entering mvn install in the prompt the build process startsagain installing the artifact into the local Maven repository and deploying it to the ACTICO Execution Server.

2.3.6. Deploying Rule Artifacts for Usage in ACTICO Modeler

Maven manages its artifacts in repositories. The basic idea is that a built project results in an artifact that isdeployed to a repository from where other clients can download it. The rule artifact produced by this buildis suitable to be used in such a way and can be used as dependency in ACTICO Modeler. This requires thedeployment to a Maven repository using the mvn deploy command. For this the distributionManagemententry has to be added to the pom.xml of the project. This is described in chapter Section 2.3.4, “Configuringthe pom.xml”.

2.4. Maven Plugins

The ACTICO Builder distributions contains different Maven Plugins for the underlying functions in ACTICO:

• visualrules-validation-maven-plugin for validating rule models

• visualrules-testing-maven-plugin for running rule tests

• visualrules-testdocgenerator-maven-plugin for creating a documentation of test results

• visualrules-javagenerator-maven-plugin for the generation of Java code

• visualrules-wsgenerator-maven-plugin for the generation of WSDL, WADL and XML schema files

• visualrules-wsdlgenerator-maven-plugin. Deprecated: Use visualrules-wsgenerator-maven-plugin.

• visualrules-manifestgenerator-maven-plugin for creating the meta information for a rule artifact

• visualrules-team-maven-plugin for checking in files, checking out files, working with branches, andcreating tags on an ACTICO Team Server

• visualrules-deploy-maven-plugin for deploying a rule artifact to an ACTICO Execution Server

• visualrules-archive-maven-plugin for creating a Rules Archive (VRA) file

• visualrules-project-dependency for generation of an ACTICO Rules Project Dependency Report orMaven Project Report

For the following sections it is assumed that Maven is already installed and configured.Instructions and downloads can be found on the Maven website at http://maven.apache.org.

By default Eclipse does not provide a Maven integration out of the box. Therefore, ACTICOModeler, which is built upon the Eclipse platform, also does not provide any Maven integration.The m2e Eclipse project is providing a Maven integration for Eclipse.

2.4.1. Configuring the License File

If the license file is not in the default location as described in Section 1.1, “Configuring the License”, it isrequired to set the license file for each plugin. Be aware that this makes the build process platform dependent.

Maven supports the concept of profiles, which can be used to cope with platform dependentbuilds. Consult the Maven documentation for details.

2.4.2. Validating Rule Models

The Maven Validation Plugin applies all validation rules on every rule model in the project. If an error is founda build failure is triggered.


http://eclipse.org/m2e/

The purpose of the visualrules-validation-maven-plugin is to validate rule models before otherplugins start processing them. It is intended that it should run in the validate phase.

<build> ... <plugins> ... <plugin> <groupId>de.visualrules.builder</groupId> <artifactId>visualrules-validation-maven-plugin</artifactId> <version>${vrBuilderVersion}</version> <executions> <execution> <configuration>  <licensefile>C:\mycompany\mylicense.txt</licensefile>  <verbose>false</verbose>  <writeXmlReport>false</writeXmlReport> </configuration> <goals> <goal>validate</goal> </goals> </execution> </executions> </plugin> ... </plugins> ... </build>

Example 2.1. Example for the visualrules-validation-maven-plugin

Table 2.2. Parameters for the visualrules-validation-maven-plugin

Parameter Description Required Type

verbose If true all warning and error messages are printed tothe console, otherwise only the first error message.

No (default:false)

boolean

licensefile The path to a valid license file. This is required if thelicense file is not in the default location.

No File

writeXmlReport If true all validation messages are written to an XMLreport file. Reports are found in the reporting folder,e.g. target/site/visual-rules-reports

No (default:false)

boolean

2.4.3. Testing Rule Models

The visualrules-testing-maven-plugin is used to execute ACTICO Rules tests in the build process. Bydefault each test within the project will be run. If one of the tests does not pass the output of the build processis considered incorrect and thus a build failure is triggered. The plugin can also be configured to use a patternfor test suites. In that mode, all test suites found by the pattern are run. On test failure the same behaviorapplies as mentioned before. It is not possible to run tests and test suites at the same time.

The test results are printed by default to the console and as well written into a XML file. It is also possible towrite a more detailed report which also contains the statistics. This test report archive can be viewed in theACTICO Modeler. Reports are found in the reporting folder, e.g. target/site/visual-rules-reports. Thegeneration of a summarizing HTML documentation is described in Section 2.4.4, “Generating Documentation ofTest Results”.

Last but not least, there are options to configure the execution of all tests by defining a global bindingconfiguration and statistics level for requests and sessions. Note that this always will override any settingdefined in the individual test or test suite.

<build> ... <plugins> ... <plugin> <groupId>de.visualrules.builder</groupId> <artifactId>visualrules-testing-maven-plugin</artifactId> <version>${vrBuilderVersion}</version> <executions> <execution> <configuration>  <licensefile>C:\mycompany\mylicense.txt</licensefile>  <testSuitePattern>All Tests</testSuitePattern>  <writeTestReportArchive>true</writeTestReportArchive>  <writeXmlReport>true</writeXmlReport>  <activeConfigurationName>production</activeConfigurationName>  <requestStatisticsLevel>medium</requestStatisticsLevel>  <sessionStatisticsLevel>medium</sessionStatisticsLevel>  <verbose>false</verbose>  <storeHierarchically>true</storeHierarchically> </configuration> <goals> <goal>test</goal> </goals> </execution> </executions> </plugin> ... </plugins> ... </build>

Example 2.2. Example for the visualrules-testing-maven-plugin



Table 2.3. Parameters for the visualrules-testing-maven-plugin


verbose If true information about each executed test isprinted to the console.

No (default:false)

boolean


No File

testSuitePattern

The pattern denoting the test suites. This is typicallya file name that can contain wildcards. To expressone arbitrary character a ? is used and * for multiplearbitrary characters. For example the pattern All*would find All Tests as well as All NightlyTests.

No String

writeTestReportArchive

If true a archive will be created containing the testresults and statistics which can be viewed in theACTICO Modeler.

No (default:false)

boolean

writeXmlReport If true the test results are written in a simple XMLformat.

No (default:true)

boolean

activeConfigurationName

Name of the configuration for the rule execution thatwill be used by all tests.

No String

requestStatisticsLevel

The level of the statistics for the request to be used byall tests. Valid values are (not case-sensitive): QUIET,LOW, MEDIUM or HIGH.

No String

sessionStatisticsLevel

The level of the statistics for the session to be used byall tests. Valid values are (not case-sensitive): QUIET,LOW, MEDIUM or HIGH.

No String

storeHierarchically

If true the Reports will be stored in directoryhierarchies corresponding to the location of thetest. If false, a unique name will be created byconcatenating the directory names.

No (default:true)

boolean

2.4.4. Generating Documentation of Test Results

The visualrules-testdocgenerator-maven-plugin Maven Plugin is capable of generating asummarizing HTML documentation of all test results. It's necessary that the execution of tests, including thecreation of XML reports, has already taken place. The generated report TestResults.html is found in thesame reporting folder as the XML reports, e.g. target/site/visual-rules-reports.

It is intended that the report generation should happen in the site phase.

<build>... <plugins> ... <plugin> <groupId>de.visualrules.builder</groupId> <artifactId>visualrules-testdocgenerator-maven-plugin</artifactId> <version>${vrBuilderVersion}</version> <executions> <execution> <configuration>  <licensefile>C:\mycompany\mylicense.txt</licensefile> </configuration> <phase>site</phase> <goals> <goal>generate-testdoc</goal> </goals> </execution> </executions> </plugin> ...</plugins>...</build>

Example 2.3. Example for the visualrules-testdocgenerator-maven-plugin

Table 2.4. Parameters for the visualrules-testdocgenerator-maven-plugin



No File

2.4.5. Generating Java Source Code

The visualrules-javagenerator-maven-plugin Maven Plugin is responsible for generating Java sourcecode. Normally a folder in the target directory of the project is used. If a target folder is specified in the rulemodel, this will be used instead. However not all settings are applicable in a Maven build, e.g. when writing toa different project. For this the parameter targetDirectory can be set, which will override the setting fromthe model.

<build>... <plugins> ... <plugin> <groupId>de.visualrules.builder</groupId> <artifactId>visualrules-javagenerator-maven-plugin</artifactId> <version>${vrBuilderVersion}</version> <executions> <execution> <configuration>  <verbose>false</verbose>  <licensefile>C:\mycompany\mylicense.txt</licensefile>  <targetDirectory>target/vr-srcgen</targetDirectory> </configuration> <goals> <goal>generate</goal> </goals> </execution> </executions> </plugin> ...</plugins>...</build>

Example 2.4. Example for the visualrules-javagenerator-maven-plugin

Table 2.5. Parameters for the visualrules-javagenerator-maven-plugin


verbose If true, all warning and error messages are printedto the console, otherwise only two messages (at thebeginning and the end) are printed.

No (default:false)

boolean

targetDirectory The folder where the code generator places thesource. This can be an absolute or a relative path. Thissetting overrides the target directory defined in themodel.

No File

encoding Sets the encoding of the generated Java source code.If this setting is not configured, the default from theJava virtual machine is used. Note that the encodingon the rulemodel will always be used if it is specifiedthere.

No String


No File

2.4.6. Generating Web Service Interface

The visualrules-wsgenerator-maven-plugin Maven Plugin is capable of generating WSDL, WADL andXML schema files used for the Web Service interface. This enables the artifact to be used on the ACTICOExecution Server.

<build>... <plugins> ... <plugin> <groupId>de.visualrules.builder</groupId> <artifactId>visualrules-wsgenerator-maven-plugin</artifactId> <version>${vrBuilderVersion}</version> <executions> <execution> <configuration>  <licensefile>C:\mycompany\mylicense.txt</licensefile> </configuration> <goals> <goal>generate</goal> </goals> </execution> </executions> </plugin> ...</plugins>...</build>

Example 2.5. Example for the visualrules-wsgenerator-maven-plugin

Table 2.6. Parameters for the visualrules-wsgenerator-maven-plugin



No File

2.4.7. Generating Manifest File

The visualrules-manifestgenerator-maven-plugin is used to generate a manifest file and someadditional meta information files for the rule project. These are intended to be included in the Jar-Artifactof the project. Other ACTICO Decision Management Platform components, like ACTICO Modeler or ACTICOExecution Server, depend on these meta data when using the rule artifact. Furthermore, the manifest containsall required headers to deploy the rule artifact as OSGi bundle.

For more information about using rule artifacts as OSGi bundles, please refer to the JavaIntegration Guide.

<build>... <plugins> ... <plugin> <groupId>de.visualrules.builder</groupId> <artifactId>visualrules-manifestgenerator-maven-plugin</artifactId> <version>${vrBuilderVersion}</version> <executions> <execution> <configuration> <includesWebService>true</includesWebService>  <licensefile>C:\mycompany\mylicense.txt</licensefile>  <entryModel>MyModelName</entryModel> </configuration> <goals> <goal>generate</goal> </goals> </execution> </executions> </plugin> ... </plugins>...</build>

In order to include the created manifest in the artifact, the maven-jar-plugin must be configured asfollows:

<build>... <pluginManagement> ... <plugins> ... <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jar-plugin</artifactId> <configuration> <useDefaultManifestFile>true</useDefaultManifestFile> </configuration> </plugin> ... </plugins> </pluginManagement>...</build>

Example 2.6. Example for the visualrules-manifestgenerator-maven-plugin

Table 2.7. Parameters for the visualrules-manifestgenerator-maven-plugin


includesWebService

Set this to true, if used in conjunction with the WSDLGenerator Plugin.

Yes (Default:true)

boolean

entryModel If more then one rule model is in the project thenit is required to specify the name of the one thatis intended to be called as entry point. This can beomitted if only one model exists.

No String


No File

2.4.8. Validating Rule Models, Generating Java Source Code, Web Service Interface and Manifest File

The visualrules-combined-builder-maven-plugin comines these plugins:

• visualrules-validation-maven-plugin

• visualrules-javagenerator-maven-plugin

• visualrules-wsgenerator-maven-plugin

• visualrules-manifestgenerator-maven-plugin

Example:

<build>... <plugins> ... <plugin> <groupId>de.visualrules.builder</groupId> <artifactId>visualrules-combined-builder-maven-plugin</artifactId> <executions> <execution> <configuration> <includesWebService>true</includesWebService>  <verbose>false</verbose>  <licensefile>C:\mycompany\mylicense.txt</licensefile>  <targetDirectory>target/vr-srcgen</targetDirectory>  <entryModel>MyModelName</entryModel>  <writeXmlReport>false</writeXmlReport> </configuration> <goals> <goal>generate</goal> </goals> </execution> </executions> </plugin> ... </plugins>...</build>

Example 2.7. Example for visualrules-combined-builder-maven-plugin



Table 2.8. Parameters for the visualrules-combined-builder-maven-plugin


verbose If true all warning and error messages are printed tothe console, otherwise only the first error message.

No (default:false)

boolean

targetDirectory The folder where the code generator places thesource. This can be an absolute or a relative path. Thissetting overrides the target directory defined in themodel.

No File


No String

includesWebService

Set this to true if webservice files should be included Yes (Default:true)

boolean

entryModel If more then one rule model is in the project thenit is required to specify the name of the one thatis intended to be called as entry point. This can beomitted if only one model exists.

No String


No File

writeXmlReport If true all validation messages are written to an XMLreport file. Reports are found in the reporting folder,e.g. target/site/visual-rules-reports

No (default:false)

boolean

2.4.9. Checking in Files and Directories to an ACTICO Team Server

The following example illustrates how to check in a file or a directory to an ACTICO Team Server 6.x (separatelyavailable) with the aid of the Maven Plugin visualrules-team-maven-plugin:



<build>... <plugins> ... <plugin> <groupId>de.visualrules.builder</groupId> <artifactId>visualrules-team-maven-plugin</artifactId> <version>${vrBuilderVersion}</version> <executions> <execution> <configuration> <url>http://localhost:8080/teamserver</url> <username>admin</username> <password>admin</password> <tenant>DEFAULT</tenant> <destination>Movie Ticket Pricing</destination> <repository>RuleRepository</repository> <fileset> <directory>/var/jenkins_home/workspace/VRFF_vrff_release_6.8.x-DXBA7JYNPMWZTUV5L2XPYAHQKME7CWO67RYSZHRDYGTNAVPGPTUA/vrff/vr-VRB__builder-parent/doc</directory> <includes> <include>**/*</include> </includes> <excludes> <exclude>target/*</exclude> </excludes> </fileset> </configuration> <goals> <goal>checkin</goal> </goals> </execution> </executions> </plugin> ... </plugins>...</build>

Example 2.8. Example for visualrules-team-maven-plugin to checkin files and directories



Table 2.9. Parameters for the visualrules-team-maven-plugin to checkin files and directories


url The URL of the Team Server Backend (e.g. http://some.host.com:8080/teamserver). For Team Server6.x.x.

Yes URL

username The username used for login. Yes String

password The password used for login. Yes String

tenant The tenant name used for login. Yes String

owner The tenant who will own the files/directories. No (Default:tenant)

String

repository The name of the repository. Yes String

destination The name of the folder, in which the files anddirectories are to be checked in (will be created, ifnecessary).

Yes String

fileset Files and directories to be checked in. Yes Fileset

branch The target branch, in which the destination will beplaced.

No. If notspecified, thelatest branch inthe repositorywill be fetched.

String

encoding The encoding of the files to be checked in to the TeamServer.

No (Standard:The JavaEncoding)

String

commitComment

Comment for the check in. No (Standard:withoutcomment)

String

licensefile Path of the license file. No. If notspecified,the directory<user.home>/.visualrules6will be scannedfor a licensefile.

File

2.4.10. Checking out Rule Projects from an ACTICO Team Server

The following example illustrates how to check out a Rule Project from an ACTICO Team Server 6.x (separatelyavailable) with the aid of the Maven Plugin visualrules-team-maven-plugin:



<build>... <plugins> ... <plugin> <groupId>de.visualrules.builder</groupId> <artifactId>visualrules-team-maven-plugin</artifactId> <version>${vrBuilderVersion}</version> <executions> <execution> <configuration> <url>http://localhost:8080/teamserver</url> <username>admin</username> <password>admin</password> <tenant>DEFAULT</tenant> <repository>RuleRepository</repository> <branch>HEAD</branch> <project>RuleProject</project> <targetDirectory>/var/jenkins_home/workspace/VRFF_vrff_release_6.8.x-DXBA7JYNPMWZTUV5L2XPYAHQKME7CWO67RYSZHRDYGTNAVPGPTUA/vrff/vr-VRB__builder-parent/doc</targetDirectory> </configuration> <goals> <goal>checkout</goal> </goals> </execution> </executions> </plugin> ... </plugins>...</build>

Example 2.9. Example for visualrules-team-maven-plugin to checkout projects

You can check out a single project or all projects of a tag. To check out a single project specify the branch andproject parameter. To check out all projects of a tag specify the tag parameter.



Table 2.10. Parameters for the visualrules-team-maven-plugin to checkout projects


url The URL of the Team Server Backend (e.g. http://some.host.com:8080/teamserver). For Team Server6.x.x.

Yes URL




owner The tenant whose project(s) will be checked out. No (Default:tenant)

String

repository The name of the repository. Yes String

tag The name of the tag which contains the projects tocheckout. If this parameter is set, it is not possible tospecifiy the project and branch parameters.

Yes, if projectnot specified.

String

project The project which shall be checked out. Yes, if tag notspecified.

String

branch The branch of the project to checkout. No. If notspecified, thelatest branch inthe repositorywill be fetched.

String

targetDirectory The directory on the local file system where theproject should be placed.

Yes Directory

createSubDirectory

If true the files are checked out into a subdirectory ofthe targetDirectory, named like the project. If false,the files are checked out directly into targetDirectory.

No (Default:true)

Boolean


File

2.4.11. Creating and Populating a Branch in the ACTICO Team Server

The following example illustrates how to create a new branch in the ACTICO Team Server (version 6.x) andpopulate it with a project with the aid of the Maven Plugin visualrules-team-maven-plugin. Creating anew branch always also creates a new tag with the same name as the branch.



<build>... <plugins> ... <plugin> <groupId>de.visualrules.builder</groupId> <artifactId>visualrules-team-maven-plugin</artifactId> <version>${vrBuilderVersion}</version> <executions> <execution> <configuration> <url>http://localhost:8080/teamserver</url> <username>admin</username> <password>admin</password> <tenant>DEFAULT</tenant> <repository>RuleRepository</repository> <projects>Movie Ticket Pricing</projects> <branch>HEAD</branch> <newBranch>Version 1.0.x</newBranch> </configuration> <goals> <goal>branch</goal> </goals> </execution> </executions> </plugin> ... </plugins>...</build>

Example 2.10. Example for the visualrules-team-maven-plugin to create and populate a Branch in Team Server

Table 2.11. Parameters for the visualrules-team-maven-plugin


url The URL of the Team Server Backend (e.g. http://some.host.com:8080/teamserver).

Yes URL




owner The tenant who will own the new branch. No (Default:tenant)

String

repository The repository name. Yes String

newBranch Name of the branch to be newly created. Yes String

branch Specification of a given branch from which theprojects are to be copied.

No (standard:the latestbranch)

String

projects Specification of one or more projects, which areassigned to the newly generated branch. Multipleprojects can be separated by |.

Yes String

licensefile Path of the license file No. If notspecified,the directory<user.home>/.visualrules6will be scannedfor a licensefile.

File



2.4.12. Creating a tag in the ACTICO Team Server

The following example illustrates how to create a new tag in the ACTICO Team Server (version 6.x) with the aidof the Maven Plugin visualrules-team-maven-plugin:

<build>... <plugins> ... <plugin> <groupId>de.visualrules.builder</groupId> <artifactId>visualrules-team-maven-plugin</artifactId> <version>${vrBuilderVersion}</version> <executions> <execution> <configuration> <url>http://localhost:8080/teamserver</url> <username>admin</username> <password>admin</password> <tenant>DEFAULT</tenant> <repository>RuleRepository</repository> <branch>HEAD</branch> <resources>*</resources> <tag>NewTag</tag> </configuration> <goals> <goal>tag</goal> </goals> </execution> </executions> </plugin> ... </plugins>...</build>

Example 2.11. Example for the visualrules-team-maven-plugin to create a tag in Team Server

By specifying <resources>*</resources>, all projects in repository RuleRepository below the branch HEADwill be tagged as NewTag.

It is also possible to explicitely specify the resources to be tagged. Therefore enter the corresponding resourcepaths which have to be separated by a | symbol. For example this could look like:

<resources>project1|project2/src</resources>

In this case project project1 and the directory src, which is located in project2, will be tagged.



Table 2.12. Parameters for the visualrules-team-maven-plugin to create tags



Yes URL




owner The tenant whose resources will be tagged. No (Default:tenant)

String


branch The branch which contains the specified resources. No. If notspecified, thelatest branch inthe repositorywill be fetched.

String

resources Specification of one or more resources which areassigned to the newly generated tag. Multipleresources can be separated by |. The * charactercan be used to choose all projects in the specifiedrepository and branch.

Yes String

tag Name of the new tag. Yes String

tagComment A comment for the tag. No String


File

2.4.13. Deploying to ACTICO Execution Server

The visualrules-deploy-maven-plugin deploys a rule artifact and all dependencies to a running ACTICOExecution Server. This means that the plugin must run in a phase after the package phase.

<build>... <plugins> ... <plugin> <groupId>de.visualrules.builder</groupId> <artifactId>visualrules-deploy-maven-plugin</artifactId> <version>${vrBuilderVersion}</version> <configuration> <url>http://localhost:8080/executionserver</url> <user>admin</user> <password>admin</password> <tenant>DEFAULT</tenant>  <timeout>5000</timeout>  <licensefile>C:\mycompany\mylicense.txt</licensefile> </configuration> <executions> <execution> <phase>install</phase> <goals> <goal>vrdeploy</goal> </goals> </execution> </executions> </plugin> ...</plugins>...</build>

Example 2.12. Example for the visualrules-deploy-maven-plugin



Table 2.13. Parameters for the visualrules-deploy-maven-plugin


url The URL of the ACTICO Execution Server. Yes String

user The name of the user on the server. No, if the targetapplicationdoes notrequireauthentication

String

password The password of the user on the server. No, if the targetapplicationdoes notrequireauthentication

String

tenant The tenant name used for login. No, if the targetapplicationdoes notrequireauthentication

String

owner The tenant for whom the rule service shall bedeployed.

No (Default:tenant)

String

timeout The connection timeout in milliseconds. This must bea positive value.

No Integer


No File

active Sets the rule service active or inactive No Boolean

validFrom Sets the validFrom setting of a rule service. The valueis specified by: yyyy-MM-dd HH:mm:ss

No String

validTo Sets the validTo setting of a rule service. The value isspecified by: yyyy-MM-dd HH:mm:ss

No String

For more information on the settings active, validFrom, validTo refer to the Execution Server UserGuide.

2.4.14. Generate Rules Archive (VRA) files

The visualrules-archive-maven-plugin Maven plugin can be used to create Rules Archive (VRA) files.It is intended to run this plugin within or after the package phase; the package phase is also the defaultbehaviour. A VRA file contains, besides the actual rule artifact, all necessary dependencies and informationabout groupId, artifactId, and version of the contained files, making this a good choice when distributing todifferent environments like test or production.

The following example illustrates the usage of the visualrules-archive-maven-plugin Maven plugin:



<project> ... <build> ... <plugins> <plugin> <groupId>de.visualrules.builder</groupId> <artifactId>visualrules-archive-maven-plugin</artifactId> <version>${vrBuilderVersion}</version> <executions> <execution> <phase>package</phase> <goals> <goal>vrarchive</goal> </goals> </execution> </executions> </plugin> </plugins> </build></project>

Example 2.13. Example for the visualrules-archive-maven-plugin

Table 2.14. Parameters for the visualrules-archive-maven-plugin


licensefile The path to a valid license file. No. This isrequired ifthe licensefile is not inthe defaultlocation.

File

2.4.15. Generating an ACTICO Rules Project Dependency Report or Maven Project Report

The visualrules-project-dependency maven plugin allows to list dependencies (java artifacts) ofan ACTICO Rules Rule Project or Maven Project and to persist it in a so called Dependency report as XML. Agenerated Dependency report has the file extension vrdependency and is found in the same reporting folderas the XML reports, e.g. target/site/visual-rules-reports.

<build> ... <plugins> ... <plugin> <groupId>de.visualrules.builder</groupId> <artifactId>visualrules-project-dependency</artifactId> <version>${vrBuilderVersion}</version> <executions> <execution> <configuration>  <licensefile>C:\mycompany\mylicense.txt</licensefile>  <logReport>false</logReport> </configuration> <phase>package</phase> <goals> <goal>report</goal> </goals> </execution> </executions> </plugin> ... </plugins> ... </build>

Example 2.14. Example for the visualrules-project-dependency plugin

Table 2.15. Parameter for the visualrules-project-dependency plugin



No File

logReport True or False whether the content of the Dependencyreport should be displayed in the console output.

No String

The Builder distribution also supports the generation of Dependency reports using the command line.

For an ACTICO Rules Rule Project navigate to the project folder and execute the following command:

$mvn -f ruleproject.vr de.visualrules.builder:visualrules-project-dependency:report

For a Maven Project the following command has to be executed:

$mvn de.visualrules.builder:visualrules-project-dependency:report

Chapter 3. Using the Ant Tasks



3.1. Overview

The ACTICO Builder distribution contains the following Ant tasks:

• VRGenerate for the generation of Java code

• VRTest for testing of rules

• VRCheckout for checking out rule projects from an ACTICO Team Server

• VRCheckin for the checking in files into the ACTICO Team Server

• VRBranch for the generation and population of a branch in the ACTICO Team Server

• VRTag for the generation of a tag in the ACTICO Team Server

• VRDeploy for deploying rule artifacts to the ACTICO Execution Server

• VRArchiveDeploy for deploying Rule Archive (VRA) files to the ACTICO Execution Server

3.2. Running the Example Ant Build Script

The Builder distribution includes an example project to illustrate the use of the Ant tasks.

You need to have a Java Development Kit (JDK) and Apache Ant installed and configured correctlyto run the example. The bin folder of the Ant distribution must be on your PATH and theANT_HOME environment variable must be set. See http://ant.apache.org for details.

1. Open a command line and go to the Movie Ticket Pricing Ant folder. You can find it in theexamples folder of the Builder distribution, e.g.:

C:\VR-builder\examples\Movie Ticket Pricing Ant>

2. The project contains a build.xml file. This is an Ant build script that illustrates how to use the Ant tasks.Run Ant to execute the build script build.xml.

The Ant build script will generate the rule code (VRGenerate), compile it, and finally execute rule testsand a test suite (VRTest). The output will look like this:

http://ant.apache.org



C:\VR-builder\examples\Movie Ticket Pricing Ant>antBuildfile: build.xml

generateRuleCode:[VRGenerate] Generated 26 Java source files to C:\VR-builder\examples\Movie Ticket Pricing Ant\src-ant[VRGenerate] Generated wsdl to C:\VR-builder\examples\Movie Ticket Pricing Ant\src-ant\META-INF\visualrules\webservice[VRGenerate] Generated MANIFEST.MF to C:\VR-builder\examples\Movie Ticket Pricing Ant\src-ant\META-INF

compile: [javac] Compiling 25 source files to C:\VR-builder\examples\Movie Ticket Pricing Ant\bin-ant [javac] Note: Some input files use unchecked or unsafe operations. [javac] Note: Recompile with -Xlint:unchecked for details.

executeTests: [VRTest] Test 'BonusPoints Test' executed in 9ms (7/7 test cases processed, 1.29ms per case). [VRTest] Test 'Pricing Test' executed in 8ms (8/8 test cases processed, 1.0ms per case).

executeTestSuite: [VRTest] Test 'BonusPoints Test' executed in 3ms (7/7 test cases processed, 0.43ms per case). [VRTest] Test 'Pricing Test' executed in 5ms (8/8 test cases processed, 0.63ms per case). [VRTest] Test suite 'All Tests' processed.

all:

BUILD SUCCESSFULTotal time: 6 secondsC:\VR-builder\examples\Movie Ticket Pricing Ant>

3. If you have an ACTICO Execution Server, you can also run the deployArtifact target in build.xml tocreate a rule artifact and deploy it to the Execution Server (VRDeploy).

You will have to configure the parameters of the VRDeploy task in build.xml to match yourenvironment, i.e. you will have to specify the Execution Server URL, user name, and password.

If you run the deployArtifact target, the output will look like this:



C:\VR-builder\examples\Movie Ticket Pricing Ant>ant deployArtifactBuildfile: build.xml

generateRuleCode:[VRGenerate] Generated 26 Java source files to C:\VR-builder\examples\Movie Ticket Pricing Ant\src-ant[VRGenerate] Generated wsdl to C:\VR-builder\examples\Movie Ticket Pricing Ant\src-ant\META-INF\visualrules\webservice[VRGenerate] Generated MANIFEST.MF to C:\VR-builder\examples\Movie Ticket Pricing Ant\src-ant\META-INF

compile: [javac] Compiling 25 source files to C:\VR-builder\examples\Movie Ticket Pricing Ant\bin-ant [javac] Note: Some input files use unchecked or unsafe operations. [javac] Note: Recompile with -Xlint:unchecked for details.

createArtifact: [jar] Building jar: C:\VR-builder\examples\Movie Ticket Pricing Ant\movieticketpricing-1.0.jar

deployArtifact: [VRDeploy] Successfully deployed C:\VR-builder\examples\Movie Ticket Pricing Ant\movieticketpricing-1.0.jar as movie-ticket-pricing-ant:Movie-Ticket-Pricing-Ant:1.0 to http://localhost:8080/executionserver-4.6.1/admin/upload

BUILD SUCCESSFULTotal time: 6 secondsC:\VR-builder\examples\Movie Ticket Pricing Ant>

3.3. Setting up the Ant Tasks

In order to make Ant recognize the Builder Ant tasks in your build script, you have to define them withtaskdef tags. This is illustrated in the following snippet. All the JARs in the lib and runtime folders of theBuilder distribution are put on the classpath for the tasks.

You will have to set the property builder.home to the location where you have installed the Builderdistribution.

<property name="builder.home" value="C:\VR-builder" /> <path id="cp"> <fileset dir="${builder.home}/lib/" includes="*.jar"/> <fileset dir="${builder.home}/runtime/" includes="*.jar"/></path>

<taskdef name="VRGenerate" classname="de.visualrules.ant.java.codegeneration.internal.VRGenerate" classpathref="cp"/><taskdef name="VRTest" classname="de.visualrules.ant.java.execution.internal.VRTest" classpathref="cp"/><taskdef name="VRCheckout" classname="de.visualrules.ant.team.internal.VRCheckout" classpathref="cp"/><taskdef name="VRDeploy" classname="de.visualrules.ant.deploy.internal.VRDeploy" classpathref="cp"/><taskdef name="VRCheckin" classname="de.visualrules.ant.team.internal.VRCheckin" classpathref="cp" /><taskdef name="VRBranch" classname="de.visualrules.ant.team.internal.VRBranch" classpathref="cp" /><taskdef name="VRTag" classname="de.visualrules.ant.team.internal.VRTag" classpathref="cp" /><taskdef name="VRArchiveDeploy" classname="de.visualrules.ant.deploy.internal.VRArchiveDeploy" classpathref="cp" />

3.4. Generating Java Rule Code

The VRGenerate task is used for the generation of Java rule code. The task can be used as follows:

<VRGenerate modelFile="${modelFile}" targetDir="${src-dir}" >  <modelpath /> </VRGenerate>

Table 3.1. Parameters for the VRGenerate Ant task

Attribute Description Required Ant Type

modelFile Path to the rule model file. Yes file

targetDir Path to the target directory. Yes directory

modelpath A nested path denoting folders and jars that containadditional rule model files (e.g. referenced via ReusePackages).

No path

validateModel Whether or not the model should validated prior tocode generation.

No (default:true)

boolean

enableStatisticsAndListenerCode

Whether or not to enable the generation of the codenecessary to support collection of execution statisticsand custom listeners.

No (default:true)

boolean

checkPathLimit Whether or not to check, if the generated files exceedthe Windows path limit. If set to true the build willfail in case the limit is exceeded.

No (default:false)

boolean

generatemanifest

Whether or not to generate a MANIFEST.MF filecontaining informations about the Rule Model ornot. The resulting file will be created in the folder<targetDir>/META-INF..

No (default:false)

boolean

generatews Whether or not to generate WSDL, WADL and XMLschema files containing web service definitions of therules that are exported as web services. The resultingfiles will be created in the folder <targetDir>/META-INF/visualrules/webservice. When bothweb service generation and manifest generation areenabled the resulting manifest file will also containinformation about the web services.

No (default:false)

boolean

version Version of the Rule Project that contains the rulemodel file. Required if web service generation isactivated.

No (Yes, ifgeneratews istrue

String

generatewsdl Deprecated: Use generatews. No (default:false)

boolean


No String

licenseFile Path to a license file. If not specified the defaultlicense file location will be scanned for a license fileand the one found there will be used.

No file

3.5. Compiling Java Rule Code

The generated rule code can be compiled with the javac task. The generated code has dependencies toseveral libraries: the ACTICO Rules runtime library, several third party utility libraries and the librariesadditionally introduced by the user (for example for custom functions, Java type libraries etc.). These librarieshave to be on the classpath of the javac task in order to compile the code. In the example the compilation ofthe rule code looks as follows.

<javac srcdir="/var/jenkins_home/workspace/VRFF_vrff_release_6.8.x-DXBA7JYNPMWZTUV5L2XPYAHQKME7CWO67RYSZHRDYGTNAVPGPTUA/vrff/vr-VRB__builder-parent/doc/src-ant" destdir="/var/jenkins_home/workspace/VRFF_vrff_release_6.8.x-DXBA7JYNPMWZTUV5L2XPYAHQKME7CWO67RYSZHRDYGTNAVPGPTUA/vrff/vr-VRB__builder-parent/doc/bin-ant"> <classpath> <fileset dir="${visualrules-runtime}"> <include name="*.jar" /> </fileset> </classpath></javac>

3.6. Executing Rule Tests

The VRTest task can be used to execute one or more rule tests and/or test suites. In the example provided,the VRTest task is used as shown below.

<VRTest summaryReportDir="/var/jenkins_home/workspace/VRFF_vrff_release_6.8.x-DXBA7JYNPMWZTUV5L2XPYAHQKME7CWO67RYSZHRDYGTNAVPGPTUA/vrff/vr-VRB__builder-parent/doc/summaryReports" generateHtmlReport="true" executionResultDir="/var/jenkins_home/workspace/VRFF_vrff_release_6.8.x-DXBA7JYNPMWZTUV5L2XPYAHQKME7CWO67RYSZHRDYGTNAVPGPTUA/vrff/vr-VRB__builder-parent/doc/executionResults" failOnError="false" activeConfigurationName="default" verbose="true" requestStatisticsLevel="medium" sessionStatisticsLevel="medium">

 <tests> <fileset dir="/var/jenkins_home/workspace/VRFF_vrff_release_6.8.x-DXBA7JYNPMWZTUV5L2XPYAHQKME7CWO67RYSZHRDYGTNAVPGPTUA/vrff/vr-VRB__builder-parent/doc"> <include name="**/*.vrtest"/> </fileset> </tests>

 <modelPath> <pathelement location="/var/jenkins_home/workspace/VRFF_vrff_release_6.8.x-DXBA7JYNPMWZTUV5L2XPYAHQKME7CWO67RYSZHRDYGTNAVPGPTUA/vrff/vr-VRB__builder-parent/doc" /> </modelPath>

 <classpath> <pathelement location="/var/jenkins_home/workspace/VRFF_vrff_release_6.8.x-DXBA7JYNPMWZTUV5L2XPYAHQKME7CWO67RYSZHRDYGTNAVPGPTUA/vrff/vr-VRB__builder-parent/doc/bin-ant" /> </classpath></VRTest>



Table 3.2. Parameters for the VRTest Ant task

Attribute/Element

Description Required Ant Type

tests A nested path denoting all tests and/or test suiteswhich should be to executed.

Yes Path

modelpath A nested path denoting folders and jars that containadditional rule model files (e.g. referenced via reusepackages).

Yes Path

classpath A nested path denoting folders and/or jarscontaining the compiled rule code and/or additionalclasses (e.g. custom actions/functions or businessobject model).

Yes Path

summaryReportDir

Specifies the target directory for test summaryreports (simple xml files providing information aboutwhich tests failed and which not). If not assigned nosummary report will be created (default).

No String

generateHtmlReport

Set to true a summarizing report of all testresults is generated in HTML format and saved asTestResults.html in the directory specified bysummaryReportDir. If summaryReportDir isn'tdefined the HTML report won't be created.

No (default:false)

Boolean

executionResultDir

Specifies the target directory for execution files(*.vrexecution) These files can be copied into theACTICO Modeler to inspect detailed test results andexecution statistics. If not assigned no execution filewill be created (default).

No String

failOnError Set to true the VRTest task will raise an exceptionif at least one test execution failed. All tests will beexecuted.

No (default:true)

Boolean

activeConfigurationName

Specifies the name of the configuration whichshould be used for test execution. Overwrites allconfigurations that might be set on executed tests ortest suites.

No String

verbose If set to true status messages about test executionwill be reported on standard output.

No (default:false)

Boolean

requestStatisticsLevel

Overwrites the statistics level for every test case. No Enumeration(possilbe valuesare none,medium, high)

sessionStatisticsLevel

Overwrites the statistics level for entire tests. No Enumeration(possilbe valuesare none,medium, high)

licenseFile Path to a license file. If not specified the defaultlicense file location will be scanned for a license fileand the one found there will be used.

No File

storeHierarchically

If true the Reports will be stored in directoryhierarchies corresponding to the location of thetest. If false, a unique name will be created byconcatenating the directory names.

No (default:true)

Boolean



3.7. Checking out Rule Projects from an ACTICO Team Server

The following example illustrates how to checkout a rule project from an ACTICO Team Server 6.x.x with the aidof the VRCheckout task.

<VRCheckout url="http://localhost:8080/teamserver-6.x.x" username="vruser" password="secret" tenant="DEFAULT" repository="repo1" project="MyProject" targetdirectory="/var/jenkins_home/workspace/VRFF_vrff_release_6.8.x-DXBA7JYNPMWZTUV5L2XPYAHQKME7CWO67RYSZHRDYGTNAVPGPTUA/vrff/vr-VRB__builder-parent/doc" />

You can check out a single project or all projects of a tag. To check out a single project specify the branch andproject parameter. To check out all projects of a tag specify the tag parameter.

Table 3.3. Parameters for the VRCheckout Ant task


username The username to be used for login. Yes String

password The password to be used for login. Yes String


owner The tenant whose project(s) will be checked out. No (Default:tenant)

String

repository The name of the repository to checkout from. Yes String

tag The name of the tag which contains the projects tocheckout. If this parameter is set, it is not possible tospecifiy the project and branch parameters.

Yes, if projectnot specified.

String

branch The branch of the project to checkout. No. If notspecified, thelatest branch inthe repositorywill be fetched.

String

project The name of the project to checkout. Yes, if tag notspecified.

String

targetDirectory The directory on the local file system where theproject should be placed.

Yes Directory

createSubdirectory

If true the files are checked out into a subdirectory ofthe targetDirectory, named like the project. If false,the files are checked out directly into targetDirectory.

No (default:true)

boolean

licenseFile Path to a license file. No. If notspecified thedefault licensefile locationwill be scannedfor a licensefile and theone foundthere will beused.

File

url The URL of the Team Server Backend (e.g. http://some.host.com:8080/teamserver)

Yes URL



3.8. Checking in Files and Directories to an ACTICO Team Server

The following example illustrates how to check in a file or a directory to an ACTICO Team Server 6.x.x(separately available) with the aid of the task VRCheckin:

<VRCheckin url="http://localhost:8080/teamserver-6.x.x" username="vruser" password="secret" tenant="DEFAULT" repository="repo1" destination="testDest"> <fileset dir="/var/jenkins_home/workspace/VRFF_vrff_release_6.8.x-DXBA7JYNPMWZTUV5L2XPYAHQKME7CWO67RYSZHRDYGTNAVPGPTUA/vrff/vr-VRB__builder-parent/doc"> <include name="**/*" /> <exclude name="bin/*"/> </fileset> </VRCheckin>

Table 3.4. Parameters for the VRCheckin task


url The URL of the Team Server Backend (e.g. http://some.host.com:8080/teamserver)

Yes URL




owner The tenant who will own the files/directories. No (Default:tenant)

String

repository The name of the repository to check in to. Yes String

destination The name of the folder in which the files anddirectories are to be checked in (will be created, ifnecessary).

Yes String

fileset Files and directories to be checked in. Yes Fileset

branch The target branch, in which the destination will beplaced.

No. If notspecified, thelatest branch inthe repositorywill be fetched.

String

encoding The encoding of the files to be checked in to the TeamServer.

No (standard:the JavaEncoding)

String

licenseFile Path of the license file No. If notspecified,the directory<user.home>/.visualrules6will be scannedfor a licensefile.

File

commitComment

Comment for the check in. No (standard:withoutcomment)

String

3.9. Creating and Populating a branch in the ACTICO Team Server

The following example illustrates how to create a new branch in the ACTICO Team Server (version 6.x.x) andpopulate it with a project with the aid of the task VRBranch:



<VRBranch url="http://localhost:8080/teamserver-6.x.x" username="vruser" password="secret" tenant="DEFAULT" repository="repo1" projects="Movie Ticket Pricing Ant" newBranch="Release"/>

Table 3.5. Parameters for the VRBranch task



Yes URL




owner The tenant who will own the new branch. No (Default:tenant)

String


newBranch Name of the branch to be newly created. Yes String

branch Name of a given branch from which the projects are tobe copied.

No (standard:the latestbranch)

String

projects Specification of one or more projects, which areassigned to the newly generated branch. Multipleprojects can be separated by |.

Yes String


File

3.10. Creating a tag in the ACTICO Team Server

The following example illustrates how to create a new tag in the ACTICO Team Server (version 6.x.x) with the aidof the task VRTag:

<VRTag url="http://localhost:8080/teamserver-6.x.x" username="vruser" password="secret" tenant="DEFAULT" repository="repo1" branch="HEAD" resources="*" tag="NewTag"/>

By specifying resources="*", all projects in repository repo1 below the branch HEAD will be tagged asNewTag.

It is also possible to explicitely specify the resources to be tagged. Therefore enter the corresponding resourcepaths which have to be separated by a | symbol. For example this could look like:

resources="project1|project2/src"

In this case project project1 and the directory src, which is located in project2, will be tagged.



Table 3.6. Parameters for the VRTag task



Yes URL




owner The tenant whose resources will be tagged. No (Default:tenant)

String


branch The branch which contains the specified resources. No. If notspecified, thelatest branch inthe repositorywill be fetched.

String

resources Specification of one or more resources which areassigned to the newly generated tag. Multipleresources can be separated by |. The * charactercan be used to choose all projects in the specifiedrepository and branch.

Yes String

tag Name of the new tag. Yes String

comment A comment for the tag. No String


File

3.11. Deploying Rule Artifacts to ACTICO Execution Server

The VRDeploy task can be used to deploy a rule artifact to an Execution Server. To do so, the rule artifact hasto be created first. To create rule artifacts usable by the Execution Server a jar archive has to be created whichcontains special files that can be processed by the Execution Server. When using the Ant tasks to create such ajar archive perform the following steps:

• Set the generatemanifest attribute of the VRGenerate task to true. If it is desired to export and deployrules to the Execution Server then it is also necessary to set generatews to true.

• The MANIFEST.MF created by the VRGenerate task has to be the first entry in the jar archive. To make sureit is the first entry specify it as manifest explicitly when calling the jar ant task.

• In the resulting jar file the models that were used to generate the source code have to reside in the folderMETA-INF/visualrules/models.

• Create a ruleartifact.vr which describes all the transitive dependencies of this project. In this file allthe dependencies have to be specified with groupId, artifactId, and version. This file has to containboth the Java dependencies (for example the ACTICO Rules Runtime) and dependent rule artifacts. Takea look at the Movie Ticket Pricing Ant example available in the ACTICO Modeler for an exampleruleartifact.vr.

The following example illustrates how to deploy an artifact to an ACTICO Execution Server with VRDeploy.



Table 3.7. Parameters for the VRDeploy Ant task


username The user name to be used for the deployment. No, if the targetapplicationdoes notrequireauthentication

String

password The password to be used for the deployment. No, if the targetapplicationdoes notrequireauthentication

String


String

owner The tenant for whom the rule service shall bedeployed.

No (Default:tenant)

String

uploadURL The upload URL of the ACTICO Execution Server towhere the artifact is being deployed.

Yes String

fileToDeploy The absolute or relative location of the artifact that isbeing deployed.

Yes File

groupId The group id of the artifact that is being deployed. Yes String

artifactId The artifact id of the artifact that is being deplDoyed. Yes String

version The version of the artifact that is being deployed. Yes String

licenseFile Path to a license file No. If notspecified thedefault licensefile locationwill be scannedfor a licensefile and theone foundthere will beused.

File

timeOut Timeout in milliseconds (ms) for the deploymentconnection.

No. If notspecified adefault of5000ms (5seconds) isused.

Integer

active Sets the rule service active or inactive No. If notspecified thedefault ofExecutionServer is used.

Boolean

validFrom Sets the validFrom setting of a rule service. The valueis specified by: yyyy-MM-dd HH:mm:ss

No String

validTo Sets the validTo setting of a rule service. The value isspecified by: yyyy-MM-dd HH:mm:ss

No String



For more information on the settings active, validFrom, validTo refer to the Execution Server UserGuide.

Additionally, it is necessary to deploy all the dependent artifacts specified in the ruleartifact.vr tothe Execution Server. ACTICO Rules Runtime and its dependencies are always necessary for executing a ruleartifact. These jar archives can be found in the visualrules-runtime folder of the Builder distribution. Theyshould always be present in the ruleartifact.vr and be deployed on the Execution Server.

If DatabaseIntegrator is used in addition the visualrules-dbcruntime dependency has to be defined aswell:

When working with projects that have a lot of dependencies between each other and to variousJava libraries this process can become tedious, as you will have to create and maintain aruleartifact.vr for each project. Consider using Maven instead of Ant for your build system,which simplifies dependency management.

3.12. Deploying Rules Archive (VRA) Files to ACTICO Execution Server

As an alternative to VRDeploy, VRArchiveDeploy deploys Rule Archive (VRA) files, which can be buildwith ACTICO Team Server or downloaded from a running ACTICO Execution Server. The VRA file consists ofall dependencies and all necessary information about groupId, artifactId, and version of the contained files,making this a good choice when distributing to different environments like test or production.

The following snippet illustrates the deployment of "archive.vra" to a running Execution Server:

<VRArchiveDeploy username="admin" password="admin" tenant="DEFAULT" uploadURL="http://localhost:8080/executionserver" archiveFile="archive.vra"/>



Table 3.8. Parameters for the VRArchiveDeploy Ant task


username The user name to be used for the deployment. No, if the targetapplicationdoes notrequireauthentication

String

password The password to be used for the deployment. No, if the targetapplicationdoes notrequireauthentication

String


String

owner The tenant for whom the Rule Archive shall bedeployed.

No (Default:tenant)

String

uploadURL The upload URL of the ACTICO Execution Server towhere the artifact is being deployed.

Yes String

archiveFile The absolute or relative location of the Rules Archive(VRA) file that is being deployed.

Yes File

licenseFile Path to a license file No. If notspecified thedefault licensefile locationwill be scannedfor a licensefile and theone foundthere will beused.

File

timeOut Timeout in milliseconds (ms) for the deploymentconnection.

No. If notspecified adefault of5000ms (5seconds) isused.

Integer

active Sets all rule services in the archive active or inactive. No. If notspecified thedefault ofExecutionServer is used.

Boolean

For more information on the setting active refer to the Execution Server User Guide.

actico rules - builder builder user guide · 3. a maven repository such as apache archiva or...

Documents