CHOReVOLUTION Studio and Synthesis Processor

Table of content

Introduction

This section is a quick guide to install and use CHOReVOLUTION Studio and Synthesis Processor from user point view. The synthesis process is available in REST mode.

The CHOReVOLUTION Studio is an Eclipse-based development environment that is customized for developing choreography service oriented systems. It provides a ready-to-use environment to design, synthesize, deploy and enact in secured and adaptable way a choreography by using the CHOReVOLUTION platform.

It is freely available for development and internal business operations use with no time limits, fully open-source and licensed under the terms of the Apache License 2.0.

CHOReVOLUTION Studio - Installation Guide

This Installation Guide will guide the user in the installation and use of CHOReVOLUTION Studio and Synthesis Processor module. To better understand the structure of the CHOReVOLUTION Studio and the Synthesis Processor, we have included sections where the user is introduced to the logic which they were implemented and how they work together.

Requirements

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

CPU: dual-core, 2 GHz (minimum), 32-bit or 64 bit (recommended)
RAM: 1,5 GB or 2+ GB (recommended)
Disk: 1,5 GB (minimum, depends on your projects)

The software requirements can be summarized as:

Microsoft Windows, Mac OS X or Unix Operating Systems and derived are supported
Latest Oracle JDK 8 or OpenJDK 8 (only Unix Operating Systems based) available is recommended, latest Oracle JDK 7 or Open JDK 7 available is also supported

Configure the memory settings

If you want to tune the memory allocation for your JVM, you only need to edit the Chorevolution Studio.ini the file corresponding to your executable file.
Learn more on http://www.oracle.com/technetwork/java/hotspotfaq-138619.htmlhttp://www.oracle.com/technetwork/java/hotspotfaq-138619.html.

Download information

CHOReVOLUTION Studio is available for your Operating System. Save the compressed file in your system.

Installation steps

Follow the instructions in this section to install the IDE on your system. These installation instructions apply to all supported platforms. For the list of supported platforms and system requirements, see the Requirements section.

For all Operating Systems

To install the software:

After the download completes extract the archive file on your hard drive
If the operation was successful double click on Chorevolution Studio executable file.

Uninstalling steps

Follow the instructions in this section to uninstall the IDE on your system. These installation instructions apply to all supported platforms. For the list of supported platforms and system requirements, see the Requirements section.

For all Operating Systems

If necessary, you can uninstall the Chorevolution Studio using the following procedures:

Shut down the software
Drag the program folders or files to the Trash

Synthesis Processor - Installation Guide

The Synthesis Processor is realized by a number of REST (REpresentational State Transfer) services that perform synthesis-time activities, and related model transformations, to automatically generate Binding Components, Security Filters, Coordination Delegate, Choreography Architecture, and Choreography Deployment Description. Moreover, it exposes REST API to download specific artifact generated, validate BPMN2 Choreography Diagram, and design BPMN2 Choreography Diagram.
It exposes a full-compliant JAX-RS 2.0 RESTful interface which enables third-party applications, written in any programming language, to consume synthesis processor services.

The Synthesis Processor is provided as a set of REST-services and it is bundled as a Java web application that can be deployed into any Java EE application server (e.g., Apache Tomcat).

It is freely available for development and internal business operations use with no time limits, fully open-source and licensed under the terms of the Apache License 2.0.

The following sections provide a quick guide to install Synthesis Processor and use it from the end-users point of view.

Requirements

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

CPU: dual-core, 2 GHz (minimum), 32-bit or 64 bit (recommended)
RAM: 1,5 GB or 2+ GB (recommended)
Disk: 250 MB (minimum)

The software requirements can be summarized as:

Microsoft Windows, Mac OS X or Unix Operating Systems and derived are supported
Latest Oracle JDK 8 or OpenJDK 8 (only Unix Operating Systems based) available is recommended, latest Oracle JDK 7 or Open JDK 7 available is also supported
Latest Apache Tomcat version available or can be used any Java Web Container that it implements the Java Servlet 3.1 Specification.

Download information

Synthesis Processor is available for your Operating System. Save the compressed file in your system.
A synthesisprocessor-2.1.0.war package is available for installation on your application server of choice. After that, you can deploy the web archive depending on the mode of your application server (e.g. in Tomcat you can copy the .war in the webapps directory).

Moreover, Synthesis Processor is available a REST version already embedded in the web server tomcat, i.e., synthesisprocessor-rest-2.1.0.zip.

CHOReVOLUTION Studio - User Guide

This section provides a very simple and quick introduction to the CHOReVOLUTION Studio workflow by walking you through the creation of the WP5 Case Study. The steps defined in the generative approach of CHOReVOLUTION will be shown through the implementation of the case study.

