All docs This doc
Skip to end of metadata
Go to start of metadata

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. 

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 Tooling 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
  1. Open WSO2 Integration Studio and click ESB Project → Create New  in the Getting Started view as shown below.

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

  3. Click Finish to save the projects. The ESB projects are listed in the project explorer as shown below.

 Creating an individual ESB Config project
  1. Open WSO2 Integration Studio and click Miscellaneous → Create New Config Project  in the Getting Started view as shown below.
  2. In the dialog that opens, select New ESB Config Project and click Next.
  3. Enter a name for the ESB config project.
  4. 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
  1. Open WSO2 Integration Studio and click Miscellaneous → Create New Registry Project  in the Getting Started view as shown below.
  2. In the dialog that opens, enter a name for the registry project.
  3. 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
  1. Open WSO2 Integration Studio and click Miscellaneous → Create Mediator Project  in the Getting Started view as shown below.
  2. In the dialog that opens, select Create New Mediator and click Next.
  3. Enter a project name, package name, and class name.
  4. 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
  1. Open WSO2 Integration Studio and click DS Project → Create New Data Service  in the Getting Started view as shown below.
  2. In the dialog that opens, enter a project name and click Next.
  3. Click Finish and see that the project is now listed in the project explorer.

See instructions on managing data service artifacts using WSO2 EI Tooling.

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:

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

Creating ESB artifacts 

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

After creating the ESB Config project, you can define the mediation flow by using the required integration artifacts. R ight-click the ESB config project, click New, and select the required ESB artifact. See the links given below for more information on each of the artifacts:

Proxy Service | REST API | Inbound Endpoint | Scheduled Task | Sequence | Template | Endpoint | Local Entry | Message Processor | Message Store


Registry artifacts are resources (such as images, WSDLs, XSLTs), which are stored in a central repository. To create such artifacts, right-click the Registry Resource project , click New, and select Registry Resource. See the instructions on creating and using registry artifacts.


After creating the Connector Exporter project, right-click the project, click New, and select Add/Remove Connectors to start adding connector artifacts to your project. See the instructions on working with connectors.

Data service artifacts are used for exposing data as a service. After creating the Data Service project, right-click the project, click New, and select required artifact types. See the instructions on creating and using data services.


After creating the Mediator project, right-click the project, click New, and select required artifact types. See the instructions on creating and using custom mediators.

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:

  1. Select the pom.xml file that is under the composite application project in the project explorer.
  2. 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.

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

  1. Open the Getting Started  view and click  Miscellaneous → Create New Composite Application .

  2. In the  New Composite Application Project  dialog that opens, select the artifacts from the relevant ESB projects and click Finish.

Alternatively, 

  1. Right-click the project explorer and click New -> Project.
  2.  In the New Project dialog that opens, select Composite Application Project from the list and click Next.
  3. Give a name for the Composite Application project and select the artifacts that you want to package.
  4. 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:

  1. Install Docker from the Docker Site.
  2. Create a Docker Account at Docker Hub and log in.

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

    The WSO2 Platform Distribution - Generate Docker Image wizard opens.
  3. 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.
       

Testing ESB artifacts

Once you have developed an integration solution, WSO2 Integration Studio allows you to build unit tests for the following:

Create Unit Test Suite
  1. Open WSO2 Integration Studio.
  2. Open an existing project with your integration solution.
  3. Right-click the test folder, which is parallel to the src folder and go to New -> Unit Test Suite as shown below.

    Create Unit Test Suite

    The New Unit Test Suite wizard opens.

  4. Select Create a New Unit Test Suite and click Next.

    Select Create Method

  5. Specify a name for the unit test suite. Then, select the artifact file that you want to test from the file list and click Next.

    Note

    You can only select one sequence, proxy service, or API artifact per unit test suite.

    Fill Unit Test Suite Details

  6. Select the supporting artifacts from the list as shown below and click Next.

    Select Supportive Artifacts

  7. You can use a mock service to simulate the actual endpoint. If you have an already created Mock Service, select the mock service files from the list as shown below. You can also create a new Mock Service for this purpose.

    Select Mock Services

  8. Click Finish.

