Getting Started with CHOReVOLUTION

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 two main stages.

  • Stage One covers the creation and publication of provider web services. 
  • Stage Two covers the design of a simple choreography with these web services.
  • Stage Three covers the 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

Install CHOReVOLUTION

If you have downloaded and launched the beta-test VM, please skip this part.

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

To install the CHOReVOLUTION Studio (required) you can follow this step-by-step guide.
To install Syncope (required) you can follow this guide.
To install and update into the inventory the Synthesis Processor you can follow this easy guide.

You should now be ready to start! (Of course if you have downloaded and launched the CHOReVOLUTION beta test VM, everything is already in place.)

Tutorial Overview

Through the implementation of a simple case study, we'll walk you through your first CHOReVOLUTION Service/Thing and Synthesis projects, 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 1). 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 1 - Case Study Overview

Back to top

Stage One: Creating Services

First you must publish services and/or things into the Service Inventory. This is achieved with the CHOReVOLUTION Studio by providing dedicated models (e.g., interface, security) for each service/thing by using CHOReVOLUTION Service/Thing projects in the Studio.

We will now take you through the three main steps to create/publish web services:

  • Create CHOReVOLUTION Service/Thing projects
  • Add Interface Specification models
  • Upload Services into Service Inventory

Download the zip archive containing the Interface Description (wsdl) related to this tutorial. Use the following values when required:

Create a CHOReVOLUTION Service/Thing project

  1. Start CHOReVOLUTION Studio
  2. Choose File -> New -> CHOReVOLUTION Service/Thing Project,  as shown in Figure 2:

NewCHOReVOLUTIONServiceThingProject.png

Figure 2 

3.  Type the name of the project, i.e., Carrier. Leave the Use default location checkbox selected (as shown in Figure 3).
Click Next.

thingCarrier.png

Figure 3

4. Click Next and select Web Service Description Language item, see Figure 4. 

thingCarrier1.png

Figure 4

5. Click Finish

The project is created and opened. In the Package Explorer view you can quickly navigate between elements within the selected folder or created file, as shown in Figure 5.

thingCarrier2.png

Figure 5

Add Interface Specification Models

6. Import the Carrier.wsdl file from previously downloaded zip archive; the easy way is to drag and drop the file into the folder interface. See Figure 6 for references.

thingCarrier3.png

Figure 6

Upload Services into Service Inventory

7. Right-Click on Carrier.servicething file, choose CHOReVOLUTION Tools -> Upload Service into Service Inventory, see Figure 7.

thingCarrier4.png

Figure 7

The Service Inventory Wizard will be shown, and you can add a new service in the service inventory or select the correct service role if it is already present in the inventory.
In the latter case, click Search button in Available Roles area, see Figure 10. Otherwise, see Figure 8 :

thingCarrier4bis.png

Figure 8

You have to specify the:

  • Service endpoint, i.e., http://chorevolution.disim.univaq.it/carrier/carrier
  • Service Role name, i.e., Carrier_role

Click Create.

thingCarrier5.png

Figure 9

Click Ok

thingCarrier5bis.png

Figure 10

The available Roles will listed, see Figure 10.
Select the correct role, i.e., Carrier_role in the list, then Click Add (>). The selected role will be added in the Selected Roles column, see Figure 11.

thingCarrier6.png

Figure 11

Click Ok.

thingCarrier6bis.png

Figure 12

The service, together with its Interface Description, is correctly uploaded in the Service Inventory.

Following the same steps, you can now create the CHOReVOLUTION Service/Thing projects for the remaining services (i.e., Invoicer, Scheduler, and Payment System).

This concludes Stage One.

Back to top

Stage Two: Designing Choreographies

In this section you will design and deploy a choreography. We will now take you through the four main steps to design and deploy choreographies: 

  • Create a new CHOReVOLUTION Synthesis project
  • Validate the choreography
  • Start the Synthesis process
  • Deploy a choreography

If you are not using the beta test VM, download the zip archive containing the choreography diagram with the related messages type file.

Create a new CHOReVOLUTION Synthesis project

The first step concerns the specification of the choreography diagram related to our "Hello World" case study.

  1. Start the CHOReVOLUTION Studio
  2. Choose File -> New -> CHOReVOLUTION Synthesis Project,  as shown in the Figure 13. Note that for a proper choreography deployment description generation, the user must use the Java JDK and NOT the Java JRE.

