Builder User Guide. Version Visual Rules Suite - Builder. Bosch Software Innovations

(1)

Builder User Guide

Version 6.0.1

Bosch Software Innovations

Americas:

Bosch Software Innovations Corp. 161 N. Clark Street

Suite 3500

Chicago, Illinois 60601/USA

Asia:

Bosch Software Innovations c/o Robert Bosch (SEA) Pte Ltd 11 Bishan Street 21

Singapore 573943

Europe:

Bosch Software Innovations GmbH Ziegelei 7

88090 Immenstaad/GERMANY Tel. +49 7545 202-300

(2)

Visual Rules Builder User Guide, Version 6.0.1

Copyright © 2004-2012 Bosch Software Innovations GmbH

© Bosch Software Innovations GmbH, 2012. All rights reserved. Dissemination or reproduction of this publication or any part of it for any purpose or in any form whatsoever is not permitted without the prior express written consent of Bosch Software Innovations GmbH. Information contained in this publication may be subject to revision without advance notice. MLDS, Visual Rules and Work Frame Relations are registered trademarks of Bosch Software Innovations GmbH. BOSCH and the symbol are registered trademarks of Robert Bosch GmbH, Germany. Some of the product and company names used in this document are trademarks and/or registered trademarks. They are used explicitly for reference purposes and are, independent of marking, property of their respective owners.

(3)

Chapter 1. Introduction

The Visual Rules Builder distirubtion is used to setup an automated rule change, test and deployment process. The automation 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 rule models

• Generate documentation of test results • Generate Java code from rule models • Generate a web service interface • Generate Manifest files

• Check in files to a Visual Rules Team Server and work with braches • Deploy rule artifacts to a Visual Rules Execution Server

• Generate Visual Rules 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 rule projects to a Visual Rules Team Server • Check out rule projects from a Visual Rules Team Server • Create a branch on a Visual Rules Team Server

• Deploy rule artifacts to a Visual Rules Execution Server

• Deploy a Visual Rules Archive (VRA) to a Visual Rules 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 is necessary. Otherwise each task or plugin must be configured to read the license from a specified location. See the reference of either the Ant tasks or the Maven plugins for details.

1.2. Contents of the Distribution

(5)

Table 1.1. Contents of the distribution

Folder Contents Usage

doc Manuals (German and English)

examples Examples Section 3.2, “Running the Example

Ant Build Script”

Section 2.4, “Building the Provided Maven Example Project”

licenses 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 Ant Tasks”

visualrules-maven-plugins Maven-plugins, their dependencies, and installation script

Chapter 2, Using Maven

Section 2.2, “Installing Visual Rules Maven Plugins”

visualrules-runtime Visual Rules Runtime libraries as listed in

Table 3.7, “Visual Rules Runtime Dependencies”

and

Table 3.8, “Visual Rules DatabaseIntegrator Runtime Dependencies”

Section 3.5, “Compiling Java Rule Code”

Section 3.6, “Executing Rule Tests” Section 3.10, “Deploying Rule Artifacts to Visual Rules Execution Server”

(6)

Chapter 2. Using Maven

2.1. Overview

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

• 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-wsdlgenerator-maven-plugin for the generation of WSDL and XML schema files

• visualrules-manifestgenerator-maven-plugin for creating the meta information for a rule artifact • visualrules-team-maven-plugin for checking in files and working with branches in Visual Rules Team

Server

• visualrules-deploy-maven-plugin for deploying a rule artifact to a Visual Rules Execution Server • visualrules-archive-maven-plugin for creating a Visual Rules Archive (VRA) file

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, Visual Rules Modeler, which is built upon the Eclipse platform, also does not provide any Maven integration. The

M2 Eclipse Project is providing a Maven integration for Eclipse.

2.2. Installing Visual Rules Maven Plugins

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

The distribution and use of the Visual Rules Maven Plugins may only be carried out with respect to the licence terms.

The script will deploy the plugins and their dependencies to a remote Maven repository. It must allow release type uploads and host normal artifacts as well as plugins. For instance an Apache Archiva installation is suitable for the task.

Detailed instructions for installing and configuring Apache Archiva can be found on the Internet at

http://archiva.apache.org/

The remote repository has to be added to the Maven configuration as normal and as plugin repository. The username and password information needs to be added as well. Consult the Maven documentation for information on how to do this.

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

(7)

set REPOSITORY_ID=releaseRepositoryID set REPOSITORY_LAYOUT=default

set URL=http://localhost:9090/archiva/repository/releases/ set UNIQUE_VERSION=false

