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

Transcription

1 Visual Rules Suite - Builder Builder User Guide Version Bosch Software Innovations Americas: Bosch Software Innovations Corp. 161 N. Clark Street Suite 3500 Chicago, Illinois 60601/USA Tel info@bosch-si.com Asia: Bosch Software Innovations c/o Robert Bosch (SEA) Pte Ltd 11 Bishan Street 21 Singapore Tel info-sg@bosch-si.com Europe: Bosch Software Innovations GmbH Ziegelei Immenstaad/GERMANY Tel info-de@bosch-si.com

2 Builder User Guide: Version Visual Rules Builder User Guide, Version Copyright Bosch Software Innovations GmbH Bosch Software Innovations GmbH, 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 Builder User Guide Table of Contents 1. Introduction Configuring the License Contents of the Distribution 1 2. Using Maven Overview Installing Visual Rules Maven Plugins Configuring the License Building the Provided Maven Example Project Deploying Rule Artifacts for Usage in Visual Rules Modeler Project Structure Validating Rule Models Testing Rule Models Generating Documentation of Test Results Generating Java Source Code Generating Web Service Interface Generating Manifest Checking in s and Directories to a Visual Rules Team Server Creating and Populating a Branch in the Visual Rules Team Server Deploying to Visual Rules Execution Server Generate Visual Rules Archive (VRA) files Using the Ant Tasks Overview Running the Example Ant Build Script Setting up the Ant Tasks Generating Java Rule Code Compiling Java Rule Code Executing Rule Tests Checking out Rule Projects from a Visual Rules Team Server Checking in s and Directories to a Visual Rules Team Server Creating and Populating a branch in the Visual Rules Team Server Deploying Rule Artifacts to Visual Rules Execution Server Deploying Visual Rules Archive (VRA) s to Visual Rules Execution Server 28 Bosch Software Innovations iii/29

4 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 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 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 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 Contents of the Distribution The Builder components are distributed as a ZIP file with the following contents: Bosch Software Innovations 1/29

5 Chapter 1. Introduction Table 1.1. Contents of the distribution Folder Contents Usage doc Manuals (German and English) examples Examples Section 3.2, Running the 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 visualrules-runtime Maven-plugins, their dependencies, and installation script Visual Rules Runtime libraries as listed in Table 3.7, Visual Rules Runtime Dependencies and Table 3.8, Visual Rules DatabaseIntegrator Runtime Dependencies Chapter 2, Using Maven Section 2.2, Installing Visual Rules Maven Plugins Section 3.5, Compiling Java Rule Code Section 3.6, Executing Rule Tests Section 3.10, Deploying Rule Artifacts to Visual Rules Execution Server Bosch Software Innovations 2/29

6 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-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 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 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 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. Bosch Software Innovations 3/29

7 Chapter 2. Using Maven set REPOSITORY_ID=releaseRepositoryID set REPOSITORY_LAYOUT=default set URL= set UNIQUE_VERSION=false set GOAL=deploy:deploy-file 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 Configuring the License 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 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. 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) s 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 Bosch Software Innovations 4/29

8 Chapter 2. Using Maven starts again installing the artifact into the local Maven repository and deploying it to the Visual Rules Execution Server 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 <project > <distributionmanagement> <snapshotrepository> <id>snapshotrepositoryid</id> <uniqueversion>false</uniqueversion> <url>dav: </snapshotrepository> <repository> <id>releaserepositoryid</id> <url>dav: </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. Bosch Software Innovations 5/29

