Using Adapters

Objective

After completing this lesson, you will be able to Use adapters.

Adapters

In this Lesson, the Following Topics are Discussed:

  • Adapter in an overview.
  • Sample OData receiver adapter.

Adapter in an overview

A wide variety of pre-built adapters are available, with a differentiation made between input (transmitter) and output (receiver) adapters. These adapters support various application and transport protocols, as well as message protocols, and are configured based on their intended function. Adapters can be broadly categorized into two groups:

  • TCP based.
  • Non TCP based.

Often these adapters are also simplified called: HTTP based and non HTTP based.

Example: OData Adapter

Example: Details of an OData Adapter

DetailOutcome
CategoryHTTP based
Transport protocolTCP/IP
Application protocolHTTP/HTTPS
Message protocolAtom Pub as XML or JSON representation

Overview of Available Adapters

You have the option to visit the help page or view the available adapters on an integration fow, based on your license, as demonstrated earlier with connectivity.

Read more here: Configure Adapter in Communication Channels

Custom Adapter

In case the current adapters do not meet your requirements, it is possible to import adapters from third-party sources.

Read more here: Importing Custom Integration Adapter in the Cloud Foundry Environment

Develop your own adapter

In case none of the aforementioned sources are helpful in finding the desired adapter, you can also create your own adapter.

Read more here: Developing Custom Adapters

Difference to the adapters in process integration

Within PI, every incoming message format is automatically transformed into the internal XI message protocol. Unlike cloud integration, there is no native format available. Essentially, this implies that if a binary format is used to send a message, it will be forwarded as such to the next integration flow component without any modifications. That's where converters come into play. Utilizing the XML Message format enables me to receive excellent support (XPATH) in individual integration flow components.

Sample OData Receiver Adapter

The OData adapter is utilized in the exercises. What sets the OData adapter apart, and why is it specifically selected for use in the exercise?

The Query Wizard

The OData Sender Adapter features a wizard that allows users to navigate to the interface to be accessed through the use of a metadata document. This approach makes it possible to configure the adapter even if the interface details are not fully known. However, this procedure is restricted to OData V2.0 and is only appropriate for a small hierarchy structure.

The Page Processing Mode

OData interfaces transmit data in the form of a feed utilizing the Atom Pub protocol, with namespaces and their respective prefixes used for added clarity.

In some cases, the number of entries in the feed can be quite substantial, potentially resulting in technical issues due to message size limitations. To overcome this challenge, paging processing is employed. This allows for the reading of the total quantity of entries in packages or pages, which are then processed sequentially. Nevertheless, this procedure requires an additional design decision.

Sample with Page Processing Mode

No Page Processing

The Scenario has at No. 1, a looping Process Call. At No. 2, the OData Adapter calls a OData API.

The Result is:

With Page Processing

Similar to the previous scenario, the OData configuration is situated below. In this instance, each call is expected to deliver only 5 items.

The Result is:

Automatically Removing of the Name Spaces of the Response

Apart from the option to gather data in packages, the name spaces and their prefixes are also automatically eliminated. This enables the data to be processed directly with XPATH. During the practice session, the HTTP adapter is utilized for the other calls. However, it does not automatically remove the namespaces, necessitating additional mapping.

Read more here: Configure the OData Sender Adapter

Summary

SAP provides a range of adapters in cloud integration, which vary based on their direction (inbound or outbound) as well as the transport, application, and message protocols employed. Broadly speaking, these adapters can be classified as HTTP-based, TCP/IP-based, or non-HTTP/non-TCP/IP-based. For instance, the OData receiver adapter offers several unique features, such as a wizard that facilitates easy configuration of the OData API to be called and the capability for page processing to handle large data volumes. Additionally, the adapter removes namespaces and their respective prefixes from the response, which is another significant advantage.

Create a Request and Reply to an external Call (OData Adapter)

Business Scenario

Our objective is to validate the availability of productIDs against the order database to determine the subsequent processing route. This verification is performed through an OData protocol query.

The following overview image provides an understanding of the location where the new component operates.

Task Flow

In this exercise, you will perform the following tasks:

  1. Log on to the integration flow DelayedDelivery_Process.
  2. Create and configure an OData Adapter.
  3. Save as version, deploy, and debug your integration process.

