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

Visual Rules Suite - Builder Builder User Guide Version 5.4 Bosch Software Innovations Americas: Bosch Software Innovations Corp. 161 N. Clark Street Suite 3500 Chicago, Illinois 60601/USA Tel. +1 312 368-2500 info@bosch-si.com www.bosch-si.com Asia: Bosch Software Innovations c/o Robert Bosch (SEA) Pte Ltd 11 Bishan Street 21 Singapore 573943 Tel. +65 6571 2220 info-sg@bosch-si.com www.bosch-si.com Europe: Bosch Software Innovations GmbH Ziegelei 7 88090 Immenstaad/GERMANY Tel. +49 7545 202-300 info-de@bosch-si.com www.bosch-si.de

Builder User Guide: Version 5.4 Visual Rules Builder User Guide, Version 5.4 Copyright 2004-2012 Bosch Software Innovations GmbH Bosch Software Innovations GmbH, 2004-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.

Builder User Guide Table of Contents 1. Introduction.. 1 1.1. Configuring the License. 1 1.2. Contents of the Distribution 1 2. Using Maven 3 2.1. Overview 3 2.2. Installing Visual Rules Maven Plugins. 3 2.3. Configuring the License.. 4 2.4. Building the Provided Maven Example Project.. 4 2.5. Deploying Rule Artifacts for Usage in Visual Rules Modeler 4 2.6. Project Structure.. 5 2.7. Validating Rule Models 5 2.8. Testing Rule Models 6 2.9. Generating Documentation of Test Results. 8 2.10. Generating Java Source Code 9 2.11. Generating Web Service Interface 10 2.12. Generating Manifest 11 2.13. Checking in s and Directories to a Visual Rules Team Server. 13 2.14. Creating and Populating a Version in the Visual Rules Team Server. 14 2.15. Deploying to Visual Rules Execution Server.. 15 3. Using the Ant Tasks 17 3.1. Overview. 17 3.2. Running the Example Ant Build Script.. 17 3.3. Setting up the Ant Tasks. 18 3.3.1. Defining the Ant Tasks with <taskdef>.. 18 3.3.2. Running Ant Scripts in Eclipse 19 3.4. Generating Java Rule Code with VRGenerate 20 3.5. Compiling Java Rule Code.. 21 3.6. Executing Rule Tests with VRTest.. 22 3.7. Generating the Rule Model Documentation with VRDoc.. 23 3.8. Checking out Rule Projects from a Visual Rules Team Server with VRCheckout. 24 3.9. Checking in s and Directories to a Visual Rules Team Server 25 3.10. Creating and Populating a Version in the Visual Rules Team Server. 26 3.11. Deploying Rule Artifacts to Visual Rules Execution Server with VRDeploy. 27 3.12. Deploying Visual Rules Archive (VRA) s to Visual Rules Execution Server with VRArchiveDeploy.. 29 Bosch Software Innovations GmbH iii/29

Chapter 1. Introduction 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 the following Maven plugins: Rule model validation Generation of Java code from rule models Generation of WSDL and XML schema files Generation of Manifest files Deploying rule artifacts to a Visual Rules Execution Server Further information about Maven is available on the internet at http://maven.apache.org/ The Builder distribution contains the following Ant tasks: Checking out rule projects from a Visual Rules Team Server Generation of Java code from rule models (including validation, WSDL and Manifest) Testing rules Generation of a rule project documentation Deploying rule artifacts 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.visualrules5 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 The Builder components are distributed as a ZIP file with the following contents: Bosch Software Innovations GmbH 1/29

Chapter 1. Introduction Table 1.1. Contents of the distribution Folder Contents Usage doc Manuals (German and English) eclipse Eclipse distribution containing the Ant tasks (mandatory for the VRDoc task) Section 3.3.2, Running Ant Scripts in Eclipse [19] examples Examples Section 3.2, Running the Example Ant Build Script [17] Section 2.4, Building the Provided Maven Example Project [4] lib runtime visualrules-mvnartifacts Java libraries containing the Ant tasks and their dependencies Visual Rules Runtime libraries as listed in Table 3.8, Visual Rules Runtime Dependencies [28] and Table 3.9, Visual Rules DatabaseIntegrator Runtime Dependencies [29] Deploy script with Maven artifacts and plugins Section 3.3.1, Defining the Ant Tasks with <taskdef> [18] Section 3.5, Compiling Java Rule Code [21] Section 3.6, Executing Rule Tests with VRTest [22] Section 3.11, Deploying Rule Artifacts to Visual Rules Execution Server with VRDeploy [27] Section 2.2, Installing Visual Rules Maven Plugins [3] Bosch Software Innovations GmbH 2/29