set GOAL=deploy:deploy-file

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 the maven 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 installed into 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 copy the artifacts into a Maven 2 repository to use them.

2.3. Configuring the License File

If the license file is not in the default location as described in Section 1.1, “Configuring the License”, it is required 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 dependent builds. Consult the Maven documentation for details.

2.4. Building the Provided Maven Example Project

In order to import the example project select File -> New -> Example... in the menu. In the Visual Rules category choose Visual Rules Example Project and click Next >. Select the Movie Ticket Pricing Maven example and click Finish.

The Maven Plugins used in this example must be found in a Maven repository such as Apache Archiva. It suffices to have a local installation running. The Builder distribution includes a script to install the Visual Rules Maven Plugins to a repository. This is further described in Section 2.2, “Installing Visual Rules Maven Plugins”.

The following examples use Maven on the command line. For this a command prompt is required. This is specific 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 Pricing Maven and enter mvn package in the prompt.

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

Additionally, a Visual Rules Archive (VRA) file will be created. Besides the rule artifact, the VRA file contains all required dependencies. Please refer to Section 2.16, “Generate Visual Rules Archive (VRA) files” and

Section 3.11, “Deploying Visual Rules Archive (VRA) Files to Visual Rules Execution Server” for further information.

The pom.xml in the example project is configured to deploy the rule artifact to a default installation of a Visual Rules Execution Server. Before proceeding make sure the server is running. The Visual Rules Maven Deploy Plugin is executed during the install build phase. By entering mvn install in the prompt the build process

(8)

starts again installing the artifact into the local Maven repository and deploying it to the Visual Rules Execution Server.

2.5. Deploying Rule Artifacts for Usage in Visual Rules Modeler

Maven manages its artifacts in repositories. The basic idea is that a built project results in an artifact that is deployed to a repository from where other clients can download it. The rule artifact produced by this build is suitable to be used in such a way and can be used as dependency in Visual Rules Modeler. This requires the deployment to a Maven repository using the mvn deploy command. For this the distributionManagement entry has to be added to the pom.xml of the project. This defines the repositories an artifact can be deployed to. These should be repositories that are configured in Visual Rules Modeler for downloading artifacts.

The following snippet shows how this may look like for a default installation of Apache Archiva. Two Maven repositories are defined: one for snapshots and one for releases. This is a concept of Maven, which is further explained in the documentation at http://maven.apache.org.

<project ...> ... <distributionManagement> <snapshotRepository> <id>snapshotRepositoryID</id> <uniqueVersion>false</uniqueVersion> <url>dav:http://localhost:8080/archiva/repository/snapshots/</url> </snapshotRepository> <repository> <id>releaseRepositoryID</id> <url>dav:http://localhost:8080/archiva/repository/releases/</url> </repository> </distributionManagement> ... </project> 2.6. Project Structure

The Movie Ticket Pricing Maven example is structured differently than a "normal" rule project. The rule model and its files are found in the source folder src/main/rules. For the model to be included in the artifact, it is advisable to move them to a directory that does not conflict with the compiled byte code. For this the 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/models in 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 that the model folders and the packages of the generated code are conflicting in regard to case sensitivity, 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 byte code. In the example, the code generator is configured to use target/generated-sources/visualrules as 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 the target folder.

(9)

2.7. Validating Rule Models

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

The purpose of the visualrules-validation-maven-plugin is to validate rule models before other plugins 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 to the console, otherwise only the first error message.

No (default: false)

boolean

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

No File

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

No (default: false)

boolean

2.8. Testing Rule Models

The visualrules-testing-maven-plugin is used to execute Visual Rules tests in the build process. By default each test within the project will be run. If one of the tests does not pass the output of the build process is considered incorrect and thus a build failure is triggered. The plugin can also be configured to use a pattern for test suites. In that mode, all test suites found by the pattern are run. On test failure the same behavior applies 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 to write a more detailed report which also contains the statistics. This test report archive can be viewed in the Visual Rules Modeler. Reports are found in the reporting folder, e.g. target/site/visual-rules-reports. The generation of a summarizing HTML documentation is described in Section 2.9, “Generating Documentation of Test Results”.

(10)

Last but not least, there are options to configure the execution of all tests by defining a global binding configuration and statistics level for requests and sessions. Note that this always will override any setting defined 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> </configuration> <goals> <goal>test</goal> </goals> </execution> </executions> </plugin> ... </plugins> ... </build>

(11)

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

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

No (default: false)

boolean

No File

testSuitePattern The pattern denoting the test suites. This is typically a file name that can contain wildcards. To express one arbitrary character a ? is used and * for multiple arbitrary characters. For example the pattern All* would find All Tests as well as All Nightly Tests.