Prerequisites

You have completed the final step of creating and configuring a Content Modifier.

Outcome After This Exercise

The first external API call has been implemented by you.

What Do You Learn Within This Exercise?

Learn to configure OData adapter within an external call to an API.

Exercise Options

To carry out this exercise, you can choose from the following options:

  1. Live Environment: Using the instructions provided below, you can perform the steps in your SAP BTP account.
  2. Platform Simulation: Follow the step-by-step instructions within the simulation.
  3. Side-by-side: Follow the step-by-step instructions within the simulation and perform the steps in your SAP BTP account simultaneously.

Note

We strongly recommend to perform the steps in the live environment.
ExerciseStart Exercise
ExerciseStart Exercise

Task 1: Log on to the Integration Flow DelayedDelivery_Process

Steps

  1. Log on to the integration flow DelayedDelivery_Process via Integration Suite.

    1. Navigate within the Integration Suite Welcome page to Design → Integrations → DelayedDelivery_Package_randomNumber → DelayedDelivery_Process.

    2. Check the status after the last exercise step:

    3. Imagine that the integration flow is more edited.

Task 2: Create and Configure an OData Adapter

Steps

  1. Set a Receiver.

    1. The creation of a receiver was part of the initial process, but it became obscured when the swim lane was enlarged.

    2. To make the receiver visible again, slide the entire swim lane downwards by selecting it until the edge becomes active, and then dragging it down.

    3. Move the receiver down.

    4. Name the receiver API_SalesOrder_ProductSet.

  2. Set an External Call.

    1. Choose from the palette Call → External Call → Request Reply after the Modify_setProductIDAsProperty step.

    2. Name it Call_checkProductID.

  3. Configure the OData Adapter.

    1. Drag the arrow downwards to the receiver API_SalesOrder_ProductSet from the context menu.

    2. Select OData → Data V2 as the adapter.

    3. If the configuration bar does not displays automatically, choose the connection line from Call_checkProductID to API_SalesOrder_ProductSet.

    4. Select the Connection tab on the configuration bar, and enter the following data:

      NameInput
      Address

      https://< your host from your API>/v1/GWSAMPLE_BASIC

      for example: https://group00-xxxxx-yyyyyy.prod.apimanagement.eu10.hana.ondemand.com/v1/GWSAMPLE_BASIC

      Proxy TypeInternet
      AuthenticationNone
      Reuse ConnectionLabeled

    5. Your API URL can be found in the API Management section.

    6. Navigate to the Processing tab. Here, you find an OData wizard, that assists in configuring the entities and queries.

    7. Choose the Select button.

    8. Accept the offered entries, and choose the Step 2 button.

    9. In this step, choose the magnifying glass next to the Select Entity field. Choose ProductSet.

    10. Select the fields of this entity that should be read. These include:

      • ProductID
      • Category
      • Name

    11. The selected data displays below as a query.

    12. Choose the Step 3 button.

    13. To ensure that the interface only receives a single result if the ProductID stored as an Exchange Property is found in the database, we must specify this as a condition.

    14. For no. 1, select the ProductID from the interface.

    15. For no. 2, select Equal from the list of conditions.

    16. For no. 3, enter by hand: ${property.ProductID}.

      The Simple Expression Language can be used to access the stored property.

    17. Choose Finish.

      The fields Operation Details, Resource Path and Query Options will be automatically set. Make sure to also copy over the content type and timeout.

Task 3: Save as Version, Deploy, and Debug your Integration Process

Steps

  1. Save as version, deploy, and debug your integration process.

    1. Perform the following steps.

      1. Save as version.
      2. Deploy.
      3. Jump to the Overview → Manage Integration Content.
      4. Set log level to trace.
      5. Deploy again.
      6. Jump again to the Overview > Manage Integration Content.

    2. Navigate to your Integration Flow Model in Overview → Monitor Message Processing → Message Processing Run.

    3. We see two API calls for every loop one.

    4. Go to the first End entry. Choose Message Content → Payload to see the response from the API.

    5. If a productID is stored in the database, the API call functions properly. However, we also need to verify whether the API call works when the ProductID is not stored in the database.

    6. Go back to your Integration Process and choose Edit.

    7. Choose the Modify_setPayload component, open the Message Body, and change the second ProductID to HT-xxxx.

    8. Save and deploy again. Check your trace. The result must be without any product entries.

    9. Don't revert the incorrect productID back, as we need to use it for the next step of the verification process.

  2. Learn more about the OData Adapter component.

    1. Return to your integration process.

    2. Open the configuration bar of the OData component and choose the question mark symbol.

    3. Here, you will find all the information about the different adapters and how they can be used in a familiar way.