Once you are done with this tutorial, you will have a general knowledge of how to create and run applications in the IDE.

Currently, the CHOReVOLUTION Studio provides the following features:

create or import CHOReVOLUTION Synthesis Project
create or import CHOReVOLUTION Service/Thing Project
create or import choreography diagrams with BPMN2 modeler
create or import choreography architecture(Chorarch) model
create or import general interface description language(GIDL) model
create or import Service/Thing model

Setting up the CHOReVOLUTION Workbench preferences

To the following links, logical process, the user can see the process underlying of the CHOReVOLUTION platform. It has been implemented within the CHOReVOLUTION Studio, and in the following sections, we will see how.

The user can manage the location of generated CHOReVOLUTION source models and the URI of the required external services (e.g. Apache Syncope) in Preferences Dialog:

Start CHOReVOLUTION Studio
Select CHOReVOLUTION Studio > Preferences > Chorevolution, as shown in Figure 5 and 6:

Figure 5

Figure 6

Setting up CHOReVOLUTION Perspective

The Chorevolution projects is associated to the CHOReVOLUTION Perspective, see Figure 7:

Figure 7

If the CHOReVOLUTION Perspective is not enabled in your IDE:

Click Open Perspective icon, see Figure 8:

Figure 8

2. Select CHOReVOLUTION item, see Figure 9:

Figure 9

Creation CHOReVOLUTION Service/Thing project

This section provides a quick start tutorial on how to create a CHOReVOLUTION Service/Thing project within the CHOReVOLUTION Studio, how to model a choreography (WP5 Case Study), and how to bind a BPMN2 Participants involved in the choreography to services stored in into the Service Inventory (Syncope). In order to let the software work correctly, please be sure to have Syncope installed and running.
This section describes how CHOReVOLUTION Studio implements the Development process defined in CHOReVOLUTION development process section.

To create a CHOReVOLUTION Service/Thing project:

Start CHOReVOLUTION Studio
In the IDE, choose File -> New -> CHOReVOLUTION Service/Thing Project, as shown in the Figure 10:

Figure 10

3. In the Project name field, type the name of the project, e.g. PersonalWeatherStation. Leave the Use default location checkbox selected (as shown in the Figure 11).
Click-Left Next.

Figure 11

4. Select General Interface Description Language item, see Figure 12.

Figure 12

5. Click Finish

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

Figure 13

6. Create or import PersonalWeatherStation.wsdl file. Right-Click on Interface folder, New -> Other -> Web Services -> WSDL File.

Another way to create or import the Service Interface Description is to use GIDL model. Right-Click on Interface folder, New -> Other -> CHOReVOLUTION -> Generic Interface Description Language. For this tutorial, we will use this way. See Figure 14.

Figure 14

Adding Security Model

During the service registration phase, the service provider could also specify some security constraints to access it. For instance, he could:

Describe which kind of authentication is required to access his service (e.g. Username/Password, X509 certificate)
Describe if the service uses a secured communication (SSL/TLS) or not

For that, the service provider must create a security model into the security repository of his CHOReVOLUTION Service/Thing Project. The creation of this model is realized using the security model wizard present into the Chorevolution project wizard. To help the definition of this model, a graphical editor could be used.

For example, the user can create or import pws.security file. Right-Click on security folder, New -> Other -> CHOReVOLUTION -> Security, see Figure 15.

Figure 15

Click Next, see the Figure 16.

Figure 16

Click Finish.

The new model is created and opened in the IDE. In the Project Explorer view the user can quickly navigate within the security folder, and open file in the graphical view, see Figures 17 and 18.

Figure 17

Figure 18

To start, the service provider must create a PolicySet. This PolicySet will contain all the security aspects of his service. This PolicySet is dedicated to a resource. This resource (URL of the resource) must be specified as a property of the PolicySet element (Ressource property), the name and the domain of the resource.

Then, using the different element presented into this palette, he could specify:

The Authentication requirements by providing the following elements (properties):
- The Credential type (UsernamePassword or Custom) : the credential type used to be authenticated into the service. In the second case, the user can implement its own security mechanism by providing a zip archive containing the security implementation (based on java application).
- The Custom Parameters Names: list of custom parameters involved in the security part.
- A Generic account and Generic credential: a generic account and credential used to access the service and provided by the service provider himself. It’s not the most current way. In general, the credential must be empty and the account used during the choreography must be created by the choreography designer and register during the choreography design.
- The Authentication Element: it expresses the authentication element taken into account in order to be identify into the service. The possible elements are the last name of the user or its email address
- The AuthNTypeForwarded: it expresses the kind of authentication element expected by the server. The possible values are UserAccount, GenericAccount, and CustomAccount. In case of the service needs to know explicitly the user which try to access it, the service owner must specify UserAccount into the security model. In the other cases, a generic account could be used. This generic account could be an account dedicated to the choreography, for instance.