No String

writeTestReport Archive

If true a archive will be created containing the test results and statistics which can be viewed in the Visual Rules Modeler.

No (default: false)

boolean

writeXmlReport If true the test results are written in a simple XML format. No (default: true) boolean active Configuration Name

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

No String

request StatisticsLevel

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

No String

session StatisticsLevel

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

No String

2.9. Generating Documentation of Test Results

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

(12)

<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.10. Generating Java Source Code

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

(13)

<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 printed to the console, otherwise only two messages (at the beginning and the end) are printed.

No (default: false)

boolean

targetDirectory The folder where the code generator places the source. This can be an absolute or a relative path. This setting overrides the target directory defined in the model.

No File

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

No String

No File

2.11. Generating Web Service Interface

The visualrules-wsdlgenerator-maven-plugin Maven Plugin is capable of generating WSDL and XML schema files used for the Web Service interface. This enables the artifact to be used on the Visual Rules Execution Server.

(14)

<build> ... <plugins> ... <plugin> <groupId>de.visualrules.builder</groupId> <artifactId>visualrules-wsdlgenerator-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-wsdlgenerator-maven-plugin

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

No File

2.12. Generating Manifest File

The visualrules-manifestgenerator-maven-plugin is used to generate this meta information. It is intended that this is used in conjunction with the Java- and WSDL Generator Plugin. If there are multiple rule models in the project, one must be chosen as entry point.

(15)

<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 for the Manifest file to be included in the artifact, the maven-jar-plugin must be configured as follows: <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

includesWeb Service

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

Yes boolean

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

No String

(16)

2.13. Checking in Files and Directories to a Visual Rules Team Server

