Skip to Content

Call an External Endpoint to Retrieve Additional Information

test
0 %
Call an External Endpoint to Retrieve Additional Information
Details

Call an External Endpoint to Retrieve Additional Information

2019-12-17
Call an endpoint from an external system to retrieve additional information to use in your processing.

You will learn

  • How to expose an SOAP endpoint and how to call it from another flows.
  • Different ways of calling external endpoints.
  • Difference between Request-Reply and Content Enricher.

Prerequisites

  • You have created a basic flow using the first tutorial.

Instead of using an external API, we shall use an API exposed on your tenant. To expose the API, we shall create an additional flow. We will expose an SOAP endpoint through this integration flow and then consume it in the basic flow that was created in the previous chapter.

Feel free to replace the same with any externally available API.


Step 1: Create flow to expose SOAP endpoint
  1. Go to the package SAP Cloud Platform Integration Tutorials.

  2. Add an integration flow to this package.

    • Go to the Artifacts tab.
    • Click Edit.
    • In the Add dropdown, choose Integration Flow.
    Create Integration Flow
  3. Choose Create.

    Field Name Value
    Name Find Closest Warehouse Code
    Short Description Takes the address of the customer and returns the code of the closest warehouse.

    Keep the rest of the settings as it is.

    Enter Integration Flow details
  4. Click OK.

    An integration flow is now created and added to the Integration package.

    Click on the name to launch the integration flow editor.

    The system creates a skeleton flow for you by default.

    Skeleton Integration Flow created
  5. Click Edit to start adding logic to your integration flow.

    The design palette appears on the left side that provides all the process steps that can be added to the integration flow.

  6. Delete the receiver - click on the receiver and choose delete from the speed button.

    Delete Receiver
  7. Create the sender channel:

    • Click on the Sender system.
    • Click on the Connector speed button.
    Sender connector
    • Drag the arrow to the Start message event.
    • Choose SOAP from the Adapter Type pop-up and in the following window, choose SOAP 1.x.
    Sender connector choose
  8. Configure the SOAP sender to expose an SOAP endpoint:

    • Click on the SOAP sender channel.
    • Go to the Properties sheet.
    • Go to the Connection tab and configure the following settings:
    Field Value
    Address /getWarehouseCode
    Service Definition Manual
    Use WS-Addressing Not checked
    Message Exchange Pattern Request-Reply
    Authorization User Role
    User Role ESBMessaging.send

    This is the SOAP endpoint that we will use as an external API and shall call it from the basic flow.

    Sender connector configure
  9. Retrieve the OrderID from the incoming message and store it into a header:

    • Click on the design Palette.
    • Choose Message Transformers.
    • Choose Content Modifier.
    Choose Content Modifier
    • Drag it on to the execution pipeline after the Message Start Event step.

      Add Content Modifier
    • Click on the Content Modifier step, go to the properties sheet, Header tab and add the following details:

    Field Value
    Action Create
    Name orderID
    Type XPath
    Data Type java.lang.String
    Value /orders/order/orderID
    Configure Content Modifier Header

    You can add ${in/body} in the Message Body if the system does not pick the value of the orderID.

  10. Add a Filter step to retrieve the address field from the incoming message:

    • Click on the design Palette.
    • Choose Message Transformers.
    • Choose Filter.
    Choose Filter
    • Drag it on to the execution pipeline after the Content Modifier.
    Add Filter
    • Click on the Filter step, go to the properties sheet, General tab and rename the step to Retrieve Address.
    Filter Rename
    • Click on the Filter step, go to the properties sheet, Processing tab and configure the following:
    Field Value
    XPath Expression //orders/order/Address/text()
    Value Type Node
    Filter Configure

    Now the message in the pipeline is only the text of the address field of the incoming message. All other message content get discarded.

  11. Add a script step to compute the warehouse code from the recipient’s address-

    • Click on the design Palette.
    • Choose Message Transformers.
    • Choose Script.
    • Choose Groovy Script.
    Groovy Script
    • Drag it on to the execution pipeline after the Filter step.
    Drag Groovy Script
    • Click on the Script step, go to the properties sheet, General tab and rename the step to Compute Warehouse Code.

      Rename Script
    • Click on the Script step and choose Create (+) from the list of speed buttons.

      Add script code
    • Add the following code to the script’s processData method:

    def Message processData(Message message)
    {
     def body = message.getBody();
     String s = message.getBody(String.class);
     String[] str;
     String code = "KWA";
     str = s.split(',');
     for( String values : str )
     code = code + values.substring(0,1);
     message.setBody(code);
     return message;
    }
    

    In this script, we are picking the first letter of each address field and concatenating it to create a warehouse code. Feel free to change the code as you prefer.

    • Click Ok.
  12. Create an XML body using a Content Modifier:

    • Click on the design Palette.
    • Choose Message Transformers.
    • Choose Content Modifier.

    Choose Content Modifier

    • Drag it on to the execution pipeline after the Script step.

    Add Content Modifier

    • Click on the Content Modifier step, go to the properties sheet, Message Body tab and add the following details:
      Field Value
      Type Expression
      Body <?xml version="1.0" encoding="utf-8"?> <order><code>${in.body}</code><orderID>${headers.OrderID}</orderID></order>
      Configure Content Modifier Body
  13. Save, deploy and retrieve the endpoint:

    • Save the integration flow by clicking on Save.

    Alternatively, you can use Save as version to change the version of the integration flow. Versions are managed by the Web Interface which also allows you to rollback to saved versions.

    The system performs configuration check of all the integration flow settings that you configured so far and lists them in the Problems View. Errors and warnings are displayed.

    • Deploy the integration flow by clicking on Deploy.

      Flow save
      • Click Yes in the Confirmation dialog.

      • Click Ok in the Deployment pop-up.

    • Click on Monitor to open the Monitoring View and choose the first tile from the Manage Integration Content section.

    View deployed artifacts
    • Look for your integration flow. Make sure it is in Started state.

    • You can find the endpoints on the right hand pane.

    Bundled deployed and started
