Working with WSO2 Integration Studio

The following sections describe how you can use the development experience provided by WSO2 Integration Studio to create and manage the artifacts for your integration use case.

Note that the following content is tested with an older version of WSO2 Integration Studio. If you are using an updated WSO2 Integration Studio, see the latest documentation.

Installing WSO2 Integration Studio

For instructions, see Installing WSO2 Integration Studio.

Using Templates

WSO2 Integration Studio provides a set of artifact templates that will help you get started with the most prominent integration use cases. Click the icon on the top-right of the WSO2 Integration Studio interface to open the Getting Started view shown below and then select the required template. There are ESB templates, data services templates, as well as business process templates.

Working with ESB artifacts

See the topics given below for instructions on how to use WSO2 Integration Studio to build your integration use case.

Creating ESB projects

An ESB solution consists of one or several project directories. These directories (listed below) store the various ESB artifacts that you create for your integration sequence.

	ESB Config Project This project directory stores the ESB artifacts that are used when defining a mediation flow. Use one of the following approaches to create an ESB config project: Creating an ESB Solution that includes an ESB Config project Open WSO2 Integration Studio and click ESB Project → Create New in the Getting Started view as shown below. In the New ESB Solution Project dialog that opens, enter a name for the ESB config project. Select the relevant check boxes if you want to create a Registry Resources project, Connector Exporter project, and/or a Composite Application project along with the ESB Config project. Click Finish to save the projects. The ESB projects are listed in the project explorer as shown below. Creating an individual ESB Config project Open WSO2 Integration Studio and click Miscellaneous → Create New Config Project in the Getting Started view as shown below. In the dialog that opens, select New ESB Config Project and click Next. Enter a name for the ESB config project. Click Finish and see that the project is now listed in the project explorer. You can now start creating the ESB config artifacts in your ESB Config project.
	Registry Resource Project Create this project directory if you want to create registry resources for your mediation flow. You can later use these registry artifacts when you define your mediation sequences in the ESB config project . Creating a Registry project Open WSO2 Integration Studio and click Miscellaneous → Create New Registry Project in the Getting Started view as shown below. In the dialog that opens, enter a name for the registry project. Click Finish and see that the project is now listed in the project explorer. See the instructions on creating and using registry artifacts.
	Mediator Project Create this project directory to start creating custom mediator artifacts. You can use these customer mediators when you define the mediation flow in your ESB config project. Creating a Mediator project Open WSO2 Integration Studio and click Miscellaneous → Create Mediator Project in the Getting Started view as shown below. In the dialog that opens, select Create New Mediator and click Next. Enter a project name, package name, and class name. Click Finish and see that the project is now listed in the project explorer. See the instructions on creating and using custom mediators.
	Data Service Project Create this project directory to start creating data services (.dbs files) for exposing various datasources as a service. Creating a Data Service project Open WSO2 Integration Studio and click DS Project → Create New Data Service in the Getting Started view as shown below. In the dialog that opens, enter a project name and click Next. Click Finish and see that the project is now listed in the project explorer. See instructions on managing data service artifacts using WSO2 Integration Studio.
	Data Source Project Create this project directory to start creating datasources that you can expose through a data service. Creating a Data Source project Open WSO2 Integration Studio and click DS Project → Create New Data Source in the Getting Started view as shown below. In the dialog that opens, enter a project name and click Next. Click Finish and see that the project is now listed in the project explorer. See instructions on managing data service artifacts using WSO2 Integration Studio.
	Connector Exporter Project Create this project directory if you have used ESB connectors in your medition sequence (defined in the ESB config project). All connector artifacts need to be stored in a connector exporter project before packaging. See the instructions on creating and using connectors.
	Composite Application Project This poject directory allows you to package all the artifacts (stored in other ESB projects) into one composite application (C-APP). This C-APP can then be deployed in the ESB server. See the instructions on packaging ESB artifacts.

You can use the above ESB projects and other various projects as follows:

Right-click the Project Explorer and click New → Project as shown below.
In the New Project dialog that opens, select the required project.

Importing ESB projects

If you have an already created ESB project file, you can import it to your WSO2 Integration Studio workspace.