The following example illustrates how to check in a file or a directory to a Visual Rules Team Server 6.x (separately available) 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>${basedir}</directory> <includes> <include>**/*</include> </includes> <excludes> <exclude>target/*</exclude> </excludes> </fileset> </configuration> <goals> <goal>checkin</goal> </goals> </execution> </executions> </plugin> ... </plugins> ... </build>

(17)

Table 2.8. 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 Server 6.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

repository The name of the repository. Yes String

destination The name of the folder, in which the files and directories are to be checked in (will be created, if necessary)

Yes String

fileset Files and directories to be checked in Yes Fileset

branch The target branch, in which the destination will be placed. No. If not specified, the latest branch in the repository will be fetched. String

encoding The encoding of the files to be checked in to the Team Server. No (Standard: The Java Encoding) String commit Comment

Comment for the check in. No (Standard:

without comment)

String

licensefile Path of the license file No. If not

specified, the directory <user.home>/ .visualrules6 will be scanned for a license file. File

2.14. Creating and Populating a Branch in the Visual Rules Team Server

The following example illustrates how to create a new branch in the Visual Rules Team Server (version 6.x) and populate it with a project with the aid of the Maven Plugin visualrules-team-maven-plugin:

(18)

<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.8. Example for the visualrules-team-maven-plugin to create and populate a Branch in Team Server

Table 2.9. 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

username The username used for login Yes String

password The password used for login Yes 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 the projects

are to be copied

No (standard: the latest branch)

String

projects Specification of one or more projects, which are assigned to the newly generated branch. Multiple projects can be separated by |.

Yes String

licensefile Path of the license file No. If not

(19)

2.15. Deploying to Visual Rules Execution Server

The visualrules-deploy-maven-plugin deploys a rule artifact and all dependencies to a running Visual Rules Execution 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/admin/upload</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.9. Example for the visualrules-deploy-maven-plugin Table 2.10. Parameters for the visualrules-deploy-maven-plugin

url The URL of the Visual Rules Execution Server. Yes String

user The name of the user on the server. Yes String

password The password of the user on the server. Yes String

timeout The connection timeout in milliseconds. This must be a 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 value is specified by: yyyy-MM-dd HH:mm:ss

No String

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

No String

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

(20)

2.16. Generate Visual Rules Archive (VRA) files

The visualrules-archive-maven-plugin Maven plugin can be used to create Visual Rules Archive (VRA) files. A VRA file contains, besides the actual rule artifact, all necessary dependencies and 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 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> <goals> <goal>vrarchive</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project>

Example 2.10. Example for the visualrules-archive-maven-plugin Table 2.11. Parameters for the visualrules-archive-maven-plugin

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

(21)

Chapter 3. Using the Ant Tasks

3.1. Overview

The Visual Rules 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 a Visual Rules Team Server • VRCheckin for the checking in files into the Visual Rules Team Server

• VRBranch for the generation and population of a branch in the Visual Rules Team Server • VRDeploy for deploying rule artifacts to the Visual Rules Execution Server

• VRArchiveDeploy for deploying Visual Rules Archive (VRA) files to the Visual Rules 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 correctly to run the example. The bin folder of the Ant distribution must be on your PATH and the ANT_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 the examples 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 tests and a test suite (VRTest). The output will look like this:

(22)

C:\VR-builder\examples\Movie Ticket Pricing Ant>ant Buildfile: 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 SUCCESSFUL Total time: 6 seconds

3. If you have a Visual Rules Execution Server, you can also run the deployArtifact target in build.xml to create 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 your environment, i.e. you will have to specify the Execution Server URL, user name, and password.

(23)

C:\VR-builder\examples\Movie Ticket Pricing Ant>ant deployArtifact Buildfile: 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 SUCCESSFUL Total time: 6 seconds

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 with taskdef tags. This is illustrated in the following snippet. All the JARs in the lib and runtime folders of the Builder 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 Builder distribution. <property name="builder.home" value="C:\VR-builder" />

3.4. Generating Java Rule Code

(24)

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 contain additional rule model files (e.g. referenced via Reuse Packages).

No path

validateModel Whether or not the model should validated prior to code generation. No (default: true) boolean enableStatistics AndListener Code

Whether or not to enable the generation of the code necessary to support collection of execution statistics and custom listeners.

No (default: true)

boolean

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

No (default: false)

boolean

generate manifest

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

No (default: false)

boolean

generatewsdl Whether or not to generate WSDL and XML schema files containing web service definitions of the rules that are exported as web services. The resulting files will be created in the folder <targetDir>/META-INF/visualrules/webservice. When both wsdl generation and manifest generation are enabled the resulting manifest file will also contain information about the web services.

No (default: false)

boolean

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

No String

licenseFile Path to a license file. If not specified the default license file location will be scanned for a license file and 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 to several libraries: the Visual Rules runtime library, several third party utility libraries and the libraries additionally introduced by the user (for example for custom functions, Java type libraries etc.). These libraries have to be on the classpath of the javac task in order to compile the code. In the example the compilation of the rule code looks as follows.

(25)

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.

<modelPath>

(26)

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 suites which should be to executed.

Yes Path

modelpath A nested path denoting folders and jars that contain additional rule model files (e.g. referenced via reuse packages).

Yes Path

classpath A nested path denoting folders and/or jars containing the compiled rule code and/or additional classes (e.g. custom actions/functions or business object model).

Yes Path

summaryReport Dir

Specifies the target directory for test summary reports (simple xml files providing information about which tests failed and which not). If not assigned no summary report will be created (default).

No String

generateHtml Report

Set to true a summarizing report of all test results is generated in HTML format and saved as TestResults.html in the directory specified by summaryReportDir. If summaryReportDir isn't defined the HTML report won't be created.

No (default: false)

Boolean

executionResult Dir

Specifies the target directory for execution files

(*.vrexecution) These files can be copied into the Visual Rules Modeler to inspect detailed test results and execution statistics. If not assigned no execution file will be created (default).

No String

failOnError Set to true the VRTest task will raise an exception if at least one test execution failed. All tests will be executed.

No (default: true) Boolean active Configuration Name

Specifies the name of the configuration which should be used for test execution. Overwrites all configurations that might be set on executed tests or test suites.

No String

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

No (default: false)

Boolean

request StatisticsLevel

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

StatisticsLevel

Overwrites the statistics level for entire tests. No Enumeration (possilbe values are none, medium, high) licenseFile Path to a license file. If not specified the default license

file location will be scanned for a license file and the one found there will be used.

No File

3.7. Checking out Rule Projects from a Visual Rules Team Server

The following example illustrates how to checkout a rule project from a Visual Rules Team Server 6.x.x with the aid of the VRCheckout task.

<VRCheckout url="http://localhost:8080/teamserver-6.x.x" username="vruser" password="secret" tenant="DEFAULT" repository="repo1"

(27)

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

tenant The tenant name used for login. Yes String

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

project The name of the project to checkout. Yes String

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

Yes Directory

create Subdirectory

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

No (default: true)

boolean

branch The branch of the project to checkout. No. If not specified, the latest branch in the repository will be fetched.

String

licenseFile Path to a license file. No. If not

specified the default license file location will be scanned for a license file and the one found there will be used.

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 a Visual Rules Team Server

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

(28)

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

username The username used for login. Yes String

password The password used for login. Yes String

repository The name of the repository to check in to. Yes String destination The name of the folder in which the files and directories

are to be checked in (will be created, if necessary).

Yes String

fileset Files and directories to be checked in. Yes Fileset

branch The target branch, in which the destination will be placed. No. If not specified, the latest branch in the repository will be fetched. String

encoding The encoding of the files to be checked in to the Team Server.

No (standard: the Java Encoding)

String

licenseFile Path of the license file No. If not

specified, the directory <user.home>/ .visualrules6 will be scanned for a license file. File commit Comment

Comment for the check in. No (standard:

without comment)

String

3.9. Creating and Populating a branch in the Visual Rules Team Server

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

(29)

Table 3.5. Parameters for the VRBranch task

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

Yes URL

username The username used for login. Yes String

password The password used for login. Yes 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 the projects

are to be copied.

No (standard: the latest branch)

String

projects Specification of one or more projects, which are assigned to the newly generated branch. Multiple projects can be separated by |.

Yes String

licenseFile Path of the license file No. If not

3.10. Deploying Rule Artifacts to Visual Rules Execution Server

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

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

• The MANIFEST.MF created by the VRGenerate task has to be the first entry in the jar archive. To make sure it 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 folder META-INF/visualrules/models.

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

The following example illustrates how to deploy an artifact to a Visual Rules Execution Server with VRDeploy. <VRDeploy username="admin" password="admin" fileToDeploy="artifact-1.0.jar"

uploadURL="http://localhost:8080/executionserver/admin/upload" groupid="yourgroupid" artifactid="YourArtifactId" version="1.0" />

(30)

Table 3.6. Parameters for the VRDeploy Ant task

username The user name to be used for the deployment. Yes String password The password to be used for the deployment. Yes String uploadURL The upload URL of the Visual Rules Execution Server to

where the artifact is being deployed.

Yes String

fileToDeploy The absolute or relative location of the artifact that is being 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 not

File

timeOut Timeout in milliseconds (ms) for the deployment connection. No. If not specified a default of 5000ms (5 seconds) is used. Integer

active Sets the rule service active or inactive No. If not specified the default of Execution Server is used.

Boolean

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

No String

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

No String

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

Additionally, it is necessary to deploy all the dependent artifacts specified in the ruleartifact.vr to the Execution Server. See the table below for a list of dependencies required by the Visual Rules Runtime that are always necessary for executing a rule artifact. These jar archives can be found in the runtime folder of the Builder distribution. They should always be present in the ruleartifact.vr and be deployed on the Execution Server.

(31)

Table 3.7. Visual Rules Runtime Dependencies

jar name groupId artifactId version

visualrules-runtime.jar de.visualrules visualrules-runtime 5.x.x

mail.jar javax.mail mail 1.4.2

activation.jar javax.activation activation 1.1

stax-api-1.0.jar stax stax-api 1.0

stax-1.2.0.jar stax stax 1.2.0

commons-collections-3.2.1.jar commons-collections commons-collections 3.2.1

commons-lang-2.5.jar commons-lang commons-lang 2.5

commons-logging-1.0.3.jar commons-logging commons-logging 1.0.3

xbean.jar org.apache.xmlbeans xmlbeans 2.4.0

If DatabaseIntegrator is used in addition the following dependency has to be defined as well:

Table 3.8. Visual Rules DatabaseIntegrator Runtime Dependencies

jar name groupId artifactId version

visualrules-dbcruntime.jar de.visualrules visualrules-dbcruntime 5.x.x

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

3.11. Deploying Visual Rules Archive (VRA) Files to Visual Rules Execution Server

As an alternative to VRDeploy, VRArchiveDeploy deploys Visual Rules Archive (VRA) files, which can be build with Visual Rules Team Platform or downloaded from a running Visual Rules Execution Server. The VRA file consists of all 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"

uploadURL="http://localhost:8080/executionserver/admin/upload" archiveFile="archive.vra"/>

(32)

Table 3.9. Parameters for the VRArchiveDeploy Ant task

username The user name to be used for the deployment. Yes String password The password to be used for the deployment. Yes String uploadURL The upload URL of the Visual Rules Execution Server to

where the artifact is being deployed.

Yes String

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

Yes File

licenseFile Path to a license file No. If not

File

timeOut Timeout in milliseconds (ms) for the deployment connection. No. If not specified a default of 5000ms (5 seconds) is used. Integer

active Sets all rule services in the archive active or inactive. No. If not specified the default of Execution Server is used.

Boolean

Builder User Guide. Version Visual Rules Suite - Builder. Bosch Software Innovations