Getting Started with CHOReVOLUTION Virtual Machine

Introduction

Welcome to CHOReVOLUTION! This page is for all of users who are interested in learning more about CHOReVOLUTION Platform. The following sections provide a quick, hands-on instructions for building a simple e-Commerce choreography-based system.

By following this tutorial, you’ll learn fundamental CHOReVOLUTION features while working through some simple tasks. The whole exercise is divided in five main stages.

  • Stage One covers the CHOReVOLUTION Console. 
  • Stage Two covers the CHOReVOLUTION Studio.
  • Stage Three covers the synthesis process. 
  • Stage Four covers the deployment and enactment of the choreography.
  • Stage Five covers the execution of the choreography.

Once you are done with this tutorial, you will have a general knowledge of how to design, deploy, enact and run choreography-based systems.

However, before anything, for the big picture, you may want to watch this three-minute video.

Table of content

NOTE that in order to correctly complete the getting started, the user must download the OrderProcessor and Shipper business logic example here. They provide the business logic of the OrderProcessor and Shipper prosumer generated during the synthesis process.

Install and Start CHOReVOLUTION Virtual Machine

Requirements

To make the most out of the CHOReVOLUTION Virtual Machine, please consider the following hardware requirements:

  • CPU: dual core, 2 GHz (minimum), 64 bit
  • RAM: 6GB or 8+GB
  • Disk: 10 GB (minimum)

If you haven’t yet downloaded CHOReVOLUTION Virtual Machine just click and download the following components:

The virtual machine is equipped with a pre-installed instance of the runtime environment for the getting started choreography. The CHOReVOLUTION Studio already contains a project with a runnable client application for testing purposes. 

Import an Open Virtualization Format Virtual Machine

You can import an Open Virtualization Format (OVF) virtual machine and run it in VirtualBox.

Procedure

  1. Start VirtualBox
  2. In VirtualBox, select File > Import Appliance, see Figure 1.

ImportVM.png

Figure 1 - Import File

3. Browse to the .ovf file as in Figure 2 and Open File as in Figure 3.

SelectVM.png

Figure 2 - Select *.ovf File

SelectVM1.png

Figure 3 - Open *.ovf File

4. Click Continue. VirtualBox performs OVF specification conformance and virtual hardware compliance checks. Furthermore, check on Reinitialize the MAC address of all network cards item , see Figure 4. Click Import.

SelectVM2.png

Figure 4 - Configure Virtual Machine

A status bar indicates the progress of the import process.

After VirtualBox successfully imports the OVF virtual machine, the virtual machine appears in the virtual machine list, as in Figure 5.

ImportedVM.png

Figure 5 - CHOReVOLUTION Virtual Machine imported

5. You should now be ready to start! Select virtual machine and Click Start (see Figure 6).

StartVM.png

Figure 6 - CHOReVOLUTION Virtual Machine started

Back to top

Access to the CHOReVOLUTION Virtual Machine

The virtual machine is based on the Debian 9.2 (64 bit) version. The user can log on it by using the following credentials:

user: chorevolution
password: chorevolution

VMUser.png

Figure 7 - CHOReVOLUTION Virtual Machine started

Then Click Sign In, see Figure 7.

Back to top

Getting Started scenario overview

Through the implementation of a simple case study, we'll walk you through your first CHOReVOLUTION project, showing you how to use CHOReVOLUTION Studio, and start the Synthesis process. 

For the sake of clarity we have chosen a simple case study in e-Commerce domain (Figure 8). In our example, the customer is connected to the Internet through an internet client or a mobile app. She can select a list of items and, once the payment has been performed, the order can be processed, and the invoice can be sent back to the customer. Then, according to the delivery schedule, the items are packaged and sent to the customer, who will in turn receive shipping information.

CaseStudy.png

Figure 8 - Case Study Overview

Back to top

Stage One: CHOReVOLUTION Console

The user can access to the CHOReVOLUTION console to manage the service inventory, the choreographies, the synthesis processors and the enactment engines.

  • Click on Activities and run Firefox web client
  • The administration console can be logged-in by accessing the URL http://localhost:9080/syncope-console in a web browser, see Figure 9. 
  • In order to login use:
    username: admin
    password: password

idm.png

Figure 9 - CHOReVOLUTION Console login page

  • After the login, the dashboard is the first page to be shown, see Figure 10.

idm1.png

Figure 10 - CHOReVOLUTION console dashboard

You can see all the published services inside the inventory by selecting the Realms item menu.  After, click on SERVICE Tab for the services list, see Figure 11.