Chapter 2. Using Maven 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-plugin for validating rule models visualrules-testing-plugin for running tests visualrules-testdocgenerator-plugin for creating a documentation of test results visualrules-javagenerator-plugin for the generation of Java code visualrules-wsdlgenerator-plugin for the generation of WSDL and XML schema files visualrules-manifestgenerator-plugin for creating the meta information for a rule artifact visualrules-deploy-plugin for deploying an rule artifact to a Visual Rules Execution Server 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. 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 Bosch Software Innovations GmbH 3/29

Chapter 2. Using Maven Table 2.1. Variables for the deployment script Variable REPOSITORY_ID REPOSITORY_LAYOUT URL UNIQUE_VERSION GOAL Description The id of the remote repository. This has to be the same as configured in the maven settings in the <servers> section. Whether this repository uses the default layout or the legacy layout. URL of the Maven repository into which the artifact will be deployed. Whether to deploy snapshots with a unique version or not. 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 If the license file is not in the default location as described in Section 1.1, Configuring the License [1], 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 -> 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 [3]. 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. 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 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 Bosch Software Innovations GmbH 4/29

Chapter 2. Using Maven 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. 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-plugin is to validate rule models before other plugins start processing them. It is intended that it should run in the validate phase. Bosch Software Innovations GmbH 5/29

Chapter 2. Using Maven Example 2.1. Example for the visualrules-validation-plugin <build> <plugins> <plugin> <groupid>de.visualrules.maven</groupid> <artifactid>visualrules-validation-plugin</artifactid> <version>${vrversion}</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> Table 2.2. Parameters for the visualrules-validation-plugin Parameter Description Required Type verbose If true all warning and error messages are printed to the console, otherwise only the first error message. false) licensefile The path to a valid license file. This is required if the license file is not in the default location. 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 false) 2.8. Testing Rule Models The visualrules-testing-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 [8]. 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. te that this always will override any setting defined in the individual test or test suite. Bosch Software Innovations GmbH 6/29

Chapter 2. Using Maven Example 2.2. Example for the visualrules-testing-plugin <build> <plugins> <plugin> <groupid>de.visualrules.maven</groupid> <artifactid>visualrules-testing-plugin</artifactid> <version>${vrversion}</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> Bosch Software Innovations GmbH 7/29

Chapter 2. Using Maven Table 2.3. Parameters for the visualrules-testing-plugin Parameter Description Required Type verbose If true information about each executed test is printed to the console. false) licensefile The path to a valid license file. This is required if the license file is not in the default location. 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. writetestreportarchive If true a archive will be created containing the test results and statistics which can be viewed in the Visual Rules Modeler. false) writexmlreport If true the test results are written in a simple XML format. true) activeconfigurationname Name of the configuration for the rule execution that will be used by all tests. requeststatisticslevel 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. sessionstatisticslevel 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. 2.9. Generating Documentation of Test Results The visualrules-testdocgenerator-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. It is intended that the report generation should happen in the site phase. Bosch Software Innovations GmbH 8/29

Chapter 2. Using Maven Example 2.3. Example for the visualrules-testdocgenerator-plugin <build> <plugins> <plugin> <groupid>de.visualrules.maven</groupid> <artifactid>visualrules-testdocgenerator-plugin</artifactid> <version>${vrversion}</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> Table 2.4. Parameters for the visualrules-testdocgenerator-plugin Parameter Description Required Type licensefile The path to a valid license file. This is required if the license file is not in the default location. 2.10. Generating Java Source Code The visualrules-javagenerator-plugin Maven Plugin is responsible for generating Java source code. rmally 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. Bosch Software Innovations GmbH 9/29

Chapter 2. Using Maven Example 2.4. Example for the visualrules-javagenerator-plugin <build> <plugins> <plugin> <groupid>de.visualrules.maven</groupid> <artifactid>visualrules-javagenerator-plugin</artifactid> <version>${vrversion}</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> Table 2.5. Parameters for the visualrules-javagenerator-plugin Parameter Description Required Type 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. false) 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. 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. te that the encoding on the rulemodel will always be used if it is specified there. licensefile The path to a valid license file. This is required if the license file is not in the default location. 2.11. Generating Web Service Interface The visualrules-wsdlgenerator-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. Bosch Software Innovations GmbH 10/29