Create and Configure a Router

Business Scenario

The processing steps to follow will be determined by the previous API call, and if the productID is not found in the database, the process must be ended.

The following overview image provides an understanding of the location where the new component operates.

Task Flow

In this exercise, you will perform the following tasks:

  1. Log on to the integration flow DelayedDelivery_Process.
  2. Create and configure a Router.
  3. Save as version, deploy, and debug your integration process.

Prerequisites

The creation of a Request and Reply an External call has been completed by you in the last step.

Outcome After This Exercise

A running Router who controls further processing.

What do you Learn Within This Exercise?

Get familiar on how to utilize and set up a Router that consists of two routes.

Exercise Options

To carry out this exercise, you can choose from the following options:

  1. Live Environment: Using the instructions provided below, you can perform the steps in your SAP BTP account.
  2. Platform Simulation: Follow the step-by-step instructions within the simulation.
  3. Side-by-side: Follow the step-by-step instructions within the simulation and perform the steps in your SAP BTP account simultaneously.

Note

We strongly recommend to perform the steps in the live environment.
ExerciseStart Exercise

Task 1: Log on to the Integration Flow DelayedDelivery_Process

Steps

  1. Log on to the integration flow DelayedDelivery_Process via Integration Suite.

    1. Navigate within the Integration Suite Welcome page to Design → Integrations → DelayedDelivery_Package_randomNumber → DelayedDelivery_Process.

    2. Follow the status after the last exercise step.

    3. Imagine that the integration flow is more edited.

Task 2: Create and Configure a Router

Steps

  1. Set a Router.

    1. Place a router component in a known way according to the Call_checkProductID, name it Router_ProductID.

  2. Create the following Condition:

    /ProductSet/count(Product)>0.

    1. Choose the name Route 1.

    2. Rename Route 1 to ProductID_Available at tab General.

    3. Switch to the Processing tab and unflag Default Route.

      The interface will change immediately.

    4. In the Condition field, enter /ProductSet/count(Product)>0. That means if at least one child product exists, take this path.

      NameInput
      Condition/ProductSet/count(Product)>0

  3. Create the default route.

    1. A default route is essential in all cases, and for this purpose, we can utilize a second Message End event. In order to achieve this, we can move the ProductID_Available route slightly downwards.

    2. Subsequently, place a second Message End event above the initial one.

    3. Name the new End event End_Message_Event.

    4. At this point, connect the Router to the new Message End event by utilizing the context menu.

    5. Change the name of this new route to No_ProductID_Available.

    6. Go to the Processing tab, and set this route as the default one.

      Note

      Multiple methods exist for configuring a router.

Task 3: Save as Version, Deploy, and Debug your Integration Process

Steps

  1. Save as version, deploy, and debug your integration process.

    1. Perform the following steps:

      1. Save as version.
      2. Deploy.
      3. Jump to Overview → Manage Integration Content.
      4. Set log level to trace.
      5. Deploy again.
      6. Jump again to Overview → Manage Integration Content.

    2. Navigate to your Integration Flow Model in Overview → Monitor Message Processing → Message Processing Run.

    3. As the product list contains both an existing and non-existent IDs, it is necessary to follow both paths.

  2. Learn more about the Router component.

    1. To access the help page for the router, navigate to your integration process, open the configuration bar of the Router, and choose the question mark symbol. This will bring up the help page in the usual manner.

Create a Request and Reply to an external Call (HTTP Call)

Business Scenario

Our current objective is to retrieve the relevant line items for each productID. To read the Customer ID during a subsequent call, we will require the SalesOrder ID and ItemPostion for each productID.

The following overview image provides an understanding of the location where the new component operates.

Task Flow

In this exercise, you will perform the following tasks:

  1. Log on to the integration flow DelayedDelivery_Process.
  2. Create a request and reply to external HTTP call.
  3. Save as version, deploy, and debug your integration process.

