This episode of tips and tricks will help you to understand the best way to initiate your process instances for your needs.

Planning your projects might include process projects, but have you thought about the various ways that you can initiate your process?

Maybe you have JBoss BPM Suite running locally in your architecture, maybe you have it running in the Cloud, but wherever it is you will still need to make an informed choice about how to initiate a process.

We will cover here three essential ways you can best start a JBoss BPM process:

1. UI dashboard
2. RestAPI

Build & Deploy button top right.

3. client application (API)

BPM Suite UI

In the interest of completeness we have to mention the ability to start a process instance exists in the form of a button within JBoss BPM Suite dashboard tooling.

When logged into JBoss BPM Suite and you have finished project development, your BPM project can then be built and deployed as follows.

AUTHORING -> PROJECT AUTHORING -> TOOLS -> PROJECT EDITOR -> BUILD&DEPLOY (button)

The next step is to start a process instance in the process management perspective in one of two ways.

1. PROCESS MANAGEMENT -> PROCESS DEFINITIONS -> start-icon

 2. PROCESS MANAGEMENT -> PROCESS DEFINITIONS -> magnifying-glass-icon -> in DETAILS panel -> NEW INSTANCE (button)

Process definitions has start icon in right corner.

Both of these methods will result in a process instance being started, popping up a start form if data is to be submitted to the BPM process.

RestAPI

Assuming you are going to be calling for a start of your BPM process after deployment from various possible locations we wanted to show you how these might be easily integrated. 

Details view of process definition has 'New Instance' button.

It does not matter if you are starting a process from a web application, a mobile application or creating backend services for your enterprise to use as a starting point for processes. The exposed RestAPI provides the perfect way to trigger your BPM process and can be show in the following code example.

This example is a very simple Rest client that, for clarity, will be embedding the various variables one might pass to such a client directly into the example code. There are no variables passed to the process being started, for that we will provide a more complete example in the section covering a client application.

It sends a start process command and expects no feedback from the Customer Evaluation BPM process being called, as it is a Straight Through Process (STP).

public class RestClientSimple {
    private static final String BASE_URL = "http://localhost:8080/business-central/rest/";
    private static final String AUTH_URL = "http://localhost:8080/business-central/org.kie.workbench.KIEWebapp/j_security_check";
    private static final String DEPLOYMENT_ID = "customer:evaluation:1.0";
    private static final String PROCESS_DEF_ID = "customer.evaluation";
    
    private static String username = "erics";
    private static String password = "bpmsuite";
    private static AuthenticationType type = AuthenticationType.FORM_BASED;

    public static void main(String[] args) throws Exception {

     System.out.println("Starting process instance: " + DEPLOYMENT_ID);
        System.out.println();
        
     // start a process instance with no variables.
        startProcess();

        System.out.println();
     System.out.println("Completed process instance: " + DEPLOYMENT_ID);
    }

    /**
     * Start a process using the rest api start call, no map variables passed.
     * 
     * @throws Exception
     */
   public static void startProcess() throws Exception {
        String newInstanceUrl = BASE_URL + "runtime/" + DEPLOYMENT_ID + "/process/" + PROCESS_DEF_ID + "/start";
        String dataFromService = getDataFromService(newInstanceUrl, "POST");
        System.out.println("newInstanceUrl:["+newInstanceUrl+"]");
        System.out.println("--------");
        System.out.println(dataFromService);
        System.out.println("--------");
    }

<a href="https://github.com/eschabell/brms-fuse-integration-demo/blob/master/projects/brms-fuse-integration/simpleRoute/src/main/java/com/jboss/examples/RestClientSimple.java" target="_blank"><...SNIPPED MORE CODE...></a>
}

The basics here are the setup of the business central URL to point to the start RestAPI call. In the main method one finds a method call to startProcess() which builds the RestAPI URL and captures the data reply sent from JBoss BPM Suite.

To see the details of how that is accomplished, please refer to the class in its entirety within the JBoss BPM Suite and JBoss Fuse Integration Demo project.

Intermezzo on testing

An easy way to test your process once it has been built and deployed is to use curl to push a request to the process via the RestAPI. Such a request looks like the following, first in generic form and then a real run through the same Customer Evaluation project as used in the previous example.

The generic RestAPI call and proper authentication request is done in curl as follows:

$ curl -X POST -H 'Accept: application/json' -uerics 'http://localhost:8080/business-central/rest/runtime/customer:evaluation:1.1/process/customer.evaluation/start?map_par1=var1&map_par2=var2'

For the Customer Evaluation process a full cycle of using curl to call the start process, authenticating our user and receiving a response from JBoss BPM Suite should provide the following output.

$ curl -X POST -H 'Accept: application/json' -uerics 'http://localhost:8080/business-central/rest/runtime/customer:evaluation:1.1/process/customer.evaluation/start?map_employee=erics'

Enter host password for user 'erics':  bpmsuite1!

{"status":"SUCCESS","url":"http://localhost:8080/business-central/rest/runtime/customer:evaluation:1.1/process/customer.evaluation/start?map_employee=erics","index":null,"commandName":null,"processId":"customer.evaluation","id":3,"state":2,"eventTypes":[]}

Results of our testing with curl.

We see the process instances complete in the process instance perspectives as shown.

Client application

The third and final way to start your JBoss BPM Suite process instances is more in line with injecting a bunch of pre-defined submissions to populate both the reporting history and could be based on historical data.

The example shown here is available in most demo projects we provide but is taken from the Mortgage Demo project.

This demo client is using static lines of data to be injected into the process one at a time. With a few minor adjustments one could pull in historical data from an existing data source and inject as many processes as desired in this format. It also is a nice way to stress test your process projects.

We will skip the setup of the session and process details as these have been shown above, but provide instead a link to the entire demo client class and leave these details for the reader to pursue.

Here we will just focus on how the individual start process calls will look.

public static void populateSamples(String userId, String password, String applicationContext, String deploymentId) {

   RuntimeEngine runtimeEngine = getRuntimeEngine( applicationContext, deploymentId, userId, password );
   KieSession kieSession = runtimeEngine.getKieSession();
   Map<string object=""> processVariables;

   //qualify with very low interest rate, great credit, non-jumbo loan
   processVariables = getProcessArgs( "Amy", "12301 Wilshire", 333224449, 100000, 500000, 100000, 30 );
   kieSession.startProcess( "com.redhat.bpms.examples.mortgage.MortgageApplication", processVariables );

}

As you can see the last line is where the individual mortgage submission is pushed to JBoss BPM Suite. If you examine the rest of the class you will find multiple entries being started one after another.

We hope you now have a good understanding of the ways you can initiate a process and choose the one that best suits your project needs.