Chapter 2. Using Maven Example 2.5. Example for the visualrules-wsdlgenerator-plugin <build> <plugins> <plugin> <groupid>de.visualrules.maven</groupid> <artifactid>visualrules-wsdlgenerator-plugin</artifactid> <version>${vrversion}</version> <executions> <execution> <configuration> <licensefile>c:\mycompany\mylicense.txt</licensefile> </configuration> <goals> <goal>generate</goal> </goals> </execution> </executions> </plugin> </plugins> </build> Table 2.6. Parameters for the visualrules-wsdlgenerator-plugin Parameter Description Required Type licensefile The path to a valid license file. This is required if the license file is not in the default location. 2.12. Generating Manifest The visualrules-manifestgenerator-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. Bosch Software Innovations GmbH 11/29

Chapter 2. Using Maven Example 2.6. Example for the visualrules-manifestgenerator-plugin <build> <plugins> <plugin> <groupid>de.visualrules.maven</groupid> <artifactid>visualrules-manifestgenerator-plugin</artifactid> <version>${vrversion}</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> <usedefaultmanifest>true</usedefaultmanifest> </configuration> </plugin> </plugins> </pluginmanagement> </build> Table 2.7. Parameters for the visualrules-manifestgenerator-plugin Parameter Description Required Type includesweb- Service Set this to true, if used in conjunction with the WSDL Generator Plugin. 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. licensefile The path to a valid license file. This is required if the license file is not in the default location. Bosch Software Innovations GmbH 12/29

Chapter 2. Using Maven 2.13. Checking in s 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 5.x (separately available) with the aid of the Maven Plugin visualrules-team-plugin: Example 2.7. Example for visualrules-team-plugin to checkin files and directories <build> <plugins> <plugin> <groupid>de.visualrules.maven</groupid> <artifactid>visualrules-team-plugin</artifactid> <version>${vrversion}</version> <executions> <execution> <configuration> <url>http://localhost:8080/teamserver</url> <username>admin</username> <password>admin</password> <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> Bosch Software Innovations GmbH 13/29