ServicesList.png

Figure 11 - Services published into the Service inventory

Inside the Extensions menu, you can see three items:

  • Choreographies item shows the list of Choreographies that are actually deployed and/or are running into the virtual machine.
  • Synthesis Processors shows the lists of the Synthesis Processors. In our virtual machine there is only one synthesis processor instance. 
  • Enactment Engines shows the lists of the Enactment Engines. In our virtual machine there is only one enactment engine instance. 

CHView.png

Figure 12 - Choreographies list

SPView.png

Figure 13 - Synthesis Processors list

EEView.png

Figure 14 - Enactment Engines list

Back to top

Stage Two: Start CHOReVOLUTION Studio

  1. Click on Activities and Click on CHOReVOLUTION Studio icon, see Figure 15.

VMUser1.png

Figure 15 - CHOReVOLUTION virtual machine home

2. Select a directory as workspace and Click Ok, see Figure 16.

ChorevolutionStudio.png

Figure 16 - CHOReVOLUTION Studio starting

3. The CHOReVOLUTION Studio is now opened, see Figure 17. You should see the getting-started project containing the related choreography.

ChorevolutionStudio1.png

Figure 17 - CHOReVOLUTION Studio 

Back to top

Stage Three: Start the Synthesis Process

In this section we will see how to perform some phases of the synthesis process, namely:

  • Validate the choreography specification.
  • Start the Synthesis Processor.
  • Create Choreography Deployment Description.
  • Upload the Choreography Deployment Description into CHOReVOLUTION console.

Validate the choreography specification

The Validation activity validates the correctness of the choreography specification against the constraints imposed by the BPMN2 Standard Specification. The goal is to check the choreography realizability and its enforceability by the process. 

  • Right-Click on GettingStarted.bpmn2 file, then CHOReVOLUTION Tools -> Validate BPMN2 Choreography Diagram, see Figures 18 and 19.

Validation.png

Figure 18 - Validation of choreography specification 

Validation1.png

Figure 19 - Validation results

Back to top

Start the Synthesis Processor

  1. Right-Click on getting-started.bpmn2 file, then CHOReVOLUTION Tools -> Start Synthesis Processor, see Figure 20.

startSynthesis.png

Figure 20 - Synthesis Process starting

2. The Selection activity is about querying the Service Inventory in order to select concrete services/things that can play the roles of the choreography participants. Select the service from the list on the left, and for each choreography participant Click on ..., see Figures 21 and 22.

startSynthesis1.png

Figure 21 - Selection of concrete service from inventory

startSynthesis2.png

Figure 22 - List of available services

Click Ok. When each Participant have been assigned a service, you should have the following figure:

startSynthesis3.png

Figure 23 - Selection phase completed

Click Next. 

Back to top

  1. Automatic generation of the Binding Components by the Synthesis Processor.
    The Binding Component generation activity concerns the generation of the Binding Components.  Binding Components are generated when the interaction paradigm of a selected service (or thing) is different from SOAP, which is the default interaction paradigm. 

getStartBCNew.png

Figure 24 - Binding Components generation

In this case, the interaction paradigm of all Participant is SOAP, then in Interaction paradigm of the Client participant item list, select SOAP.

Click Next. 

Back to top

2. Automatic generation of the Security Filters.
The Security Filter generation activity concerns the generation of the Security Filters. They are generated for those selected services having security policies associated. These artifacts filter the services interactions according to the specified security requirements.

getStartSFNew.png

Figure 25 - Security Filters generation

In this case, Click Next. 

Back to top

3. The Generation of the Coordination Delegates. The Coordination Delegates coordinates the interactions between the selected services (or things) in order to fulfill the global collaboration prescribed by the choreography specification, in a fully distributed way.

getStartCD0.png

Figure 26 - Coordination Delegates generation

Within the Coordination Delegates generation wizard you can specify Task Correlations. For a client participant (e.g., see Customer in the Figure 26), a Task Correlation defines a correlation between two choreography tasks, both having input messages only (see the tasks "Order Product" and "Notify Order Information"): the considered client participant is initiating in a task (i.e., the task "Order Product" in our example), and receiving in the other one (i.e., the task "Notify Order Information"). In other word, a Task Correlation serves to specify that the two correlated tasks will be realised by a client-side application and a single service (the Order Processor prosumer in our example, which is automatically generated) as a two-ways request-response (synchronous) interaction, see Figure 27.

getStartCD1New.png

Figure 27 - Task Correlation specification

Click OK and Finish. 

4. Outcome of the Synthesis Processor

