Service Integration - DigiBP/digibp.github.io GitHub Wiki

This hands-on contains two usecases for the service integration that can be realized with Camunda. Each usecase starts with the creation and test of the API requests with the help of Postman.

This guide relies on the previous configured settings, such as the Camunda Modeler and a running instantiation of the digibp-camunda-template on Heroku.

• Pre-requisite - Postman
• 1. Get Pizza Menu Service
  • Create and Test the HTTP GET request with Postman
  • Create the "Get Pizza Menu Process Model"
  • Step 1: HTTP Connector
  • Step 2: Input Parameter
  • Step 3: Output Parameters
  • Step 4: Show Menu
  • Step 5: Deployment
• OPTIONAL: Get Pizza Menu Endpoint on PutsReq
• 2. Add Pizza Service
  • Create and Test the HTTP POST request with Postman
  • Create the "Add Pizza Process Model"
  • Step 1: Form Field
  • Step 2: HTTP Connector
  • Step 3: Input Parameter
  • Step 4: Output Parameters
  • Step 5: Show Pizza Menu
  • Step 6: Deployment
• OPTIONAL: Add Pizza Endpoint on PutsReq
• References / Links

Please install Postman before running this tutorial.

It is strongly recommended, to engineer and test a REST API service integration prior integrating it into an executable process or case model. Therefore, this guide is going to illustrate how the engineering and testing can be done using the API development environment Postman.

In this usecase we model a simple process that will display the menu of Mario's Pizzeria.

First we are going to create and test an HTTP GET request using Postman.

1. Open Postman (see the figure below).

2. Select Method: GET. Next, copy the URL endpoint: https://putsreq.com/0T83h2p0LDp0dxrKiYHH and paste it in the Enter request URL (next to the POST method).

3. Click on the Send button to test the GET request.

In case of successful response, the following message will be returned:

• Code: 200 OK • Sample Body:

{
    "PizzaMenu": "Margherita, Prosciutto e Funghi, Capricciosa, Boscaiola, Quattro Stagioni, Quattro Formaggi, Bufala"
}

All the available Pizza from the Menu will appear in the form of a Json object at the bottom of Postman (see the following figure).

In case of unsuccessful response, the following message will be returned:

• Code: 404 UNAUTHORIZED

Now that the HTTP GET request works, we are ready to implement the service integration using the Camunda Modeller.

Open the Camunda Modeller and create the process model as follows:

Select "Get menu" and select "Connector" from the General tab in the panel properties (see right-hand side of the figure below).

Select Connector tab and add GET method as input parameter (see in the figure below).

Add the URL input parameter (see bottom-right corner of the figure below). The URL refers to the endpoint created in PutsReq: https://putsreq.com/0T83h2p0LDp0dxrKiYHH

Add the output parameter "pizzaList". This output paramenter needs to be transformed into a Json object, which is done by the script (see bottom-right corner of the figure below).

Select "Show Menu" and add the form field "pizzaList". This form field will be populated with the available pizza from the Menu once the process runs.

Now we are ready to deploy the process and test if it works as expected. For that, we are going to use the FHNW DigiBP classroom instantiation.

• Enter deployment name and your Tenant ID.
• Enter the deployment endpoint (copy&paste): https://digibp.herokuapp.com/engine-rest/deployment/create
• Go to the DigiBP classroom instantiation welcome and landing page: https://digibp.herokuapp.com
• If it works, you can yell!!! Else, go back to step 1.

This is optional: Just in case the predefined endpoint is not working or may want to create an own instantiation.

You may create an own version of the Get Pizza Menu-Endpoint on PutsReq using the following script:

var msgPizza = '';

msgPizza = 'Margherita, Prosciutto e Funghi, Capricciosa, Boscaiola, Quattro Stagioni, Quattro Formaggi, Bufala';

// Build a response
response.body = {
    'PizzaMenu':msgPizza
    };

In this usecase a new pizza can be added to the menu of Mario's Pizzeria.

First we are going to create and test an HTTP POST request using Postman.

1. Open Postman (see the figure below).

2. Select Method: POST. Next, copy the URL endpoint: https://putsreq.com/etxiYnqeITnDenpHHdT1 and paste it in the Enter request URL (next to the POST method).

3. Fill in the Headers with

• KEY: Content-Type
• VALUE: application/json

4. Click on the "Body" tab and paste the following Json object in the dedicated section (see the figure below).

{
    "name": "Napoletana"
}

5. Click on the Send button to test the POST call

In case of successful response, the following message will be returned:

• Code: 200 OK • Sample Body:

{
    "PizzaMenu": "Margherita, Prosciutto e Funghi, Capricciosa, Boscaiola, Quattro Stagioni, Quattro Formaggi, Bufala, Napoletana"
}

Notice that pizza Napoletana has been added to the list of pizza.

Congrats!!! You made it!!! Proceed to Create Add Pizza Process Model.

In case of unsuccessful response, the following message will be returned:

• Code: 404 UNAUTHORIZED

Try again. You can make it!!!

Now that the HTTP POST request works, we are ready to implement the service integration using the Camunda Modeller.

Open the Camunda Modeller and create the process model as follows:

Select the start event and create a new form field name (see the following figure).

Select Add Pizza task and select Connector from the General tab in the panel properties (see right-hand side of the figure below).

Select Add Pizza task and add the method POST as input parameter (see the following figure).

Add headers as input parameter (see the following figure).

Add payload as input parameter (see the following figure).

Add url as input parameter (see the following figure).

Add the output parameter "pizzaList". This output paramenter needs to be transformed into a Json object, which is done by the script (see bottom-right corner of the figure below).

Select "Show Pizza Menu" and add the form field "pizzaList". This form field will be populated with the available pizza from the Menu once the process runs.

Now we are ready to deploy the process and test if it works as expected. For that, we are going to use the FHNW DigiBP classroom instantiation.

• Enter deployment name and your Tenant ID.
• Enter the deployment endpoint (copy&paste): https://digibp.herokuapp.com/engine-rest/deployment/create
• Go to the DigiBP classroom instantiation welcome and landing page: https://digibp.herokuapp.com
• If it works, you can yell and dance!!! Else, go back to step 1.

This is optional: Just in case the predefined endpoint is not working or may want to create an own instantiation.

You may create an own version of the Add Pizza-Endpoint on PutsReq using the following script:

const parsedBody = JSON.parse(request.body);
var msgPizza = "Margherita, Prosciutto e Funghi, Capricciosa, Boscaiola, Quattro Stagioni, Quattro Formaggi, Bufala";

// Build a response
if (parsedBody.name) {
    response.status = 200;
    
    response.headers['Content-Type'] = 'application/json';
    response.body = {
        "PizzaMenu": msgPizza + ", " + parsedBody.name
    };
    
} else {
    response.status = 404;
    response.headers = {};
    response.body = 'not found';
}

¹ API Debugging and Testing

• https://www.getpostman.com/tools#debug
• https://blog.getpostman.com/2014/03/07/writing-automated-tests-for-apis-using-postman