GettStart1.png

Figure 13

3. In the Project name field, type the name of the project, GettingStarted. Leave the Use default location checkbox selected (as shown in the Figure 13). 

4. Click Search and select an available Synthesis Processor (previously update into the inventory), see Figure 14. 

GettStartSynthesisProcessorSelection.png

Figure 14

Then, click Next. You should see the default names of the newly created project folders, see Figure 15.

GettStart3.png

Figure 15

5. Click Finish. Import the CHOReVOLUTION-GettingStarted.bpmn2 and types.xsd files from previously downloaded zip archive; the easy way is to drag and drop the file into the Choreography Diagrams folder. Now, the project is created and opened in the Project Explorer view, as shown in Figure 16 and 17.

newChorGet2.png

Figure 16

newChorGet4.png

Figure 17

It is important to remember you that some artifacts generated during the synthesis phase are optionals. In particular, for this "Getting Started" case study, the heterogeneity aspects (Binding Components) and security aspects (Security Filters) are not taken into account. 

Back to top

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.

getStartVal.png

Figure 18

getStartVal1.png

Figure 19

Back to top

Stage Three: Start the Synthesis Processor

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

startSynthesis.png

Figure 20

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

startSynthesis2.png

Figure 22 

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

startSynthesis3.png

Figure 23

Click Next. 

Back to top

3. Generation of choreography specific artifacts by the Synthesis Processor

3.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

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

3.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

In this case, Click Next. 

Back to top

3.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

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

Click OK and Finish. 

4. Results 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. GettingStarted.chorarch in Architecture folder), see Figures 28 and 29.

getStartProjNew.png

Figure 28

getStartChorArcNew.png

Figure 29

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

In particular, you will provide the OrderProcessor and Shipper service implementation, respectively. See Figure 31. Download the OrderProcessor and Shipper business logic example here.

prosumerGeneration1.png

Figure 31

Back to top

Stage Four: Deploy and Enact Choreography

  1. Generate the deployment descriptor. The Choreography Deployment Description activity concerns the generation of the Choreography Deployment Description model (aka ChorSpec). 
  • Click-Right on CHOReVOLUTION-GettingStarted.chorarch, CHOReVOLUTION Tools-> Generate Choreography Deployment Descriptor, see Figure 32.

getStartDep.png

Figure 32

A new CHOReVOLUTION-GettingStarted.xml file is generated in Choreography Deployment folder, see Figure 33.

getStartDep1.png

Figure 33

2. Upload and Create the choreography in the Identity Manager

At this point, we need to upload the choreography into Identity Manager (IdM):

  • Click-Right on GettingStarted.xml, and click on CHOReVOLUTION Tools-> Upload and Create Choreography, see Figure 34:

getStartEE.png

Figure 34

A Wizard is opened:

getStartEE1.png

Figure 35

Click Ok.

Optionally, the user can Search and Choice the enactment engine instance from the available ones. 

getStartEE2.png

Figure 36

Optionally, you can upload the choreography image and provide a choreography description, see Figure 37.

loadImage.png

Figure 37

Click Ok. At the end of the process, the choreography will be uploaded.

getStartEE3.png

Figure 38

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

uploadChor.png

Figure 39

Back to top

At this stage, you can select an Enactment Engine:

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

enactengineSelection.png

Figure 40

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

enactengineSelection1.png

Figure 41

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

enactengineSelection2.png

Figure 42

Back to top

Stage Five: Run Choreography

In order to start the choreography, the user has to import the Customer Maven Project (Download from here):

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

getStartEE3bis.png

Figure 43

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

getStartEE4.png

Figure 44

  • 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 45.

startEvent1.png

Figure 45

  • Run the Customer configurations, see Figure 46.

startEvent2.png

Figure 46

The Figures 47 and 48 show the simulated behavior of Customer tasks.

customer3.png

Figure 47

customer4.png

Figure 48

Back to top

Conclusion

Having followed this tutorial, now you have the basis of how to design, deploy, enact and run choreography-based systems. You can now go to this link and explore CHOReVOLUTION deeply, to better understand the mechanisms that permits the automated synthesis of dynamic choreographies and improve your knowledge about choreographies in general.