At the end of the process we have two results: on one hand the choreography specific software artifacts and on the other the related Architectural Description model (i.e. getting-started.chorarch in Architecture folder), see Figures 28 and 29.

getStartProjNew.png

Figure 28 - Software artifacts generated

getStartChorArcNew.png

Figure 29 - Getting Started choreography architecture

Note: in this Getting Started case study, only the Coordination Delegates are generated.

5. Complementary projects

In addition, two new Eclipse Projects are created: OrderProcessor and Shipper, that are required to define the business logic of the OrderProcessor and Shipper prosumer, see Figure 30. 

prosumerGeneration.png

Figure 30 - Order Processor project structure

In particular, you will provide the OrderProcessor and Shipper service implementation, respectively.  
NOTE that in order to correctly complete the getting started, the user must download the OrderProcessor and Shipper business logic example here. The files provides the business logic of the OrderProcessor and Shipper prosumer generated during the synthesis process. 

After download and unzipped the zip file, you must:

  • replace the file in eu.chorevolution.prosumer.orderprocessor.business.impl.service.OrderProcessorServiceImpl java file with OrderProcessorServiceImpl.java file. 
  • replace the file in eu.chorevolution.prosumer.shipper.business.impl.service.ShipperServiceImpl java file with ShipperServiceImpl.java file.

Back to top

Create Choreography Deployment Descriptor

  1. Generate the deployment descriptor.
    The Choreography Deployment Description activity concerns the generation of the Choreography Deployment Description model (aka ChorSpec) starting from Choreography Architecture. 
  • Click-Right on getting-started.chorarch into Architecture folder, CHOReVOLUTION Tools-> Generate Choreography Deployment Descriptor, see Figure 31.

getStartDep.png

Figure 31 - Choreography Deployment Description model generation

A new getting-started.xml file is generated in Choreography Deployment folder, see Figure 32.

getStartDep1.png

Figure 32 - Outcome of Choreography Deployment Description model

Upload the Choreography Deployment Description into CHOReVOLUTION console

  1. Create and upload the choreography into CHOReVOLUTION Console
  • Click-Right on getting-started.xml, and click on CHOReVOLUTION Tools-> Upload and Create Choreography, see Figure 33:

getStartEE.png

Figure 33 - Create and Upload the choreography in CHOReVOLUTION console

A Wizard is opened:

getStartEE1.png

Figure 34

Click Ok. Optionally, you can upload the choreography image and provide a choreography description.

getStartEE3.png

Figure 35

The user will find a new Choreography in Extensions -> Choreographies into CHOReVOLUTION console, see Figure 36.

uploadChor.png

Figure 36 - Choreography created into the CHOReVOLUTION console

Back to top

Stage Four: Deploy and Enact Choreography

At this stage, you can select an Enactment Engine:

  • From Extensions -> Choreographies, click on Enact icon of getting-started choreography, see Figure 37.

enactengineSelection.png

Figure 37 - Enactment Engine selection phase

  • Select an Enactment Engine (in our case, there is only one EE named default-ee) from the list.

enactengineSelection1.png

Figure 38 - Enactment Engines list

  • Click Save. After few seconds, the Choreography status will change: from CREATED to STARTED. See Figure 39.

enactengineSelection2.png

Figure 39

Back to top

Stage Five: Run Choreography

In order to start the choreography, the user has to import the Customer Maven Project:

  • From the main menu bar, select command link File -> Import....
    The Import wizard opens (see Figure 40).

getStartEE3bis.png

Figure 40 - Import Customer project

  • Select Maven -> Existing Maven Projects and click Next.
  • Click Browse to locate the directory or file containing the projects.

getStartEE4.png

Figure 41 - Customer project selection

  • Select Customer project and click Ok.
  • Click Finish to start the import.

The Customer project simulates the behavior of the customer participant, who is responsible for the start event in the getting started choreography.

  • Select Customer project and enables the Java perspective, see Figure 42.

startEvent1.png

Figure 42 - Enabling of Java perspective

  • Run the Customer configurations, see Figure 43.

startEvent2.png

Figure 43 - Run Configuration

The Figures 44 and 45 show the simulated behavior of Customer tasks.

customer3.png

Figure 44

customer4.png

Figure 45

Back to top

Conclusion

Congratulations for having followed this tutorial!

Now you have the basis of how to design, deploy, enact and run choreography-based systems.
Please, provide your feedback now.

To explore CHOReVOLUTION deeply, follow this link. You'll better understand the mechanisms that permits the automated synthesis of dynamic choreographies and improve your knowledge about choreographies in general.