The Communication requirements by providing the following elements (properties):
- The Secured Communication (True of False): this property indicates if the service must be contacted using TLS communication or without

Upload Service into Service inventory

In order to select concrete service/things that can play the role of the choreography participants, the user can upload service into Service Inventory:

Click-Right on PersonalWeatherStation.servicething file, CHOReVOLUTION Tools -> Upload Service into Service Inventory, see Figure 19.

Figure 19

Figure 20

2. From Service Inventory, the user can select the service to bind to the specific participant.

Click on the Search button. On the left column you can see a list of all available roles, see Figure 21:

Figure 21

You can see that a PersonalWeatherStation_role is present. Or you can obtain the filtered list using a filter by role name item, see Figure 22 and Figure 23.

Figure 22

Figure 23

Select PersonalWeatherStation_role role.

In our case, as the Credential Type is Custom, the user must provide its own security implementation. Click Browse Files button and select zip file.

Figure 24

Figure 25

Click Ok.

Figure 26

Creation CHOReVOLUTION Synthesis project

This section explains how CHOReVOLUTION Studio implements the synthesis process described in CHOReVOLUTION development process section.

To create a CHOReVOLUTION Synthesis project:

Start CHOReVOLUTION Studio
In the IDE, choose File -> New -> CHOReVOLUTION Synthesis Project, as shown in the Figure 27.

Figure 27

3. In the Project name field, type the name of the project, e.g WP5CaseStudy. Leave the Use default location checkbox selected (as shown in the Figure 27). Note that for a proper choreography deployment description generation, the user must use the Java JDK and NOT the Java JRE.
Select the Synthesis Processor functionality provided by means of REST services. Click Search and select an available Synthesis Processor. See the Figure 28.

Figure 28

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

Figure 29

Click Finish.
Now, the project is created and opened in the IDE. In the Project Explorer view, the user can quickly navigate between elements within the selected folder or file created, as shown in Figure 30.

Figure 30

CHOReVOLUTION Synthesis project properties

The user can get properties information on the project:

Click on WP5CaseStudy folder and select Properties item, see Figure 31.

Figure 31

2. Select CHOReVOLUTION category, see Figures 32, 33 and 34.

Figure 32

Figure 33

Figure 34

Creating Choreography diagram

As a first step, the user needs to create the choreography diagram by using the Eclipse BPMN modeler. The user can create or import diagram in Choreography Diagrams folder.
In Choreoagraphy Diagrams folder there are two empty files: wp5.bpmn2 and types.xsd.
In our case, we show the steps to create from scratch the wp5.bpmn2 file.

Click on Choreoagraphy Diagrams folder -> New -> Other, see Figure 35.

Figure 35

2. Select CHOReVOLUTION -> BPMN 2.0 Choreography Diagram as shown in Figure 36.

Figure 36

3. Click Next. In File name field, type the file name of the new BPMN2 file, e.g. wp5.bpm2, see Figure 37:

You can specify the Location and Target Namespace by using the related field
Click Finish

Figure 37

4. In the IDE, the BPMN 2.0 view is opened. Now, the choreography diagram can be created by using the elements provided in the related palette, see Figure 38.

Figure 38

5. In order to ensure the proper execution of the synthesis process, if in the Choreography Diagram there are message types different from the basic ones (i.e. different from the types already defined in XSD), the choreography developer(s) must provide the XML schema (types.xsd) associated with the messages exchanged between the choreography participants of the choreography defined in the previous paragraphs, see Figure 39.

Figure 39

Choreography diagram Validation

The user can validate the model; Right-Click on wp5.bpmn2 file, then CHOReVOLUTION Tools -> Validate BPMN2 Choreography Diagram, see Figure 40 and 41.

Figure 40

Figure 41

Choreography synthesis wizard

Service Selection

In order to define the bind between a selected BPMN2 Participant and service in Service Inventory:

Right-Click on wp5.bpmn2 file, then CHOReVOLUTION Tools -> Start Synthesis Processor, see Figure 42.

Figure 42

Select the service from the left list, and for each participant Click on ..., see Figure 43 and Figure 44.

Figure 43

Figure 44

In the end, see Figure 45.

Figure 45

Click Next.

Binding Components