Open WSO2 Integration Studio, navigate to File -> Import, select Existing WSO2 Projects into workspace, and click Next:
If you have a ZIP file of your project, browse for the archive file, or if you have an extracted project folder, browse for the root directory:

Select Copy projects into workspace check box if you want to save the project in the workspace.
Click Finish, and see that the project files are imported in the project explorer:

Creating ESB artifacts

Once you have created the ESB projects described above, you can create the artifacts under those projects.

Packaging ESB artifacts

To package the ESB artifacts, you need to create a Composite Application Project . Use one of the following methods:

Using an existing composite application

If you have an already created composite appliction project, do the following to package the ESB artifacts into the composite application:

Select the pom.xml file that is under the composite application project in the project explorer.
In the Dependencies section, select the artifacts from each of the projects.

Note: If you have created a custom mediator artifact, it should be packaged in the same composite application along with the other artifacts that uses the mediator.
Save the artifacts.

Creating a new composite application

If you have not previously created a composite application project, do the following to package the artifacts in your ESB Config project.

Open the Getting Started view and click Miscellaneous → Create New Composite Application .
In the New Composite Application Project dialog that opens, select the artifacts from the relevant ESB projects and click Finish.

Alternatively,

Right-click the project explorer and click New -> Project.
In the New Project dialog that opens, select Composite Application Project from the list and click Next.
Give a name for the Composite Application project and select the artifacts that you want to package.
In the Composite Application Project POM Editor that opens, under Dependencies, note the information for each of the projects you selected earlier.

Generating Docker images

To generate Docker images, follow the steps below:

Before you begin:

Install Docker from the Docker Site.
Create a Docker Account at Docker Hub and log in.
Start the Docker server.

Open the WSO2 Integration Studio interface.
Open an existing project. Right-click on Composite Project and then click Generate Docker Image.

The WSO2 Platform Distribution - Generate Docker Image wizard opens.
Enter information in the wizard as follows:
1. In the Generate Docker Image page, enter the following details:
  - Name of the application: The name of the composite application with the artifacts created for your EI project. The name of the EI projecty is displayed by default, but it can be changed if required.
  - Application version: The version of the composite application.
  - Name of the Docker Image: A name for the Docker image.
  - Docker Image Tag: A tag for the Docker image to be used for reference.
  - Export Destination: Browse for the preferred location in your machine to export the Docker image.
  Once you have entered the required details, click Next.
2. In the next page, select the EI projects that you want to include in the Docker image and click Finish.
  
  Once the Docker image is successfully created, a message similar to the following appears in your screen.

Exporting the ESB artifacts

Once you have created a composite application of your artifacts, you can export it into a CAR file (.car file):

Select the composite application project in the project explorer, right-click, and click Export Composite Application Project.
In the dialog that opens, give a name for the CAR file, the destination where the file should be saved, and click Next.
You can select the artifacts that should be packaged in the CAR file.
Click Finish to generate the CAR file.

Testing the ESB artifacts

You can test artifacts by deploying the packaged artifacts in the built-in Micro Integrator:

Be sure to create a composite application project and include your artifacts.
Right-click the composite application project and click Export Project Artifacts and Run.
In the dialog that opens, select the artifacts form the composite application project that you want to deploy.
Click Finish. The artifacts will be deployed in the WSO2 Micro Integrator and the server will start. See the startup log in the Console tab:
If you find errors in your mediation sequence, use the debugging features to troubleshoot.

Deploying ESB artifacts

WSO2 EI includes an ESB profile and WSO2 Integration Studio. The light-weight Micro Integrator is already included in your WSO2 Integration Studio package, which allows you to deploy and run the artifacts instantly. Alternatively, you can add the ESB profile server to your evironment and then deploy and run the artifacts in the ESB. See the instructions given below.

Using the ESB profile

To deploy the packaged artifacts in the ESB profile of WSO2 EI, you need to first add the ESB server to the tool. Follow the steps given below.

Open the Getting Started view and click Miscellaneous →Add New Server to open the New Server dialog.
In the New Server dialog that opens, expand the WSO2 folder and select the version of your server.
Click Next. In the CARBON_HOME field, provide the path to your product's home directory and then click Next again.
Review the default port details for your server and click Next.
Typically, you can leave these unchanged but if you are already running another server on these ports, give unused ports.

