Using Adapters

Objective

After completing this lesson, you will be able to use adapters

Adapters

In this lesson, the following topics are discussed:

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

Adapters in an overview

A wide variety of prebuilt 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 simply 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 flow, 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 previously mentioned 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, it 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 the converters come into play. Using the XML Message format enables the delivery of excellent support (XPATH) in individual integration flow components.

Sample OData Receiver Adapter

The OData adapter is applied in the exercises. What sets the OData adapter apart, and why is it selected for use in the exercise? This is discussed in the following paragraphs.

The Query Wizard

The OData Sender Adapter features a wizard that allows users to navigate to the interface to be accessed by using 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.

Screenshot of the Query Wizard.

The Page Processing Mode

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

Screenshot of an OData Entries example.

Sometimes, the number of entries in the feed can be substantial, potentially resulting in technical issues due to message size limitations. To overcome this challenge, paging processing is employed. It 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

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

This graphic shows that this Scenario has a looping Process Call at No. 1. At No. 2, the OData Adapter calls an OData API.
This graphic shows the configuration of the OData Adapter.

The Result is:

This graphic shows the result: Number of Calls at No. 1: 1 Number of Items (CustomerReviews) in the Result Feed: 30.
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.

This graphic shows the page processing example.

The Result is:

This graphic shows the result: Number of Calls at No. 1: 6 Number of Items (CustomerReviews) in the Result Feed: 5.

Automatically Removing of the Name Spaces of the Response

Apart from the option to gather data in packages, the namespaces and their prefixes are also automatically eliminated. It enables the data to be processed directly with XPATH. During the practice session, the HTTP adapter is used for the other calls. However, it does not automatically remove the namespaces, needing extra 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) and the transport, application, and message protocols employed. Broadly speaking, these adapters can be classified as HTTP-based, TCP/IP-based, or nonHTTP/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. Also, 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

In your integration process, various Product IDs are used. To check whether the supplied Product IDs are correct, you must validate them. To do this, you set up a query to the existing database and use your created API in API Management. This verification is performed through an OData protocol query.

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.

The graphic shows the prerequisite.

Outcome after this exercise

The first external API call will be implemented by you.

The graphic highlights the outcome after this exercise.

What do you learn within this exercise?

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

Task 1: Log on to the Integration Flow DelayedDelivery_Process

Steps

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

    1. Navigate within the SAP Integration Suite Welcome page to Design → Integrations → DelayedDelivery_Package_CLD900_Number → DelayedDelivery_Process_Number.

    2. Check the status after the last exercise step:

      The graphic shows the working integration flow.

    3. Imagine that the integration flow is more edited.

Task 2: Create and Configure an OData Adapter

Steps

  1. Set a Receiver.

    1. To create a receiver, choose the Participants menu and select Receiver.

    2. Move the receiver to the position you want.

      Choose Participants, and then Receiver.

    3. Name the receiver API_SalesOrder_ProductSet.

      Name and place the receiver.

  2. Set an External Call.

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

      External call request reply

    2. Name it Call_checkProductID.

      Name it Call_checkProductID.

  3. Configure the OData Adapter.

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

      Set up of the receiver and API call.

    2. Select OData → Data V2 as the adapter.

      You can also choose the OData V4 if you want.
      OData adapter is marked in red.OData V2 is marked in red.

    3. If the configuration bar does not display 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

      Code Snippet
      123
      
https://>your host from your API</v1/GWSAMPLE_BASIC

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

      DO NOT COPY THIS LINK

      Proxy TypeInternet
      AuthenticationNone
      Reuse ConnectionLabeled

      Make sure to remove the checkmark for "CSRF Protected".

      OData configuration.

    5. Your API URL can be found in the Configure → APIs → API Proxies section.

      Get the API URL.

    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.

      Choose Select in the OData setup wizard.

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

      Choose Step 2.

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

      Choose ProductSet.

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

      • ProductID
      • Category
      • Name
      ProductID, Category, and Name are marked in red as the field selections in the OData setup.

    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.

      The Filter By section is highlighted in red.

    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 manually: ${property.ProductID}.

      Be careful to write the Simple Expression Notation correctly, as mentioned in step p.

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

    17. Choose Finish.

      The fields Operation Details, Resource Path, and Query Options are automatically set. Make sure to also copy over the content type and timeout.The graphic shows the configured results in the OData setup.

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 → Integration Content.

    2. Navigate to your Integration Flow Model in Overview → Monitor Message Processing → Message Processing Run. Select the End artifact and choose the Message Content tab.

    3. Choose the End artifact and choose the Message Content tab.

      Choose Message Content and then End.

    4. Choose the Payload tab to see the message.

    Choose Payload to see the message

    1. If a ProductID is stored in the database, the API call functions properly. However, you must also verify whether the API call works when the ProductID is not stored in the database.

    2. Go back to your integration process and choose Edit.

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

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

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

      monitoring trace without any output for that productid

    5. Don't revert the incorrect ProductID back, as we must 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.

      Choose Help.

    3. Here, you 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

After extra exchange properties have been used with the content modifier and the message query has been expanded, empty information must be filtered out. This can be made visible using the router artifact.

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 Content Modifier with the Exchange Properties has been completed by you in the last step.

Outcome after this exercise

A working integration flow with a filtering of non existent ProductIDs.

outcome

What do you learn within this exercise?

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

Task 1: Log on to the Integration Flow DelayedDelivery_Process