The Figure 46 shows the wizard to configure the Binding Components generator when the selected concrete services does not use the SOAP protocol:

Figure 46

Click Next.

Security Filters

During the synthesis of the choreography, you need to provide some security elements dependent on the concrete services used and also dependent on the security constraints required for the choreography.

To help the definition of this previous information, the following wizard must be used.

Figure 47

The first part of this view is dependent on the concrete services selected during the role binding phase. If a concrete service is selected and this service is associated with a security model containing a constraint around the authentication, it must appear in this table. Just as a reminder, during the service registration, the service owner could specify the expected authentication method using the AuthNTypeForwarded parameter. This parameter is used to specify if the authentication account expected by the concrete service is a user account or a generic account. This information appears in this view in the Authentication Type column following three possible values: SHARED (for generic account), PER-USER (for user account) and CUSTOM (for custom authentication type). In the case of the authentication type is PER_USER, the authentication elements are provided by the end-user during his registration (In this case, nothing to do with this service). In the case of the authentication type is SHARED, a generic account must be specified using the username and password cells. In the case of the authentication type is CUSTOM, a custom zip file has been specified during the Service/Thing creation. Indeed, the value in Custom Auth ZIP cells is Loaded. This analysis must be realized for each concrete services present in this table.

The second part of the view is used to specify the security constraints applied to access the choreography. Two possibilities, a choreography is secured or not. If not, the user authentication is not required to access the choreography otherwise, the user must provide his credentials to access.
In case of the secured choreography is required, it's possible to specify some authorization rules. For that, it's possible to authorize the choreography access to only some persons belonging to specific security groups as defined into the Identity Manager.

The last part is for communication. It's possible to specify is the choreography must be accessible using a secured communication protocol (HTTPS) or not (HTTP)

Click Next.

Adapters

Adapters allow to bridge the gap between the interfaces and interaction protocols of the selected concrete services and the ones of the (respective) participant roles (in choreography tasks) they have to play and solve possible interoperability issues due to operation names mismatches and I/O data mapping mismatches.

Figure 48

If the Service that is playing the role of the Receiving Participant of a Choreography Task has its Operation name different from the Task name, the Service needs adaptations before proceeding with the Synthesis Processor Wizard.

From the left to the right, we can see the Initiating participant, the Task name, the Receiving participant, the Receiving participant linked to service, the service location, and the ... button.
For each initiating participant of the choreography tasks, Click on ... to select the concrete service into the inventory, see Figure 48.

A new window will be opened displaying the Adapter Model Wizard. This wizard allow the user to specify the mapping between the receiving participant and the related service within a specific choreography task. See Figure 49.

Figure 49

The left column shows the selected participant (Mobility Information Planner) with role defined (Journey Planner). The right column shows the concrete service inventoried. The red shapes identify mandatory elements to map, those in orange are optional.

Figure 50

Click on the square to start mapping the selected Choreography task (see Figure 50), then click on the triangle to apply the mapping with the selected Service operation (see Figure 51).

Figure 51

Once done, the system will try to auto-assign its Input and Output message; if it's not possible, the user must assign the Choreography input message with a Service input message and a Choreography output message with a Service output message, as done with the Task name.

Subsequently, the Choreography task message items must be "mapped" with the related Service message items.

Each item has a symbol inside parenthesis:

( 0 ) : it means that has 0 occurrences.
( ? ) : it means that can have 0 or 1 occurrence.
( * ) : it means that can have 0 to unbounded occurrences.
( 1 ) : it means that has exactly 1 occurrence.
( + ) : it means that has from 1 to unbounded occurrences.
( * ) : it means that has unbounded occurrences.

Each item has a type: it can be a simple or complex type. Simple types are the XSD basic ones, as double, integer, string…
Complex types are composed by other Simple or Complex types.
If a Complex Type has all its inner items "mapped", it will become green, and it's not mandatory to be mapped.

If an element cannot be mapped, it can have assigned a "static value" or a value taken from an Input message item, see Figure 52.

Figure 52

Double click on a Simple Type item that is not mapped (Red) into Output message of the Choreography Task or into Input message of the Service operation.

A new window will be displayed, see Figure 53.

Figure 53

Clicking on the "+" or on the "static value" button. The user can add the static value (or the string concatenation of the static values) into the Text Field and then insert the value that you need. You can also add a value took from an Input message's item of the Choreography part clicking on the name relative to the item's value you would to add.

Each element in the left side can be mapped with one or more elements of the right side, see Figure 54.

Figure 54

If an element of the Service input message has two or more lines incoming, or an element of the Choreography output message has two lines outgoing, and that element is a Simple Type, you can just double-click on it to show the Transformation Rule wizard.