Chapter 2. Using Maven Table 2.8. Parameters for the visualrules-team-plugin to checkin files and directories Parameter Description Required Type url The URL of the Team Server Backend (e.g. http:// some.host.com:8080/ teamserver). For Team Server 5.x.x. URL username The username used for login password The password used for login repository The name of the repository. destination The name of the folder, in which the files and directories are to be checked in (will be created, if necessary) fileset s and directories to be checked in set version The target version, in which the destination will be placed.. If not specified, the latest version in the repository will be fetched. encoding The encoding of the files to be checked in to the Team Server. (Standard: The Java Encoding) commitcomment Comment for the check in. (Standard: without comment) licensefile Path of the license file. If not specified, the directory <user.home>/.visualrules5 will be scanned for a license file. 2.14. Creating and Populating a Version in the Visual Rules Team Server The following example illustrates how to create a new version in the Visual Rules Team Server (version 5.x) and populate it with a project with the aid of the Maven Plugin visualrules-team-plugin: Bosch Software Innovations GmbH 14/29

Chapter 2. Using Maven Example 2.8. Example for the visualrules-team-plugin to create and populate a Version in Team Server <build> <plugins> <plugin> <groupid>de.visualrules.maven</groupid> <artifactid>visualrules-team-plugin</artifactid> <version>${vrversion}</version> <executions> <execution> <configuration> <url>http://localhost:8080/teamserver</url> <username>admin</username> <password>admin</password> <repository>rulerepository</repository> <projects>movie Ticket Pricing</projects> <version>head</version> <newversion>version 1.0.x</newVersion> </configuration> <goals> <goal>version</goal> </goals> </execution> </executions> </plugin> </plugins> </build> Table 2.9. Parameters for the visualrules-team-plugin Parameter Description Required Type url The URL of the Team Server Backend (e.g. http:// some.host.com:8080/teamserver). URL username The username used for login password The password used for login repository The repository name newversion Name of the version to be newly created version Specification of a given version from which the projects are to be copied (standard: the latest version) projects Specification of one or more projects, which are assigned to the newly generated version. Multiple projects can be separated by. licensefile Path of the license file. If not specified, the directory <user.home>/.visualrules5 will be scanned for a license file. 2.15. Deploying to Visual Rules Execution Server The visualrules-deploy-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. Bosch Software Innovations GmbH 15/29

Chapter 2. Using Maven Example 2.9. Example for the visualrules-deploy-plugin <build> <plugins> <plugin> <groupid>de.visualrules.maven</groupid> <artifactid>visualrules-deploy-plugin</artifactid> <version>${vrversion}</version> <configuration> <url>http://localhost:8080/executionserver/admin/upload</url> <user>admin</user> <password>admin</password> <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> Table 2.10. Parameters for the visualrules-deploy-plugin Parameter Description Required Type url The URL of the Visual Rules Execution Server. user The name of the user on the server. password The password of the user on the server. timeout The connection timeout in milliseconds. This must be a positive value. Integer licensefile The path to a valid license file. This is required if the license file is not in the default location. Bosch Software Innovations GmbH 16/29

Chapter 3. Using the Ant Tasks 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 VRDoc for the generation of rule project documentation VRCheckout for checking out rule projects from a Visual Rules Team Server VRCheckin for the checking in files into the Visual Rules Team Server VRVersion for the generation and population of a version 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:\VR5-builder\examples\Movie Ticket Pricing Ant> 2. The project contains the files build.xml and builddoc.xml. These are Ant build scripts that illustrate the use of the Ant tasks. Run Ant to execute the build script build.xml. The Ant build script will generate the rule model documentation (VRDoc), then generate the rule code (VRGenerate), compile it and finally execute rule tests and a test suite (VRTest). The output will look like this: C:\VR5-builder\examples\Movie Ticket Pricing Ant>ant Buildfile: build.xml generatedocumentation: [java] Buildfile: builddoc.xml [java] [java] generatedocumentation: [java] [VRDoc] Generated report at D:\VR5-builder\examples\Movie Ticket Pricing Ant\documentation [java] BUILD SUCCESSFUL [java] [java] BUILD SUCCESSFUL [java] Total time: 4 seconds generaterulecode: [VRGenerate] Generated 26 Java source files to C:\VR5-builder\examples\Movie Ticket Pricing Ant\src-ant [VRGenerate] Generated wsdl to C:\VR5-builder\examples\Movie Ticket Pricing Ant\src-ant \META-INF\visualrules\webservice [VRGenerate] Generated MANIFEST.MF to C:\VR5-builder\examples\Movie Ticket Pricing Ant\srcant\META-INF compile: [javac] Compiling 25 source files to C:\VR5-builder\examples\Movie Ticket Pricing Ant \bin-ant [javac] te: Some input files use unchecked or unsafe operations. Bosch Software Innovations GmbH 17/29

Chapter 3. Using the Ant Tasks [javac] te: Recompile with -Xlint:unchecked for details. executetests: [VRTest] Test 'BonusPoints Test' executed in 50ms (7/7 test cases processed, 7.14ms per case). [VRTest] Test 'Pricing Test' executed in 50ms (8/8 test cases processed, 6.25ms per case). executetestsuite: [VRTest] Test 'BonusPoints Test' executed in 30ms (7/7 test cases processed, 4.29ms per case). [VRTest] Test 'Pricing Test' executed in 20ms (8/8 test cases processed, 2.5ms per case). [VRTest] Test suite 'All Tests' processed. all: BUILD SUCCESSFUL Total time: 12 seconds C:\VR5-builder\examples\Movie Ticket Pricing Ant> 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. If you run the deployartifact target, the output will look like this: C:\VR5-builder\examples\Movie Ticket Pricing Ant>ant deployartifact Buildfile: build.xml generaterulecode: [VRGenerate] Generated 26 Java source files to C:\VR5-builder\examples\Movie Ticket Pricing Ant\src-ant [VRGenerate] Generated wsdl to C:\VR5-builder\examples\Movie Ticket Pricing Ant\src-ant \META-INF\visualrules\webservice [VRGenerate] Generated MANIFEST.MF to C:\VR5-builder\examples\Movie Ticket Pricing Ant\srcant\META-INF compile: [javac] Compiling 25 source files to C:\VR5-builder\examples\Movie Ticket Pricing Ant \bin-ant [javac] te: Some input files use unchecked or unsafe operations. [javac] te: Recompile with -Xlint:unchecked for details. createartifact: [jar] Building jar: C:\VR5-builder\examples\Movie Ticket Pricing Ant \movieticketpricing-1.0.jar deployartifact: [VRDeploy] Successfully deployed C:\VR5-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 C:\VR5-builder\examples\Movie Ticket Pricing Ant> 3.3. Setting up the Ant Tasks 3.3.1. Defining the Ant Tasks with <taskdef> 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. Bosch Software Innovations GmbH 18/29

Chapter 3. Using the Ant 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:\vr5-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="vrversion" classname="de.visualrules.ant.team.internal.vrversion" classpathref="cp" /> <taskdef name="vrarchivedeploy" classname="de.visualrules.ant.deploy.internal.vrarchivedeploy" classpathref="cp" /> The VRDoc task cannot be used this way, because it only works within Eclipse. See the following section. 3.3.2. Running Ant Scripts in Eclipse The VRDoc task only works within a running Eclipse which has the Visual Rules Modeler plugins installed. The Builder distribution provides such an Eclipse within the eclipse folder. Eclipse provides the ability to execute Ant scripts with the Eclipse AntRunner. You can execute the Eclipse AntRunner from the command line like this: C:\>java -jar "C:\Progam s\visual Rules\eclipse\plugins \org.eclipse.equinox.launcher_1.0.201.r35x_v20090715.jar" -application org.eclipse.ant.core.antrunner -buildfile "Movie Ticket Pricing Ant\build.xml" generatedocumentation The -buildfile option specifies the Ant build script to use, and generatedocumentation denotes the Ant target in the example above. If you want to start the Eclipse AntRunner from a regular Ant build script, you can use the java task to do this (the "Movie Ticket Pricing Ant" example does this): <property name="builder.home" value="c:\vr5-builder" /> <java fork="true" classname="org.eclipse.core.launcher.main"> <classpath> <fileset dir="${builder.home}"> <include name="/eclipse/plugins/org.eclipse.equinox.launcher_*.jar"/> </fileset> </classpath> <arg value="-application"/> <arg value="org.eclipse.ant.core.antrunner"/> <arg value="-buildfile"/> <arg value="vr-build.xml"/> </java> You can run all Visual Rules Ant tasks with AntRunner, but it is needed and recommended only for the VRDoc task. Bosch Software Innovations GmbH 19/29

Chapter 3. Using the Ant Tasks 3.4. Generating Java Rule Code with VRGenerate The VRGenerate task is used for the generation of Java rule code. The task can be used as follows: <VRGenerate model="${model}" targetdir="${src-dir}" > <!-- Folders and JARs containing additional rule model files (e.g. referenced via Reuse Packages) --> <modelpath /> </VRGenerate> Bosch Software Innovations GmbH 20/29

Chapter 3. Using the Ant Tasks Table 3.1. Parameters for the VRGenerate Ant task Attribute Description Required Ant Type model Path to the rule model file file targetdir Path to the target directory directory modelpath A nested path denoting folders and jars that contain additional rule model files (e.g. referenced via Reuse Packages) path modelfolders Please note that this attribute is deprecated. Use modelpath instead. A nested directory set (dirset) denoting the folder(s) that contain additional rule model files (e.g. referenced via Reuse Packages). dirset validatemodel Whether or not the model should validated prior to code generation true) failonvalidationerrors Please note that this attribute is deprecated and has no effect anymore. It was used to trigger a build failure in the case of a validation error. This is now the default behavior but may be deactivated by setting validatemodel to false. true) enablestatistic- sandlistener- Code Whether or not to enable the generation of the code necessary to support collection of execution statistics and custom listeners true) 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. false) generatemanifest 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. false) 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. false) 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. te that the encoding on the rulemodel will always be used if it is specified there. license 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. 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 Bosch Software Innovations GmbH 21/29