Prerequisites

The creation and configuration of a Router has been completed by you in the last step.

Outcome After This Exercise

An external HTTP adapter has been configured for a second Request and Reply call that is currently running.

What Do You Learn Within This Exercise?

Get familiar how to use and configure an HTTP adapter.

Exercise Options

To carry out this exercise, you can choose from the following options:

  1. Live Environment: Using the instructions provided below, you can perform the steps in your SAP BTP account.
  2. Platform Simulation: Follow the step-by-step instructions within the simulation.
  3. Side-by-side: Follow the step-by-step instructions within the simulation and perform the steps in your SAP BTP account simultaneously.

Note

We strongly recommend to perform the steps in the live environment.
ExerciseStart Exercise
ExerciseStart Exercise

Task 1: Log on to the Integration Flow DelayedDelivery_Process

Steps

  1. Log on to the integration flow DelayedDelivery_Process via Integration Suite.

    1. Navigate within the Integration Suite Welcome page to Design → Integrations → DelayedDelivery_Package_randomNumber → DelayedDelivery_Process.

    2. Check the Process.

    3. Imagine that the integration flow is more edited.

Task 2: Create a Request and Reply to an External HTTP Call

Steps

  1. Expand the workspace.

    1. We are working on the ProductID_Available route.

  2. Set a second Receiver component.

    1. Add a Receiver component.

    2. Rename the receiver to API_SalesOrder_ProductSet_ToSalesOrderLineItems. Ensure that each name is distinct.

  3. Add a Call → External Call → Request Reply.

    1. Manually arrange the components to create a visually pleasing flow. However, note that there is an automatic formatting feature.

    2. Change the name to Call_fetchLineItems.

    3. Again, drag the arrow from the context menu of the

      • Call_fetchLineItems to
      • API_SalesOrder_ProductSet_ToSalesOrderLineItems.

    4. Select the HTTP adapter.

    5. Select the HTTP connection line and access the connection tab to configure the adapter. Once again, we`ll use the Simple Expression Language to read the Exchange Property.

      Field NameInput
      Addresshttps://< your API >/ProductSet('${property.ProductID}')/ToSalesOrderLineItems for example: https://group-xxxxxxxxxxxxx.eu10.hana.ondemand.com/v1/GWSAMPLE_BASIC/ProductSet('${property.ProductID}')/ToSalesOrderLineItems
      Query$select=SalesOrderID,ItemPosition,DeliveryDate
      Proxy TypeInternet
      MethodGET
      AuthenticationNone

  4. Verify the number of available data records.

    1. In your browser tab, enter the following URL and replace ${property.ProductID} with HT-1000.

      https://< your API Host >/ProductSet('${property.ProductID}')/ToSalesOrderLineItems/$count

    2. Currently, there are 1400 data records available for the ProductID "HT-1000", but it is also possible that there is only one dataset. Keep in mind that the database will be filled with data every day, so if you don`t have a few data, try again later.

Task 3: Save as Version, Deploy, and Debug your Integration Process

Steps

  1. Save as version, deploy, and debug your integration process.

    1. Perform the following steps:

      1. Save as version.
      2. Deploy.
      3. Jump to Overview → Manage Integration Content.
      4. Set log level to trace.
      5. Deploy again.
      6. Jump again to Overview → Manage Integration Content.

    2. Navigate to your Integration Flow Model in Overview → Monitor Message Processing → Message Processing Run.

    3. A ProductID is being processed.

    4. Choose the End event step at the Message Content tab and at the Payload link.

    5. You will notice that the payload is too large, as it contains 1400 data records.

    6. You can either download the entire payload or use the following URL to retrieve only two data records using the "&$top=2" query parameter.

    7. Replace ${property.ProductID} with HT-1000.

      https://< your API >/ProductSet('${property.ProductID}')/ToSalesOrderLineItems/?&top=2

    8. The result is a feed with name spaces. The values we are interested in are under /Content/m:properties/SalesOrderandentry/Content/m:properties/ItemPosition.

  2. Learn more about the HTTP Adapter component.

    1. Navigate back to your Integration Process.

    2. Open the configuration bar of the HTTP Adapter and choose the question mark symbol.

Log in to track your progress & complete quizzes