SAP: Integration Flows with Open Connectors on BTP Integration Suite

→ Before designing any integration flow, create an integration package first and, within this integration package, create an integration flow.

Looking at the menu on the left, if something is missing istead to this picture, please check the assigned capabilities and roles.

→ Create a set of credential so that the Integration Flow will be able to access the Open Connector.

• To do this, go to Monitor - Integration and APIs:

• On the landing page, click on Security Material in the Manage Security section:

→ The next page shows the list of all the credentials created. Click on Create on the top right and then on User Credentials in the dropdown menu.

→ In the pop up box, select OpenConnectors in the Type dropdown menu:

→ Fill in the mandatory data:

User, Organization and Element must be retrieved from the Open Connector instance which should be used in the Integration Flow (Check the point create instance in the Cloud Fax/SMS/Email Connector on BTP tutorials).

Remember to get the Open Connector endpoint too (it looks like this, even though it may differ a bit: https://api.openconnectors.eu10.ext.hana.ondemand.com/elements/api-v2).

A different set of credentials for every Open Connector Instance (even within the same kind of connector) as the Element changes every time.

Once all the fields have been filled, click on Deploy and the new set of credentials will be displayed in the list mentioned in the previous step.

Now, the Integration Flow can be created by building an integration package. Every integration package may contain multiple Integration Flows.

→ Go to Design - Integration and APIs:

 The list of Integration Packages will show up (It is empty when the first integratio flow is generated):

→ Select Create on the top right corner to create a new Integration package.

→ Fill in the mandatory field in the Header tab:

→ Click on Save in the top right corner and then on the Artifact tab.

→ Click on Add and select Integration Flow from the dropdown menu:

→ Fill in the required data and a description that may help in understanding what this flow does:

→ Once you filled the form, select the Add button.

The Integration Flow has been created and it is added to the list of Artifacts of the actual integration package:

→ To edit, just click on anywhere on the line in the list.

The basic structure that has already been created is shown:

As a first step, connect the Sender to the Start of the Integration Flow. To do so, click on the arrow (Connectors) featured in the top menu bar. 

By moving the mouse close to the Sender, a frame with connecting points will appear.

Click on the point of the right side or the one in the middle and draw a line until a similar connecting point at the center of the Start circle is reached.

Once the two elements have been connected, a pop up window will show up. Select HTTPS for the connection type.

It is now necessary to set up the connection. Click on this icon at the bottom right corner:

This will show up the property setup window, which will be used from now on to define all the parameters needed by the flow.

Different properties will be displayed in this window depending on the element selected on the graphical editor. Click anywhere in a blank space, the general flow properties will be displayed.

Click on the connecting arrow HTTPS  to see its properties, then select the Connection tab:

Deselect CSRF Protected.

The Address depends on the type of Retarus service to be posted.

• Fax-for-Applications
  /{yourCustomerNumber}/fax //Example: /12345/fax

• Transactional Email
  /rest/v2/jobs

• SMS-for-Applications
  /rest/v1/jobs

Now, when a message is received over HTTPS from the Integration Flow endpoint, the automation designed in the flow will be triggered for execution.

The next step is to add an element capable of sending back to the sender the answer received by the called Retarus service (i.e. a message with the job ID).

From the top menu, select Call => External Call => Request Reply:

Then, hover the mouse pointer to the arrow connecting Start and End:

Click on it to add the Request Reply element:

Request Reply must now be connected to the Receiver.

Drag the Receiver element underneath Request Reply then click on this one to make its context menu appear and use the Connector Icon (the arrow) to draw a connection between Request Reply and Receiver (keep clicked and drag to the Receiver):

Once the Receiver has been connected, a pop-up window appears in which the Adapter Type can be selected. 

Scroll down until OpenConnectors and select it:

Now, look at the properties window and select the Connection tab:

Change Method to POST.

Push the Select button near the Credential Name field.

Select the set of credentials for the Open Connector to call:

Enter the Base URI of the Open Connector endpoint in the proper field.

The Base URI you get from the Open Connector instance is something like "https://api.openconnectors.../elements/api-v2/{part depending on the service}". Here you have to enter everything from "https" to "api-v2". What follows "api-v2" must not be entered here.

Click now on the Select button near the Resources field to open a pop up window. Here select the proper resource from the Open Connector to POST the job.

Of course, depending on the called Open Connector, this list may completely change. Here is an example:

The Resources to choose depending on the service are:

• Fax-for-Applications
  /{cuNo}/fax
//Note: you can leave {cuNo} but it requires a dynamical replacement of the customer number at runtime, which is an advanced feature beyond the scope of this tutorial. If you don't know how to do
//it, replace it with the chosen customer number to get something like /12345/fax

• Transactional Email
  /rest/v2/jobs

• SMS-for-Applications
  /rest/v1/jobs

Once the Resource has been correctly selected, click on Save in the upper right corner and all the eventual errors that may still be highlighted should disappear (if everything is correct).

The Integration Flow is now completed and can be deployed, so click on Deploy, again in the top right corner of the editing area.

Click anywhere in a blank area of the design window, the properties window will show the general properties of the Integration Flow. Select the Deployment Stats tab to check when the deployment is finished and if it has been completed without errors:

Click on Navigate to Manage Integration Content to move to the page where you can find the endpoint to call this Integration Flow to send your jobs. for instance:

The part after "/http/" changes depending on the specified Resource.

To access this endpoint you will need to use a basic authentication method. The username and the password to log in are the Client Id and the Client Secret you have to get from the set of credentials associated to the Integration Flow Runtime instance of your sub-account. Check this tutorial for reference about how to create or find the credentials: SAP BTP - Creating Credentials for Services.

As a first step connect the Sender to the Start of the Integration Flow. To do so, click on the arrow (Connectors) featured in the top menu bar. 

Move the mouse pointer close to the Sender, a frame with connecting points will appear. Click on the point of the right side or the one in the middle and draw a line the similar connecting point at the center of the Start circle.

Once the two elements have been connected, a pop up window will show up. Select HTTPS for the connection type.

Now the created connector must be setup. Click on this icon at the bottom right corner:

This will show up the property setup window that will be used from now on to define all the parameters needed to the flow.

Different properties will be displayed in this window depending on the element selected on the graphical editor. Click anywhere in a blank space, the general flow properties will be displayed.

Click on the connecting arrow HTTPS  to see its properties, then select the Connection tab:

Deselect CSRF Protected.

The Address to be entered, instead, depends on the type of Retarus Service need to be posted:

• Fax-for-Applications
  /{yourCustomerNumber}/fax/reports //Example: /12345/fax/reports

• SMS-for-Applications
  /rest/v1/reports

Now, when a message is received over HTTPS from the Integration Flow endpoint, the automation designed in the flow will be triggered for execution.

To retrieve the report about a specific Job, we need the Job ID. The Job ID will be provided as a parameter in the GET request (we'll see later how to setup the request).

The Job ID can be obtained from the GET request by using a script so, 

To enter a script, click on the Message Transformation icon in the top menu and then select Script => Groovy Script:

Click now on the arrow connecting Start and End to set the block for entering the script:

To create a new script for this block, click on the Create icon in the context menu:

The script editor will open with a default code already prepared like this:

Delete everything and replace it with the following code:

/* Refer the link below to learn more about the use cases of script.
https://help.sap.com/viewer/368c481cd6954bdfa5d0435479fd4eaf/Cloud/it-IT/148851bf8192412cba1f9d2c17f4bd25.html
 
If you want to know more about the SCRIPT APIs, refer the link below
https://help.sap.com/doc/a56f52e1a58e4e2bac7f7adbf45b2e26/Cloud/it-IT/index.html */
import com.sap.gateway.ip.core.customdev.util.Message;
import java.nio.charset.Charset;
 
def Message extractUrlGetParameters(Message message) {
     
    String httpQuery = message.getHeader('CamelHttpQuery', String);
     
    if(httpQuery) {
        Map<String, String> queryParameters = URLDecoder.decode(httpQuery, Charset.defaultCharset().name())
        .replace("\$","")
            .tokenize('&')
            .collectEntries { it.tokenize('=')};
         
        message.setProperties(queryParameters);
    }
     
    return message;
}

The next step is to add an element capable of sending back to the sender the answer received by the called Retarus service (i.e. a message with the job ID).

From the top menu, select Call => External Call => Request Reply:

Click on the arrow following the Script block to add the Request Reply one:

Request Reply must now be connected to the Receiver.

Drag the Receiver element underneath Request Reply, then click on this one to make its context menu appear, and use the Connector Icon (the arrow) to draw a connection between Request Reply and Receiver (keep clicked and drag to the Receiver):

After connecting the Receiver, a pop-up window will show up to choose the Adapter Type.

Scroll down until OpenConnectors and select it:

Now, look at the properties window and select the Connection tab:

Push the Select button near the Credential Name field and select the set of credentials for the Open Connector to call, for instance:

Enter the Base URI of the Open Connector endpoint in the proper field.

The Base URI from the Open Connector instance is something like "https://api.openconnectors.../elements/api-v2/{part depending on the service}". Enter everything from "https" to "api-v2". What follows "api-v2" must not be entered here.

To GET the Report from the Retarus service we are going to call, we need to use the jobID we got from the script we have created before.

To do so, we cannot use the Resources supplied by the Open Connectors but we need to modify them a little bit. 

Depending on the service, then, in the Resource field we have to enter:

• Fax-for-Applications
  /{cuNo}/fax/reports/${property.jobId}
//replace {cuNo} with the your Customer Number, like 12345 => for instance: /12345/fax/reports/${property.jobId}

• SMS-for-Applications
  /rest/v1/jobs/${property.jobId}

Once the Resource has been correctly selected, click on Save in the upper right corner and all the eventual errors that may still be highlighted should disappear (if everything is correct).

The Integration Flow is now completed and can be deployed, so click on Deploy, again in the top right corner of the editing area.

Click anywhere in a blank area of the design window, the properties window will show the general properties of the Integration Flow. Select the Deployment Stats tab to check when the deployment is finished and if it has been completed without errors:

Click on Navigate to Manage Integration Content to move to the page the endpoint can be found to call this Integration Flow to send the jobs.

The part after "/http/" changes depending on the specified Resource.

To access this endpoint, you will need to use a basic authentication method. The username and the password to log in are the Client Id and the Client Secret you have to get from the set of credentials associated to the Integration Flow Runtime instance of your sub-account. Check this tutorial for reference about how to create or find the credentials: SAP BTP - Creating Credentials for Services.

 To test the integration flow we have just created, it is possible to use Postman.

Create a GET request in Postman specifying the above URL and adding jobId and its value as a parameter of the request.

For Fax:

For SMS:

The name of the parameter used to pass the Job ID must be the same as the one defined in the integration flow, including capitals, as it is case sensitive.