Chapter 3. Using the Ant Tasks 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. <javac srcdir="${basedir}/src-ant" destdir="${basedir}/bin-ant"> <classpath> <fileset dir="${vr5.home}/plugins"> <include name="de.visualrules.runtime*/visualrules-runtime.jar" /> <include name="de.visualrules.commons.collections*/lib/*.jar" /> <include name="de.visualrules.commons.lang*/lib/*.jar" /> <include name="de.visualrules.commons.logging*/lib/*.jar" /> <include name="de.visualrules.java.mail*/lib/*.jar" /> </fileset> </classpath> </javac> 3.6. Executing Rule Tests with VRTest 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="${basedir}/summaryreports" generatehtmlreport="true" executionresultdir="${basedir}/executionresults" failonerror="false" activeconfigurationname="default" verbose="true" requeststatisticslevel="medium" sessionstatisticslevel="medium"> <!-- Tests to execute --> <tests> <fileset dir="${basedir}"> <include name="**/*.vrtest"/> </fileset> </tests> <!-- Folders containing the rule model files --> <modelpath> <pathelement location="${basedir}" /> </modelpath> <!-- Classpath containing the compiled rule model code and any additional classes needed for execution the tests --> <classpath> <pathelement location="${basedir}/bin-ant" /> </classpath> </VRTest> Bosch Software Innovations GmbH 22/29

