PolymitaDemo

This is a shipping demo using BRMS, BPM, Polymita, and JBoss. You can create shipments, add containers to those shipments and add items to each of those containers. Items can have different weights, HazMat classes, and descriptions. If a hazardous item is added to the container, it kicks off a human task in jBPM, in which the item will need approval. Based on this information, the items are priced using BRMS, each container is assigned a price based on the items, and the total shipment gets a price based on all of the containers. This information is then all passed back to Java and reflected in the Bill of Lading table, and can be exported to PDF if desired.

This README will tell you how to install this demo. It will also go through a few sample usages of the program.

Here is a video explaining most of the installation process.

PolymitaDemo Install from Robert Wagner on Vimeo.

###Installation Step 1: Clone The Repo

Step 2: Download Source .zip Files

Step 3: Install Maven

Step 4: Transfer Maven settings.xml and Build Project

Step 5: Install and Run PostgreSQL

Step 6: Setup Server and Define Runtimes

Step 7: Import the Project

Step 8: Upload Resources to Guvnor

Step 9: Run the PolymitaDemo app

Step 10: Configure Polymita

Notes

###Usage App

BPM

Step 1: Clone The Repo

Clone this repo into your ~/Downloads folder.

cd ~/Downloads
git clone https://github.com/rwwagner90/PolymitaDemo.git

Step 2: Download Source .zip Files

Download the following from the JBoss Customer Portal at access.redhat.com

EAP6 (jboss-eap-6.1.0.zip)

BRMS deployable (brms-p-5.3.1.GA-deployable-ee6.zip)

Copy these files to the installs directory in the root of this repo and ensure that they are executable by running:

chmod +x ~/Downloads/PolymitaDemo/installs/jboss-eap-6.1.0.zip
chmod +x ~/Downloads/PolymitaDemo/installs/brms-p-5.3.1.GA-deployable-ee6.zip

Step 3: Install Maven

Make sure you have Maven installed on your machine.

mvn --version

If you have it installed, you will see output similar to:

Apache Maven 3.0.3 (r1075438; 2011-02-28 12:31:09-0500)
Maven home: /usr/share/maven
Java version: 1.6.0_51, vendor: Apple Inc.
Java home: /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home
Default locale: en_US, platform encoding: MacRoman
OS name: "mac os x", version: "10.8.4", arch: "x86_64", family: "mac"

If you do not have it installed, you can find instructions on how to install it online. One specific source is here, but there are other tutorials you can find.

Step 4: Transfer Maven settings.xml and Build Project

Copy the settings.xml file in the root of this repo to your ~/.m2 folder.

cp ~/Downloads/PolymitaDemo/settings.xml ~/.m2/

Then you are ready to build the project. Run the init.sh script in the root of your repository folder and it will build.

sh ~/Downloads/PolymitaDemo/init.sh

Step 5: Install and Run PostgreSQL

Go here and download the PostgreSQL that works with your system and follow the instructions to get it running.
Start the PostgreSQL service with the template1 database and create a polymita user for the polymita table.

In bash, start psql by running:

psql template1

Execute the following once you are running psql.

CREATE USER polymita WITH PASSWORD 'polymita';
DROP DATABASE IF EXISTS polymita;
CREATE DATABASE polymita;
ALTER DATABASE polymita OWNER TO polymita;

Now start the psql service. If you are on linux, use the following command:

sudo service postgresql start

If you are not on linux, look around the documentation of the PostgreSQL instance you installed for how to start it.

Step 6: Setup Server and Define Runtimes

Setup EAP 6 Server in JBoss Developer Studio

Select the Servers view. If it is currently not open, select Window → Show View → Other and search for the Servers view.
Right click the white space in the Servers view and choose New → Server.
Select JBoss Enterprise Application Platform 6.1.
Set the following values:

Server's host name: localhost
Server Name: JBoss EAP 6.1
For Server Runtime Environment click Add Then set the following:
Name: JBoss EAP 6.1 Runtime
Home Directory: ~/Downloads/PolymitaDemo/target/jboss-eap6.1
JRE: Choose 1.7.x, whichever version of Java 7 you prefer.
Configuration file: standalone.xml.
Note: If this runtime was automatically detected earlier and created, you may just use it instead of making a new one.

Click Finish.

Install SOA Tools

Select Help → Install New Software and add the SOA Tools update site https://devstudio.jboss.com/updates/5.0/central/soa-tooling/

Select Business Rules Tooling and SOA and Data Services Tooling (all sub-menu items will be selected) and proceed through installation and restart JBoss Developer Studio to complete the installation.

You will be told to restart JBoss Developer Studio for the changes to take effect, do this now.

Detect and add a BRMS 5.3.1 runtime environment

Select Window → Preferences.
Click the plus sign to expand JBoss Tools and then select JBoss Runtime Detection.
Select the Add button and navigate to the ~/Downloads/PolymitaDemo/target folder, then select OK.
The jboss-eap-6.1 runtime created earlier should have been found and selected. If so, select OK.
Select OK again to close the Preferences dialog window.

Detect and add jBPM BRMS 5.3.1 runtime environment

Select Window → Preferences.
Click the plus sign to expand jBPM and then select Installed jBPM Runtimes.
If not automatically listed in the view: Select the Add button, then the Create a new jBPM Runtime button and navigate to the ~/Downloads/PolymitaDemo/target/jboss-eap-6.1 folder, then name the runtime jBPM BRMS 5.3.1 runtime and select OK.
The jBPM BRMS 5.3.1 runtime should be selected. If so, select OK to close the Preferences dialog window. If not, click box to add check mark next to runtime and then select OK.
If asked to restart JBoss Developer Studio for the changes to take effect, restart.