Log on to answer question
Step 2: Create a credential to call the above flow

In order to call the above flow from the basic flow, you need a user who has ESBMessaging.send. This is what was configured in the SOAP channel.

Assign ESBMessaging.send to a user and then add the corresponding user as a credential in the tenant:

A User Credential is an artifact created in the secure store of SAP Cloud Platform Integration to securely store user/passwords. The credential artifact is always stored as encrypted and hence keeps the password safe.

  1. Create and deploy a credential for sending mail on behalf of a mail account.
    • Go to the Monitor view.
    • Click on Security Material.
    • Add User Credential.
    • Set Name to user.
    • Configure the tenant user’s name and passwords.
    Sender mail credentialClick Deploy.
Log on to answer question
Step 3: Call the exposed endpoint from the basic flow
  1. Open the basic flow Manage Freight Logistics.
  2. Click on Edit to start editing the flow.
  3. Add a RequestReply step to the message pipeline:
    • Click on the design palette.
    • Choose Call.
    • Choose External Call.
    • Click on Request Reply.
    Choose RequestReply
    • Drop it on to the message pipeline after the Message Start Event.
    Add Request Reply
  4. Add a receiver to the canvas:

    • Click on the design palette.
    • Choose Participants.
    • Choose Receiver.
    Choose receiver
    • Drag the receiver on the canvas as shown below.
    Add receiver
    • Rename the receiver ExternalAPI.
    • Click on RequestReply and drag the connector to the Receiver.
    • Choose the SOAP connector because we exposed an SOAP endpoint in the flow creates in step 1.
    Connect Receiver
  5. Configure the external API in the SOAP connector.

    • Choose the SOAP connector.
    • Go to the Properties Sheet.
    • Go to the Connections tab.
    Field Value
    Address SOAP endpoint URL of the flow created in Step 1
    Authentication Basic
    Credential Name user
    Configure SOAP
  6. Save, deploy and execute the flow.

  7. Check the mail received:

    You should have received the following mail:
    RR Mail

  8. As you may have noticed, the result if the external API call overwrote the message in the pipeline.

    In case you wanted to preserve the input message and add the result of the API call to it, you must you a Content Enricher instead. This is covered in the next step.

Log on to answer question
Step 4: Replace the Request Reply step with a Content Enricher
  1. Delete the request reply step.

    Delete Request Reply
  2. Add a Content Enricher step to the message pipeline (in place of the Request Reply):

    • Click on the design palette.
    • Choose Call.
    • Choose External Call.
    • Click on Content Enricher.
    Choose Content Enricher
    • Drop it on to the message pipeline after the Message Start Event.
    Add Content Enricher
  3. Configure the Content Enricher:

    • Choose the Content Enricher.
    • Go to the Properties Sheet.
    • Go to the Processing tab.
    Field Value
    Address SOAP endpoint URL of the flow created in Step 1
    Method POST
    Authentication Basic
    Credential Name User
  4. Add SOAP connector:

    • Click on Receiver and drag the connector to the Content Enricher.
    • Choose the SOAP connector because we exposed an SOAP endpoint in the flow creates in step 1.
    Connect Content Enricher
  5. Configure the external API in the SOAP connector.

    • Choose the SOAP connector.
    • Go to the Properties Sheet.
    • Go to the Connections tab.
    Field Value
    Address SOAP endpoint URL of the flow created in Step 1
    Method POST
    Authentication Basic
    Credential Name User
    Configure SOAP
  6. Save, deploy and execute the flow.

  7. Check the mail received:

    You should have received the following mail:

    Content Enricher Mail

    As you can see, a new order element is added under the parent Order node and it contains the code element.

Which external call interleaves data on the pipeline with the results of the external API call in SAP Cloud Platform Integration?
×

Next Steps

Back to top