Chapter 3. Using the Ant Tasks 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. Path modelpath A nested path denoting folders and jars that contain additional rule model files (e.g. referenced via reuse packages) 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). Path summaryreportdir 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). 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. false) Boolean executionresultdir 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). failonerror Set to true the VRTest task will raise an exception if at least one test execution failed. All tests will be executed. true) Boolean activeconfigurationname 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 (available since version 5.2, this attribute is known as configuration in former versions; this is still supported). verbose If set to true status messages about test execution will be reported on standard output. false) Boolean requeststatisticslevel sessionstatisticslevel Overwrites the statistics level for every test case. Enumeration (possilbe values are none, medium, high) Overwrites the statistics level for entire tests. Enumeration (possilbe values are none, medium, high) license 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. 3.7. Generating the Rule Model Documentation with VRDoc The VRDoc task generates the documentation for a rule model. It is possible to generate the documentation in either HTML or PDF format. In the example provided the documentation is generated in HTML format, which is the default setting. Bosch Software Innovations GmbH 23/29

Chapter 3. Using the Ant Tasks <VRDoc model="${model}" targetdir="${doc-dir}" /> Since the VRDoc task creates images for the rule documentation, a running graphical environment is needed on the system it is executed on. Additionally, the VRDoc task can only be used on platforms that are supported by the Standard Widget Toolkit (SWT). For more information please visit http://www.eclipse.org/swt Table 3.3. Parameters for the VRDoc Ant task Attribute Description Required Ant Type model Path to the rule model file targetdir Path to the target directory Directory modelpath A nested path denoting folders and jars that contain additional rule model files (e.g. referenced via Reuse Packages) path reporttype The type of the report. Either html, pdf or word. html) Enumeration (possible values: html, pdf, word) includeruleimages Whether or not the documentation should contain rule images true) includedescriptionsinruleimages Whether or not descriptions should be included in rule images true) includecontentsinruleimages Whether or not the rule element contents should be included in rule images true) includecallassignmentdetailsinruleimages Whether or not data values should be included in rule images true) includetesin- RuleImages Whether or not notes should be included in rule images false) includestatisticsinruleimages Whether or not statistics information should be included in rule images false) includeexcep- tionhandlingin- RuleImages Whether or not exception handling should be included in rule images true) includeruleelementdetails Whether or not the documentation should contain details of rule elements true) license 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. 3.8. Checking out Rule Projects from a Visual Rules Team Server with VRCheckout The following example illustrates how to checkout a rule project from a Visual Rules Team Server 4.x.x. Bosch Software Innovations GmbH 24/29

Chapter 3. Using the Ant Tasks <VRCheckout teamserverhost="localhost" teamserverport="1530" username="vruser" password="secret" repository="repo1" project="myproject" targetdirectory="${basedir}" /> If you are working with a Team Server 5.x.x do the following to checkout a rule project: <VRCheckout url="http://localhost:8080/teamserver-5.x.x" username="vruser" password="secret" repository="repo1" project="myproject" targetdirectory="${basedir}" /> Table 3.4. Parameters for the VRCheckout Ant task Attribute Description Required Ant Type teamserver- Host The URL of the Team Server host. Only for 4.x.x Team Servers., if no url Attribute given teamserverport The port of the Team Server host. Only for 4.x.x Team Servers. 1530) Integer username The username to be used for login password The password to be used for login repository The name of the repository to checkout from project The name of the project to checkout targetdirectory The directory on the local file system where the project should be placed Directory createsubdirectory 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. true) version The version of the project to checkout. If not specified, the latest version in the repository will be fetched. license 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. url The URL of the Team Server Backend. Only for 5.x.x Team Servers., if no team- ServerHost attribute given URL 3.9. Checking in s 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 5.x (separately available) with the aid of the task VRCheckin: <VRCheckin url="http://localhost:8080/teamserver-5.x.x" username="vruser" password="secret" repository="repo1" destination="testdest"> <fileset dir="${basedir}"> <include name="**/*" /> <exclude name="bin/*"/> Bosch Software Innovations GmbH 25/29