Steps

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

    1. Navigate within the SAP Integration Suite Welcome page to Design → Integrations → DelayedDelivery_Package_CLD900_Date_Number → DelayedDelivery_Process_Number.

    2. Follow the status after the last exercise step.

      exercise start

    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 artifact in a known way according to the Modify_setProductIDasProperty, name it Router_ProductID.

      set a router

    2. Rename the existing End Message Event to End_Message_with_ProductID.

  2. Create the following Condition in the router:

    1. Choose the line between the router and the End_Message_with_ProductID artifact. Choose the General tab and change the name from Route 1 to ProductID_Available.

      name the route

    2. Switch to the Processing tab. In the Condition field and enter the code below. That means if at least one child product exists, take this path:

      /ProductSet/count(Product)>0.

      configuration of the router
      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 use a second Message End event. In order to achieve this, choose the plus navigation menu and add an End Message Event artifact. Now, you can move the ProductID_Available route slightly downwards.

      add an end message
      no productid available route

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

    3. Name the new End event End_Message__without_ProductID.

    4. Go to the Processing tab of the No_ProductID_Available route, and set this route as the default one.

      set a default route

    5. Now, your process should look like this one:

      example outcome

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 the 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 existing and non existent IDs, it is necessary to follow both paths.

      Go to the monitoring and first choose the End_Message_without_ProductID artifact. Select the Message Content tab and check the Payload without any ProductID information.

      monitoring trace

    Now, you don't see entries for some ProductIDs.

    without productid payload

    1. Now, check the monitor trace messages with ProductIDs. To do this, select the End_Message_with_ProductID artifact and choose the Message Content tab to check the payload with ProductIDs.

      with productids payload

      Now, you see some entries with ProductID information.

      payload with productids

  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 brings up the help page in the usual manner.

Create a Request and Reply to an External Call (2. OData Adapter)

Business Scenario

To obtain the customer names in a list, you must retrieve more detailed information via the GWSAMPLE API. Specifically, you will need the SalesOrderID, ItemPosition, and ProductID, which can be found in the ToSalesOrderLineItems via the Productset Resource.

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 an external OData 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 OData adapter has been configured for a second Request and Reply call that is currently running.

The graphic shows the outcome.

What do you learn within this exercise?

Get familiar with how to use and configure an OData adapter.

Task 1: Log on to the Integration Flow DelayedDelivery_Process

Steps

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

    1. Navigate within the SAP Integration Suite Welcome page to Design → Integrations → DelayedDelivery_Package_CLD900_Date_Number → DelayedDelivery_Process_Number.

    2. Your actual integration flow should look like this.

      Start at this exercise.

    3. Imagine that the integration flow is more edited.

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

Steps

  1. Expand the workspace.

    1. We are working on the ProductID_Available route.

      End message.

  2. Set a second Receiver component.

    1. Add a Receiver component.

      Set up the receiver.

    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, there is an automatic formatting feature in the context menu on the integration process line.

      Request reply.

    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.
      Connect the receiver.

    4. Select the OData adapter.

      Odata adapter.

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

      Odata connection.You get your API address from your SAP Integration Suite under Configure → APIs
      Field NameInput
      Address
      Code Snippet
      123
      
https://<yourAPI>/<version>/GWSAMPLE_BASIC
      Proxy TypeInternet
      AuthenticationNone
      CSRF Protectedflagged
      Reuse Connectionflagged

      Switch to the Processing tab to configure the processing details.

      Processing setup.

      Choose the Select button to configure your resource path.

      Field NameInput
      Operation DetailsQuery (Get)
      Resource PathChoose the Select button.

      All needed information under Connect to System should be automatically filled in. Choose the Step 2 button to continue.

      Connect to system.

      In this section, you need only to choose the operation Query (GET), the Sub Levels, and the Entity with their needed Fields.

      Field NameInput
      Connection SourceRemote
      Address*automatically filled in*
      Proxy TypeInternet
      AuthenticationNone
      Select entity.

      In the fields section, choose ToSalesOrderLineItems and the subfields SalesOrderID, ItemPosition, DeliveryDate.

      Field NameInput
      OperationQuery (Get)
      Sub Levels1
      Select EntityProductSet
      Select entity 1.

      Now, the wizard generates a query for you, check your query and if everything is matching, choose the Step 3 button.

      Field NameInput
      FieldsToSalesOrderLineItems
      SubfieldSalesOrderID
      SubfieldItemPosition
      SubfieldDeliveryDate
      Select entity 2.

      The last step is configuring a filter with your already set exchange property.

      Choose the

      Code Snippet
      123
      
ProductID <Equal> ${property.ProductID}
      in the Filter by section.

      When you have done this, choose the Finish button.

      Configure odata.Be aware that you type the Exchange Property correctly in the field ${property.ProductID}!End of odata setup.

    6. That is how your OData adapter configuration should look.

  4. Now, you can verify the number of available data records with a request as follows:

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

      Trace monitoring.

    3. A ProductID is being processed.

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

      End message.

    5. If the payload is too large, you cannot view it immediately. To do so, you must download it or limit the message flow."?&top=2"

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

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

      Here, you can check and see that the system has limited the message output on two messages entries. Try it out.

      Xml structure.

  2. Learn more about the OData Adapter component.

    1. Navigate back to your integration process.

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

Log in to track your progress & complete quizzes

Learning

SAP FacebookSAP YoutubeSAP LinkedIn