Update the Unit Test Suite

Once you have created a Unit Test Suite in WSO2 Integration Studio, you can find it inside the test folder. You can update the Unit Test Suite by adding test cases and changing the supporting artifacts and mock-services.

  1. Open Unit Test Suite from the project explorer. You can use either the design view or the source view to update the unit test suite.

    Unit Test Form

  2. In design view, click the '+' button under the Test Artifact, Test Cases and Assertion Details section to add a new test case to the unit test suite.

    Add Test Case

  3. Enter the following information:

    1. Enter a name for the test case.
    2. Update the Input Payload and Properties section:

      • Input Payload: The input payload of the test case. This can be JSON, XML, or plain text.
      • Input properties: The input properties of the test case. There are three types of properties allowed in unit testing: Synapse(ctx), Axis2(axis2), and Transport($trp) properties.

      For sequences, the test suite allows to add all type of properties with the value. For APIs and proxy services, you are only allowed to add transport properties.

      Note

      For APIs, you also need to specify the Request Path and Request Method in the this section. The Request Path indicates the URL mapping of the API resource. If the URL mapping consists some parameter(s), replace those with values. Also the Request Method indicates the REST method of the resource.

    3. In the Assertions section, you can add multiple assertion belonging to two types: AssertEquals check the whether the mediated result and expected values are equeal. AssertNotNull checks whether the mediated result is not null.

      Add Assertions

      • Assertion Type: Type of the assertion.
      • Actual Expression: Expression that you want to assert.

        • $body: assert the payload
        • $ctx:"": assert synapse property
        • $axis2:"": assert axis2 property
        • $trp:"": assert transport property
      • Expected Value: Expected value for the actual expression. Type can be a JSON, XML or a plain text.

      • Error Message: Error message to print when the assertion is failed.
        1. Once you have added at least one assertion, click Add.
      • Save the unit test suite.
Run Unit Test Suites

You can run the created Unit Test Suites using the unit testing server that is included in the embedded Micro Integrator of WSO2 Integration Studio. Right-click the test directory and click Run Unit Test to run all the unit test suites at once, or right-click the particular unit test suite and click Run Unit Test to run a selected unit test suite.

Run Unit Test Suite

The Unit Test Run Configuration wizard opens. Select one of server run configuration method you want to proceed with Unit Test.

Run Configuration

  1. Local Server Configuration: Run the Unit Test Suite(s) in embedded unit testing Server in Micro Integrator or local unit testing server.

    • Executable Path: Path to the unit testing server.
    • Server Test Port: Port of the unit testing server.
  2. Remote Server Configuration: Run the Unit Test Suite(s) in remote unit testing server.

    • Server Remote Host: Host IP of the remote unit testing server.
    • Server Test Port: Port of the remote unit testing server.
  3. Click Run to start the unit test. It will start the unit testing server in the console and prints the summary report for the given unit test suite(s) using the response from the unit testing server.

    Output Console

Create Mock Service

Mock services give the opportunity to simulate the actual endpoint.

  1. Open an existing project that has your integration solution.
  2. Right-click the test folder parallel to the src folder, and go to New -> Mock Service as shown below.

    Create Mock Service

  3. Select Create a New Mock Service and click Next.

    Select Create Mock Service Method

  4. In the Create a new Mock Service page, enter the following details:

    Mock Service Details

    • Name of the Mock Service: A name for the mock service.
    • Mocking Endpoint Name: Endpoint name which wants to mock.
    • Mock Service Port: Port for the mock service.
    • Mock Service Context: Main context for the service starts with '/'.
  5. Add multiple resources for the mock service as needed. To add multiple resources click the '+' icon on top of the resources table.

    • Service Sub Context: Sub context of the resource starts with '/'.
    • Service Method: REST method type of the resource.
  6. Fill the Expected Request to the Mock Service Resource section if you want to mock an endpoint based on the coming request headers or payload.

    Mock Service Resource Request Details

    • Header Name: Expected request header name.
    • Header Value: Expected request header value.
    • Expected Request Payload: Expected request payload to the service.

    Note: Entered request headers/payload must me matched with the request to send the response a this mock service.

  7. Fill the Response Send Out from the Mock Service Resource section to get a response from the service.

    Mock Service Resource Response Details

    • Response Status Code: Response status code of the mock service.
    • Header Name: Response request header name.
    • Header Value: Response request header value.
    • Send Out Response Payload: Expected response payload from the service.