Figure 55

This wizard is very similar to the Static Value Wizard but has more functions available and more items on the right side.
Clicking on a function, it will be added to the Text Field with some example value:

+: is a string concatenation between members
static value: is the static value that would be assigned
valueof(elementName, "elementValue_0":"returnValue_0", "elementValue_1":"returnValue_1"): elementName is one element and the other values are just "replace":"with". The function replaces in elementName (it must be a Restriction) the "replace" with "with".
valueof(elementName, "elementValue_0":"returnValue_0", "elementValue_1":"returnValue_1"): elementName is one element and the other values are just "replace":"with". The function replaces in elementName (it must be a Restriction) the "replace" with "with".
json(elementName, "elementValue") just takes an element with "elementValue" from an "elementName" that is returning a json.
parseDate(elementName, "regexpToBeParsed") takes an element with a "elementName" and extracts the date using "regextToBeParsed" that must be a regexp.

The "elementName" values can easily be added clicking the relative button in the field: "Members of the transformation rule".
The "Fields from Request" field does exactly the same that in the Static Value Wizard.
To save a transformation rule, just click "OK".

Figure 56

To remove a previously saved Transformation Rule: double-click on Choreography item, then click on Remove button, see Figure 56.

Once the Adapter model creation is terminated, just click on the "OK" button: the previously clicked button will change and his text will be "Created", see Figure 57.

Figure 57

To edit a previously created Adapter Model, just click on the "Created" button and the relative Adapter Model will be shown.
When all the adapters are created, just click on the "Next" button to go ahead.

In the end, see Figure 58.

Figure 58

Click Next.

The AUTO-MAP button allows the user to automatically generate the mappings. The operation takes advantages of syntactic binding rules: the user must verify the correctness of the mapping, make changes, and add missing mandatory mappings.

Figure 59

Coordination Delegates

The CD generation activity concerns the generation of the Coordination Delegates. The CDs coordinate the interactions among the selected services (or things) in order to fulfill the global collaboration prescribed by the choreography specification, in a fully distributed way.

Figure 60

Within the CD generation wizard, you can specify Task Correlations.
For a client participant (e.g., see STApp in the Figure 60), a Task Correlation defines a correlation between two choreography tasks, both having input messages only (see the tasks "Get Trip Plan", "Get Best Route", etc): the considered client participant is initiating in a task (i.e., the task "Get Trip Plan" in our example), and receiving in the other one (i.e., the task "Set Trip Plan"). 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 as a two-ways request-response (synchronous) interaction, see Figures 61 and 62.

Figure 61

Figure 62

Click Ok and Finish.

Figure 63

At the end of the wizard, all the additional software artifacts are generated with the related Architectural Description model, i.e., wp5.chorarch in Architecture folder, see Figure 64.

Figure 64

During the synthesis process, the projections (BPMN2 choreography) associated with the various participants of the choreography will be generated, see Figure 65.

Figure 65

In addition, will be generated three new Eclipse Projects: Tourist Agent, Tourism Information Planner, and Mobility Information Planner, that are required to define the business logic of the Tourist Agent and Trip Planner prosumer, see Figure 66.

Figure 66

In particular, you will provide the TouristAgent, Tourism Information Planner and Mobility Information Planner service implementation, respectively. See Figure 72.

Figure 67

Choreography Architecture generation

Considering the selected service/things and the generated BCs, SFs, As, and CDs, an architectural description is automatically generated, and a graphic representation of the choreographed system is provided, see Figure 68.

Figure 68

In the IDE, the ChorArch view is opened and the chorarch model can be updated or modified by using the elements shown in the related palette, see Figure 69 and 70.

Figure 69

Figure 70

Choreography Deployment generation

The last activity of the synthesis process concerns the generation of the Choreography Deployment Description (called Choreography Specification (ChorSpec)) out of the Choreography Architecture model.

Click-Right on wp5.chorarch, CHOReVOLUTION Tools-> Generate Choreography Deployment Descriptor, see Figure 71.

Figure 71

A new wp5.xml file is generated in Choreography Deployment folder, see Figure 72.

Figure 72

Now, the user can upload the choreography specification on Identity Manager. Click Right on wp5.xml file in Choreography Deployment folder.
Select CHOReVOLUTION Tools->Upload and Create Choreography, see Figure 73.

Figure 73

A new wizard is opened where the user can provide the enactment engine location, if available, and a choreography description and image, see Figure 74.

Figure 74

Click Ok.

Figure 75

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

Figure 76

The Choreography is now available in syncope console.