See Default Ports of WSO2 Products for more information.
To deploy the C-App project to your server, select the composite application from the list, click Add to move it into the configured list, and then click Finish.
On the Servers tab, note that the server is currently stopped. Click the 'play' icon on the tool bar. If prompted to save changes to any of the artifact files you created earlier, click Yes.
As the server starts, the Console tab appears. Note messages indicating that the composite app was successfully deployed.
You can also deploy/redeploy or remove C-Apps from a running server:

- To deploy/remove C-Apps, right-click the server, click Add and Remove and follow the instructions on the wizard.
- If you want to redeploy a C-App after modifying the included artifacts, select the already deployed C-App, right-click and click Redeploy.

Deploying EI solutions in Integration Cloud

Once you have developed an EI solution, you can host it on the Integration Cloud to make it available for multiple users. To understand how to host a solution on Integration Cloud, follow the steps below:

Before you begin:

Create an EI application as follows:
1. Open WSO2 Integration Studio. In the Getting Started page, click the Hello World Service template to start creating a new EI application based on this template.
2. In the Create Project Using Hello World Service Template dialog box, enter a name for the application. In this example, let's enter HelloWorldApps as the name.
  
  Click Finish to add the project for the application.
The project currently has the configurations derived from the template. Let's modify them as follows:

The purpose of this step is to change the default values. You can skip it if required.

You can skip this step if required.
1. In the left navigator, open the HelloWorldApplication/src/main/synapse-config/proxy-services/HelloWorld.xml file. Then click on the PayloadFactory icon to open the Payload Factory Mediator configuration in the Properties tab.
2. In the Payload field, replace the existing value with {“data”: “HelloWorld”}.
Before deploying the composite application, you need to know the key of the organization to which you are deploying it. To get the organization ID, sign in to the Integration Cloud and access your organization as follows:

If you already know the key of the organization to which the application needs to be deployed, you can skip this step.
1. Sign in to the Integration Cloud with your credentials.
2. Click on the following icon tray in the right end of the top bar.
  
  Then click Organizations to open the Manage Organizations page.
  
  The keys of the available organizations are displayed as shown below.
Deploy the Hello World Application that you created as follows:
1. In the WSO2 Integration Studio, open your workbench. Then right-click on HelloWorldAppsCompositeApplication, and then click Deploy to Integration Cloud. The WSO2 Integration Cloud - Authentication wizard opens as follows.
2. Enter the following information in the wizard:
  - Organization Key: The key of the organization to which you want to deploy the EI application. The required organization key needs to be already registered under your Integration Cloud account.
  - Email: The email address with which you are registered in the Integration Cloud.
  - Password: The password with which you sign in to the Integration Cloud.
3. Click Finish. The WSO2 Platform Distribution wizard opens.
4. In the WSO2 Platform Distribution wizard, select the applications that you want to include in the CAR file that you are deploying to the Integration Cloud. For this example, select HelloWorldApps as shown below.
5. Click Next, and then click Finish. A message appears to inform you that your application is being deployed to the cloud. Once the deployment is complete, the following message appears.
Access your organization on Integration Cloud as you did in step 3. The HelloWorldAppsComposite Application you deployed is displayed as follows.
To create a new version, repeat step 4, sub steps a-c. Then follow the steps below to create a new version.
1. In the page where you select deployable artifacts, select HelloWorldApps and click Next.
2. In the next page, select the Create New Version option and update the value displayed in the Application Version field.
3. Click Finish.
4. Sign in to the Integration Cloud and click on the HelloWorldApps application.
  
  The application opens, and the updated version is displayed as shown below.

Working with business process artifacts

The following topics explain the steps involved in building BPMN/BPEL artifacts and Human Tasks for business workflows, and for deploying them in the Business Process Server profile of WSO2 EI.