9 Chapter 2. Using Maven 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. (default: false) boolean 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 (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. Bosch Software Innovations 6/29

10 Chapter 2. Using Maven 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. <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> Example 2.2. Example for the visualrules-testing-maven-plugin Bosch Software Innovations 7/29

11 Chapter 2. Using Maven Table 2.3. Parameters for the visualrules-testing-maven-plugin Parameter Description Required Type verbose If true information about each executed test is printed to the console. (default: false) boolean 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. writetestreport Archive If true a archive will be created containing the test results and statistics which can be viewed in the Visual Rules Modeler. (default: false) boolean writexmlreport If true the test results are written in a simple XML format. (default: true) boolean active Configuration Name Name of the configuration for the rule execution that will be used by all tests. 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. 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 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. It is intended that the report generation should happen in the site phase. Bosch Software Innovations 8/29

12 Chapter 2. Using Maven <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 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 Generating Java Source Code The visualrules-javagenerator-maven-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 9/29

13 Chapter 2. Using Maven <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 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. (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. 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 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. Bosch Software Innovations 10/29

14 Chapter 2. Using Maven <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 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 Generating Manifest 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. Bosch Software Innovations 11/29

15 Chapter 2. Using Maven <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> <usedefaultmanifest>true</usedefaultmanifest> </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 Parameter Description Required Type includesweb Service Set this to true, if used in conjunction with the WSDL Generator Plugin. 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. licensefile The path to a valid license file. This is required if the license file is not in the default location. Bosch Software Innovations 12/29

16 Chapter 2. Using Maven 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 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> <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> Example 2.7. Example for visualrules-team-maven-plugin to checkin files and directories Bosch Software Innovations 13/29

17 Chapter 2. Using Maven Table 2.8. Parameters for the visualrules-team-maven-plugin to checkin files and directories Parameter Description Required Type url The URL of the Team Server Backend (e.g. some.host.com:8080/teamserver). For Team Server 6.x.x. URL username The username used for login password The password used for login tenant The tenant name 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 branch The target branch, in which the destination will be placed.. If not specified, the latest branch in the repository will be fetched. encoding The encoding of the files to be checked in to the Team Server. (Standard: The Java Encoding) commit Comment Comment for the check in. (Standard: without comment) licensefile Path of the license file. If not specified, the directory <user.home>/.visualrules6 will be scanned for a license file 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: Bosch Software Innovations 14/29

18 Chapter 2. Using Maven <build> <plugins> <plugin> <groupid>de.visualrules.builder</groupid> <artifactid>visualrules-team-maven-plugin</artifactid> <version>${vrbuilderversion}</version> <executions> <execution> <configuration> <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 Parameter Description Required Type url The URL of the Team Server Backend (e.g. some.host.com:8080/teamserver). URL username The username used for login password The password used for login tenant The tenant name used for login repository The repository name newbranch Name of the branch to be newly created branch Specification of a given branch from which the projects are to be copied (standard: the latest branch) projects Specification of one or more projects, which are assigned to the newly generated branch. Multiple projects can be separated by. licensefile Path of the license file. If not specified, the directory <user.home>/.visualrules6 will be scanned for a license file. Bosch Software Innovations 15/29

19 Chapter 2. Using Maven 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> <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 Parameters for the visualrules-deploy-maven-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. tenant The tenant name used for login 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. active Sets the rule service active or inactive Boolean validfrom Sets the validfrom setting of a rule service. The value is specified by: yyyy-mm-dd HH:mm:ss validto Sets the validto setting of a rule service. The value is specified by: yyyy-mm-dd HH:mm:ss For more information on the settings active, validfrom, validto refer to the Execution Server User Guide. Bosch Software Innovations 16/29

20 Chapter 2. Using Maven 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 Example for the visualrules-archive-maven-plugin Table Parameters for the visualrules-archive-maven-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. Bosch Software Innovations 17/29

21 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 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 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: Bosch Software Innovations 18/29

22 Chapter 3. Using the Ant Tasks 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\srcant\META-INF compile: [javac] Compiling 25 source files to C:\VR-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. 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 C:\VR-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: Bosch Software Innovations 19/29

23 Chapter 3. Using the Ant Tasks 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\srcant\META-INF compile: [javac] Compiling 25 source files to C:\VR-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:\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 localhost:8080/executionserver-4.6.1/admin/upload BUILD SUCCESSFUL Total time: 6 seconds C:\VR-builder\examples\Movie Ticket Pricing Ant> 3.3. Setting up the Ant Tasks In order to make Ant recognize the Builder Ant tasks in your build script, you have to define them 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" /> <path id="cp"> <fileset dir="${builder.home}/lib/" includes="*.jar"/> <fileset dir="${builder.home}/runtime/" includes="*.jar"/> </path> <taskdef name="vrgenerate" classname="de.visualrules.ant.java.codegeneration.internal.vrgenerate" classpathref="cp"/> <taskdef name="vrtest" classname="de.visualrules.ant.java.execution.internal.vrtest" classpathref="cp"/> <taskdef name="vrcheckout" classname="de.visualrules.ant.team.internal.vrcheckout" classpathref="cp"/> <taskdef name="vrdeploy" classname="de.visualrules.ant.deploy.internal.vrdeploy" classpathref="cp"/> <taskdef name="vrcheckin" classname="de.visualrules.ant.team.internal.vrcheckin" classpathref="cp" /> <taskdef name="vrbranch" classname="de.visualrules.ant.team.internal.vrbranch" classpathref="cp" /> <taskdef name="vrarchivedeploy" classname="de.visualrules.ant.deploy.internal.vrarchivedeploy" classpathref="cp" /> 3.4. Generating Java Rule Code The VRGenerate task is used for the generation of Java rule code. The task can be used as follows: Bosch Software Innovations 20/29

24 Chapter 3. Using the Ant Tasks <VRGenerate model="${model}" targetdir="${src-dir}" > <!-- Folders and JARs containing additional rule model files (e.g. referenced via Reuse Packages) --> <modelpath /> </VRGenerate> 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 validatemodel Whether or not the model should validated prior to code generation. (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. (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. (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.. (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. (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. 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 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. Bosch Software Innovations 21/29

25 Chapter 3. Using the Ant Tasks <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 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 22/29

26 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 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). 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. (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). failonerror Set to true the VRTest task will raise an exception if at least one test execution failed. All tests will be executed. (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. verbose If set to true status messages about test execution will be reported on standard output. (default: false) Boolean request StatisticsLevel session StatisticsLevel 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 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=" username="vruser" password="secret" tenant="default" repository="repo1" project="myproject" targetdirectory="${basedir}" /> Bosch Software Innovations 23/29

27 Chapter 3. Using the Ant Tasks Table 3.3. Parameters for the VRCheckout Ant task Attribute Description Required Ant Type username The username to be used for login. password The password to be used for login. tenant The tenant name 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 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. (default: true) boolean branch The branch of the project to checkout.. If not specified, the latest branch 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 (e.g. some.host.com:8080/teamserver) URL 3.8. 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 6.x.x (separately available) with the aid of the task VRCheckin: <VRCheckin url=" username="vruser" password="secret" tenant="default" repository="repo1" destination="testdest"> <fileset dir="${basedir}"> <include name="**/*" /> <exclude name="bin/*"/> </fileset> </VRCheckin> Bosch Software Innovations 24/29

28 Chapter 3. Using the Ant Tasks Table 3.4. Parameters for the VRCheckin task Attribute Description Required Ant Type url The URL of the Team Server Backend (e.g. some.host.com:8080/teamserver) URL username The username used for login. password The password used for login. tenant The tenant name 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 branch The target branch, in which the destination will be placed.. If not specified, the latest branch 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>/.visualrules6 will be scanned for a license file. commit Comment Comment for the check in. (standard: without comment) 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: <VRBranch url=" username="vruser" password="secret" tenant="default" repository="repo1" projects="movie Ticket Pricing Ant" newbranch="release"/> Bosch Software Innovations 25/29

29 Chapter 3. Using the Ant Tasks Table 3.5. Parameters for the VRBranch task Attribute Description Required Ant Type url The URL of the Team Server Backend (e.g. some.host.com:8080/teamserver). URL username The username used for login. password The password used for login. tenant The tenant name used for login. repository The repository name. newbranch Name of the branch to be newly created. branch Specification of a given branch from which the projects are to be copied. (standard: the latest branch) projects Specification of one or more projects, which are assigned to the newly generated branch. Multiple projects can be separated by. license Path of the license file. If not specified, the directory <user.home>/.visualrules6 will be scanned for a license file 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=" groupid="yourgroupid" artifactid="yourartifactid" version="1.0" /> Bosch Software Innovations 26/29