Detect and add Drools 5.3.1 runtime environment

Select Window → Preferences.
Click the plus sign to expand Drools and then select Installed Drools Runtimes.
If not automatically listed in the view: Select the Add button, then the Create a new Drools 5 Runtime button and navigate to the ~/Downloads/PolymitaDemo/target/jboss-eap-6.1 folder, then name the runtime Drools 5.3.1.Final runtime and select OK.
Select the Drools 5.3.1.Final runtime.
In Drools in the left hand side menu select Drools Flow nodes, make sure all boxes are checked and select OK to close the Preferences dialog window.
You will be told to restart JBoss Developer Studio for the changes to take effect, do this now.

Step 7: Import the Project

Import the project into JBoss Developer Studio by clicking File → Import and choosing General → Existing Projects into Workspace. Then navigate to ~/Downloads/PolymitaDemo/PolymitaDemo as the source folder. (Note the double PolymitaDemo/PolymitaDemo)

Then we need to update the dependencies and such so everything will work.

Right click the project folder and do Maven → Update Project, followed by Run As → Maven Clean, and then Run As → Maven Install. This should download all the required dependencies.

Now that everything is updated, start the server so that Guvnor will be running for the next step. To do this, right click the project and choose Run As → Run on Server and choose the JBoss EAP 6.1 server and click finish.

Step 8: Upload Resources to Guvnor

Upload POJO Model

Select all the java files under org.railroad.shipping and then right click and choose Export → Java → JAR file.

All of the default options for saving the JAR will be fine, just save it somewhere you will remember.

Next, navigate to http://localhost:8080/jboss-brms and login with Username: admin and Password: admin. This is Guvnor that you are logging into, and it is where you will upload rules and flows.

After logging in, it will ask you to import sample data because it is a new repository. DO NOT do this!

Then click Knowledge Bases and then click Create New → New Package and call it org.railroad.shipping.

Still in Knowledge Bases, click Create New → Upload POJO. Name it whatever you would like and click next. Then find the JAR you just made and upload it.

Upload Rules and Flows

Add Guvnor to JBoss Developer Studio

Click Window → Open Perspective → Other → Guvnor Repository Exploring
Then click File → New → Other → Guvnor → Guvnor repository location
The default info is fine for Location, Port, and Repository, and for User Name put admin and also for Password put admin.
Click finish

Upload rules to Guvnor

In JBoss Developer Studio, navigate to src/main/rules.
Select all .drl files, right click and go to Guvnor → Add
Use your existing Guvnor, click next.
Expand your Guvnor and select packages/org.railroad.shipping as the package to upload to.
Click finish

Upload flows to Guvnor

In JBoss Developer Studio, navigate to src/main/resources.
Select all .bpmn2 files, right click and go to Guvnor → Add
Use your existing Guvnor, click next.
Expand your Guvnor and select packages/org.railroad.shipping as the package to upload to.
Click finish

Add the item form

In Guvnor, navigate to Knowledge Bases → org → railroad → shipping.
Under the Assets tab open the processes dropdown and open org.railroad.shipping.ItemFlow
In the ItemFlow window click the task called "Hazard Human Check"
Click on the green shirted man directly above the task and a form editing window pops up
In JBoss Developer Studio open up src/main/resources/humanHazardCheck.html
copy-paste the contents into the process form window in guvnor and click save.

PNG all flows

Log in to Guvnor at http://localhost:8080/jboss-brms with the Username: admin and Password: admin.
Click Knowledge Bases → org → railroad → shipping to navigate to the package.
Now click Assets → Processes and click Open next to each process. This will open each one in a tab at the top.
Now click each tab, and the flow will appear for that process.
While viewing each flow, click the PNG button at the bottom to generate images needed by BRMS. You do not need to save the generated PNG file, it will save the images in assets by itself.
After each PNG is generated, click File → Save Changes.

Build the package

In Guvnor, navigate to Knowledge Bases → org → railroad → shipping.
Then click Edit.
Click the Validate Configuration button, followed by the Build Package button and fix any errors that may arise.
Click File → Save Changes to ensure the package that was built is saved.

Step 9: Run the PolymitaDemo app

In JBoss Developer Studio, right click the project and choose Run As → Run on Server.
Then select the runtime you previously set up, and wait for everything to start up.
You should then be able to navigate to http://localhost:8080/PolymitaDemo and see the app!

Step 10: Configure Polymita

Create a user.

Run ~/Downloads/PolymitaDemo/target/jboss-eap6.1/bin/add-user.sh
Choose b for an Application User
Press enter to select ApplicationRealm
For username choose polymita
Choose any password you desire
For roles type user,admin
For the next step say yes
And for EJB say no

Go to http://localhost:8080/dashbuilder and login with polymita and the password you created.

Add a datasource

On the left side, after signing in, click Administration.
Then click External Connections
Next click New DataSource
Then choose the following:
Type: JNDI
Name: jbpm
JNDI Path: java:jboss/datasources/jbpmDS
Test Query: SELECT * FROM organizationalentity;

Add the new datasource as a data provider

On the left, select Data Providers
Click on the drop down and choose SQL Query
Name it Tasks
select the jbpm datasource
in the Query field type SELECT * FROM task
click Attempt Data Load and then Save

Create a Graph

Click on the center dropdown on the top bar and choose Page template
Click on the puzzle piece next to that drop down
Go to Dashboard → Key Performance Indicator and drag Instances by status into the page
Choose the Tasks Data provider

Notes

When you make changes, you must click the red stop button to stop the server, then do Run As → Run on Server again to redeploy.
You must PNG a flow after any changes for the Guvnor to realize the changes.
You must build your package again after all changes to make the changes go through.
You must have psql running whenever running the application, so you can access the databases.