Creating business workflows

	BPMN workflows If you are using BPMN to define a business workflow, the BPMN artifacts should be stored in the BPMN project. After creating a BPMN project, add a BPMN diagram to that project. See the instructions given below. 1. Creating a BPMN project Open the Getting Started view and click BP Project → Create New BPMN Project. In the Create an Activiti Project dialog, enter a name for the project and click Next. In the next step, select any referenced projects and click Finish . Click Open Perspective in the below message. You will not get this message if you are already in the Activiti perspective. You can access the current perspective from the project explorer. When you click Finish , the project will be listed in the project explorer (Activity explorer). 2. Creating BPMN artifacts Right-click your BPMN project and go to New → Other. Select BPMN Diagram and click Next. Select the diagrams folder in your BPMN project, give a file name for your diagram and click Next. Select a template diagram or choose to create an empty diagram and click Finish. You will see that the BPMN diagram has been added under the project you specified and a new empty diagram will open up along with a palette. You can drag and drop notations from the Pallete to create the desired diagram. See the BPMN tutorials for step-by-step instructions on how to create a BPMN workflow.
	BPEL workflows If you are using BPEL to define a business workflow, you need to create a BPEL workflow . See the instructions given below. Creating a BPEL workflow Open the Getting Started view and click BP Project → Create New BPEL Workflow. In the New BPEL Project dialog that opens, select Create New BPEL Workflow and click Next. Enter the project name, process name, process namespace, and template accordingly, and click Finish . Click Open Perspective in the below message. You will not get this message if you are already in the BPEL perspective. You can access the current perspective from the project explorer. A new BPEL diagram is added to the project explorer under the BPEL project. You can drag and drop artifact symbols from the pallette to create the desired diagram. See the BPEL tutorials for step-by-step instructions on how to create a BPEL workflow.
	Human Tasks If you want to integrate a 'human task' into a business workflow, you need to defined a Human Task artifact as explained below. Creating human task artifacts Open the Getting Started view and click BP Project → Create New Human Task as shown below. In the Human Task Project Wizard that opens, enter a project name, process name, process namespace, and click Finish . The Human Task project and artifact files are added to the project explorer as shown below. The 'newfile.ht' file in the project lists the various properties of the human task artifact that should be defined. Click on each of the topics (Task Properties, Task Input, Task Output, Presentation Elements, People Assignment) to expand the view as shown below. See the tutorial on simulating a simple order approval process for instructions defining these properties. See the Human Task tutorials for step-by-step instructions on integrating human tasks into a business workflow.

Packaging BPMN artifacts

Follow the steps given below.

Select Window -> Show View -> Other in the top menu of your screen.
Search for Package Explorer and click Open.
In the Package Explorer, right-click the BPMN project and click Create deployment artifacts.
The BPMN artifacts will be pacakged into a .bar file and stored in the / deployment folder as shown below.

Deploying BPMN artifacts

You can deploy the .bar file of the BPMN process using the management console of the Business Process profile in WSO2 EI.

Install WSO2 Enterprise Integrator and start the Business Process profile by executing one of the given commands. See the installation guide for more information on setting up and running WSO2 EI.
Open the management console from https://localhost:9445/carbon/ .
Log in by using admin as the username and password.
Go to Main -> Manage -> Add ->BPMN and upload the .bar file.

Packaging BPEL/Human Task artifacts

BPEL artifacts and Human Task artifacts can be packaged into separate .zip files. Follow the steps given below.

Select one of the projects (BPEL or Human Task) from the Project Explorer.
Right-click the project and select Export Project as a Deployable Archive.
When the Project Export dialog opens, provide the location where you want to save the artifact and click Finish.

This will generate a .zip archive that can be deployed directly in the Business Process profile of WSO2 EI.

Deploying BPEL/Human Task artifacts

Once you have packaged your BPEL or Human Task artifacts, deploy them in the Business Process profile as follows:

Install WSO2 Enterprise Integrator and start the Business Process profile by executing one of the given commands. See the installation guide for more information on setting up and running WSO2 EI.
Open the management console from https://localhost:9445/carbon/ .
Log in by using admin as the username and password.
Go to the Main tab and upload the relevant .zip files.
- Click Add ->BPEL and upload the .zip file with your BPEL artifacts.
- Click Human Tasks →Add and upload the .zip file with your Human Task artifacts.