Once you have entered the required details, click Add. It will list the resource under the Add Service Resource table with Sub Context and Method. After that click Finish to create a Mock Service. It will locate under the test → resources → mock-services directory.

Mock Service Form

Deploying ESB artifacts 

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

Using the Micro Integrator 

To deploy the packaged artifacts in the ESB profile:

  1. Right-click the composite application project and click Export Project Artifacts and Run.

  2. In the dialog that opens, select the artifacts form the composite application project that you want to deploy.

  3. Click Finish. The artifacts will be deployed in the Micro Integrator and the server will start. See the startup log in the Console tab:

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.

  1. Open the Getting Started view and click Miscellaneous →Add New Server to open the New Server dialog. 


  2. In the New Server dialog that opens, expand the WSO2 folder and select the version of your server.
  3. Click Next. In the CARBON_HOME field, provide the path to your product's home directory and then click Next again.
  4. 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.

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

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

  7. As the server starts, the Console tab appears. Note messages indicating that the composite app was successfully deployed.

  8. 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:

  1. 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.
  2. 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”}.
  3. 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.
       
  4. 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.

  5. Access your organization on Integration Cloud as you did in step 3. The HelloWorldAppsComposite Application you deployed is displayed as follows.
  6. 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
  1. Open the Getting Started view and click BP Project → Create New BPMN Project.

  2. In the Create an Activiti Project dialog, enter a name for the project and click Next.
  3. In the next step, select any referenced projects and click  Finish .  
  4. 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.

  5. When you click  Finish , the project will be listed in the project explorer (Activity explorer).

 2. Creating BPMN artifacts
  1. Right-click your BPMN project and go to New → Other
  2. Select BPMN Diagram and click Next.
  3. Select the diagrams folder in your BPMN project, give a file name for your diagram and click Next.

  4. Select a template diagram or choose to create an empty diagram and click Finish
  5. 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
  1. Open the Getting Started view and click BP Project → Create New BPEL Workflow.

  2. In the New BPEL Project dialog that opens, select Create New BPEL Workflow and click Next

  3. Enter the project name, process name, process namespace, and template accordingly, and click  Finish

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

  5. 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
  1. Open the Getting Started view and click BP Project → Create New Human Task as shown below.

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


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

  1. Select Window -> Show View -> Other in the top menu of your screen.
  2. Search for Package Explorer and click Open.
  3. In the Package Explorer, right-click the BPMN project and click Create deployment artifacts.
  4. 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.

  1. 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 a terminal and execute the following command:

    wso2ei-6.5.0-business-process

    Go to  Start Menu -> Programs -> WSO2 -> Enterprise Integrator 6.5.0 Business Process. This will open a terminal and start the business process profile.

  2. Open the management console from  https://localhost:9445/carbon/ .
  3. Log in by using admin as the username and password.
  4. 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.

  1. Select one of the projects (BPEL or Human Task) from the Project Explorer.
  2. Right-click the project and select Export Project as a Deployable Archive.
  3. 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:

  1. 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 a terminal and execute the following command:

    wso2ei-6.5.0-business-process

    Go to  Start Menu -> Programs -> WSO2 -> Enterprise Integrator 6.5.0 Business Process. This will open a terminal and start the business process profile.

  2. Open the management console from  https://localhost:9445/carbon/ .
  3. Log in by using admin as the username and password.
  4. 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.
  • No labels