Chapter 3. Using the Ant Tasks </fileset> </VRCheckin> Table 3.5. Parameters for the VRCheckin task Attribute Description Required Ant Type url The URL of the Team Server Backend (e.g. http:// some.host.com:8080/teamserver). For Team Server 5.x.x. URL username The username used for login password The password used for login repository The name of the repository to check in to destination The name of the folder, in which the files and directories are to be checked in (will be created, if necessary) fileset s and directories to be checked in set version The target version, in which the destination will be placed.. If not specified, the latest version in the repository will be fetched. encoding The encoding of the files to be checked in to the Team Server. (standard: the Java Encoding) license Path of the license file. If not specified, the directory <user.home>/.visualrules5 will be scanned for a license file. commitcomment Comment for the check in. (standard: without comment) 3.10. Creating and Populating a Version in the Visual Rules Team Server The following example illustrates how to create a new version in the Visual Rules Team Server (version 5.x) and populate it with a project with the aid of the task VRVersion: <VRVersion url="http://localhost:8080/teamserver-5.x.x" username="vruser" password="secret" repository="repo1" projects="movie Ticket Pricing Ant" newversion="release"/> Bosch Software Innovations GmbH 26/29

Chapter 3. Using the Ant Tasks Table 3.6. Parameters for the VRVersion task Attribut Beschreibung Erforderlich Ant Typ url The URL of the Team Server Backend (e.g. http:// some.host.com:8080/teamserver). URL username The username used for login password The password used for login repository The repository name newversion Name of the version to be newly created version Specification of a given version from which the projects are to be copied (standard: the latest version) projects Specification of one or more projects, which are assigned to the newly generated version. Multiple projects can be separated by. license Path of the license file. If not specified, the directory <user.home>/.visualrules5 will be scanned for a license file. 3.11. Deploying Rule Artifacts to Visual Rules Execution Server with VRDeploy In order to deploy a rule artifact to the Execution Server 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. <VRDeploy username="admin" password="admin" filetodeploy="artifact-1.0.jar" uploadurl="http://localhost:8080/executionserver/admin/upload" groupid="yourgroupid" artifactid="yourartifactid" version="1.0" /> Bosch Software Innovations GmbH 27/29

Chapter 3. Using the Ant Tasks Table 3.7. Parameters for the VRDeploy Ant task Attribute Description Required Ant Type username The user name to be used for the deployment password The password to be used for the deployment uploadurl The upload URL of the Visual Rules Execution Server to where the artifact is being deployed filetodeploy The absolute or relative location of the artifact that is being deployed groupid The group id of the artifact that is being deployed artifactid The artifact id of the artifact that is being depldoyed version The version of the artifact that is being deployed license 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. timeout Timeout in milliseconds (ms) for the deployment connection. If not specified a default of 5000ms (5 seconds) is used Integer 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. Table 3.8. 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 commons-collections 3.2.1 commons-lang-2.5.jar commons-lang commons-lang 2.5 commons-collections-3.2.1.jar 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: Bosch Software Innovations GmbH 28/29

Chapter 3. Using the Ant Tasks Table 3.9. 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.12. Deploying Visual Rules Archive (VRA) s to Visual Rules Execution Server with VRArchiveDeploy 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" archive="archive.vra"/> Table 3.10. Parameters for the VRArchiveDeploy Ant task Attribute Description Required Ant Type username The user name to be used for the deployment password The password to be used for the deployment uploadurl The upload URL of the Visual Rules Execution Server to where the artifact is being deployed archive The absolute or relative location of the Visual Rules Archive (VRA) file that is being deployed license 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. timeout Timeout in milliseconds (ms) for the deployment connection. If not specified a default of 5000ms (5 seconds) is used Integer Bosch Software Innovations GmbH 29/29