title | description | services | ms.suite | author | ms.author | ms.reviewer | ms.topic | ms.date | tags |
---|---|---|---|---|---|---|---|---|---|
Connect to SAP systems |
Access and manage SAP resources by automating workflows with Azure Logic Apps |
logic-apps |
integration |
divyaswarnkar |
divswa |
estfan, daviburg, logicappspm |
article |
07/21/2020 |
connectors |
Important
The earlier SAP Application Server and SAP Message Server connectors are deprecated on February 29, 2020. The current SAP connector consolidates these previous SAP connectors so that you don't have to change the connection type, is fully compatible with previous connectors, provides many additional capabilities, and continues to use the SAP .Net connector library (SAP NCo).
For logic apps that use the older connectors, please migrate to the latest connector before the deprecation date. Otherwise, these logic apps will experience execution failures and won't be able to send messages to your SAP system.
This article shows how you can access your on-premises SAP resources from inside a logic app by using the SAP connector. The connector works with SAP's classic releases such as R/3 and ECC systems on-premises. The connector also enables integration with SAP's newer HANA-based SAP systems, such as S/4 HANA, whether they're hosted on-premises or in the cloud. The SAP connector supports message or data integration to and from SAP NetWeaver-based systems through Intermediate Document (IDoc), Business Application Programming Interface (BAPI), or Remote Function Call (RFC).
The SAP connector uses the SAP .NET Connector (NCo) library and provides these actions:
-
Send message to SAP: Send IDoc over tRFC, call BAPI functions over RFC, or call RFC/tRFC in SAP systems.
-
When a message is received from SAP: Receive IDoc over tRFC, call BAPI functions over tRFC, or call RFC/tRFC in SAP systems.
-
Generate schemas: Generate schemas for the SAP artifacts for IDoc, BAPI, or RFC.
For these operations, the SAP connector supports basic authentication through usernames and passwords. The connector also supports Secure Network Communications (SNC). SNC can be used for SAP NetWeaver single sign-on (SSO) or for additional security capabilities provided by an external security product.
This article shows how to create example logic apps that integrate with SAP while covering the previously described integration scenarios. For logic apps that use the older SAP connectors, this article shows how to migrate your logic apps to the latest SAP connector.
To follow along with this article, you need these items:
-
An Azure subscription. If you don't have an Azure subscription yet, sign up for a free Azure account.
-
The logic app from where you want to access your SAP system and a trigger that starts your logic app's workflow. If you're new to logic apps, see What is Azure Logic Apps? and Quickstart: Create your first logic app.
-
Your SAP application server or SAP message server.
-
Message content that you send to your SAP server, such as a sample IDoc file, must be in XML format and include the namespace for the SAP action you want to use.
-
To use the When a message is received from SAP trigger, you also need to perform these setup steps:
[!NOTE] This trigger uses the same URI location to both renew and unsubscribe from a webhook subscription. The renewal operation uses the HTTP
PATCH
method, while the unsubscribe operation uses the HTTPDELETE
method. This behavior might make a renewal operation appear as an unsubscribe operation in your trigger's history, but the operation is still a renewal because the trigger usesPATCH
as the HTTP method, notDELETE
.-
Set up your SAP gateway security permissions with this setting:
"TP=Microsoft.PowerBI.EnterpriseGateway HOST=<gateway-server-IP-address> ACCESS=*"
-
Set up your SAP gateway security logging, which helps find Access Control List (ACL) errors and isn't enabled by default. Otherwise, you get the following error:
"Registration of tp Microsoft.PowerBI.EnterpriseGateway from host <host-name> not allowed"
For more information, see the SAP help topic, Setting up gateway logging.
-
These prerequisites apply when your logic apps run in multi-tenant Azure, and you want to use the managed SAP connector, which doesn't run natively in an integration service environment (ISE). Otherwise, if you're using a Premium-level ISE and want to use the SAP connector that runs natively in the ISE, see Integration service environment (ISE) prerequisites.
The managed (non-ISE) SAP connector integrates with on-premises SAP systems through the on-premises data gateway. For example, in send message scenarios, when a message is sent from a logic app to an SAP system, the data gateway acts as an RFC client and forwards the requests received from the logic app to SAP. Likewise, in receive message scenarios, the data gateway acts as an RFC server that receives requests from SAP and forwards them to the logic app.
-
Download and install the on-premises data gateway on your local computer. Then, create an Azure gateway resource for that gateway in the Azure portal. The gateway helps you securely access on-premises data and resources.
As a best practice, make sure to use a supported version of the on-premises data gateway. Microsoft releases a new version every month. Currently, Microsoft supports the last six versions. If you experience an issue with your gateway, try upgrading to the latest version, which might include updates to resolve your problem.
-
Download and install the latest SAP client library on the same computer as the on-premises data gateway.
These prerequisites apply when your logic apps run in a Premium-level (not Developer-level) integration service environment (ISE), and you want to use the SAP connector that runs natively in an ISE. An ISE provides access to resources that are protected by an Azure virtual network and offers other ISE-native connectors that let logic apps directly access on-premises resources without using on-premises data gateway.
Note
Although the SAP ISE connector is visible inside a Developer-level ISE, attempts to install the connector won't succeed.
-
If you don't already have an Azure Storage account and a blob container, create that container by using either the Azure portal or Azure Storage Explorer.
-
Download and install the latest SAP client library on your local computer. You should have the following assembly files:
- libicudecnumber.dll
- rscp4n.dll
- sapnco.dll
- sapnco_utils.dll
-
Create a .zip file that includes these assemblies and upload this package to your blob container in Azure Storage.
-
In either the Azure portal or Azure Storage Explorer, browse to the container location where you uploaded the .zip file.
-
Copy the URL for that location, making sure that you include the Shared Access Signature (SAS) token.
Otherwise, the SAS token doesn't get authorized, and deployment for the SAP ISE connector will fail.
-
Before you can use the SAP ISE connector, you need to install and deploy the connector in your ISE.
-
In the Azure portal, find and open your ISE.
-
On the ISE menu, select Managed connectors > Add. From the connectors list, find and select SAP.
-
On the Add a new managed connector pane, in the SAP package box, paste the URL for the .zip file that has the SAP assemblies. Make sure that you include the SAS token.
-
When you're done, select Create.
For more information, see Add ISE connectors.
-
-
If your SAP instance and ISE are in different virtual networks, you also need to peer those networks so that your ISE's virtual network is connected to your SAP instance's virtual network.
-
Make sure that you install the latest version, SAP Connector (NCo 3.0) for Microsoft .NET 3.0.22.0 compiled with .NET Framework 4.0 - Windows 64-bit (x64). Earlier versions can result in compatibility problems. For more information, see SAP client library versions.
-
By default, the SAP installer puts the assembly files in the default installation folder. You need to copy these assembly files to another location, based on your scenario as follows:
-
For logic apps that run in an ISE, follow the steps described in the integration service environment prerequisites. For logic apps that run in multi-tenant Azure and use the on-premises data gateway, copy the assembly files from the default installation folder to the data gateway installation folder. If you run into problems with the data gateway, review the following issues:
-
You must install the 64-bit version for the SAP client library because the data gateway runs only on 64-bit systems. Otherwise, you get a "bad image" error because the data gateway host service doesn't support 32-bit assemblies.
-
If your SAP connection fails with the error message "Please check your account info and/or permissions and try again", the assembly files might be in the wrong location. Make sure that you copied the assembly files to the data gateway installation folder.
To help you troubleshoot, use the .NET assembly binding log viewer, which lets you check that the assembly files are in the correct location. Optionally, you can select the Global Assembly Cache registration option when you install the SAP client library.
-
Earlier SAP NCo versions might become deadlocked when more than one IDoc message is sent at the same time. This condition blocks all later messages that are sent to the SAP destination, which causes the messages to time out.
Here are the relationships between the SAP client library, the .NET Framework, the .NET runtime, and the gateway:
-
Both the Microsoft SAP Adapter and the gateway host service use .NET Framework 4.5.
-
The SAP NCo for .NET Framework 4.0 works with processes that use .NET runtime 4.0 to 4.7.1.
-
The SAP NCo for .NET Framework 2.0 works with processes that use .NET runtime 2.0 to 3.5, but no longer works with the latest gateway.
If you use the on-premises data gateway with the optional Secure Network Communications (SNC), which is supported only in multi-tenant Azure, you also need to configure these settings:
-
If you use SNC with Single Sign On (SSO), make sure the data gateway is running as a user that's mapped against the SAP user. To change the default account, select Change account, and enter the user credentials.
-
If you enable SNC with an external security product, copy the SNC library or files on the same computer where the data gateway is installed. Some examples of SNC products include sapseculib, Kerberos, and NTLM.
For more information about enabling SNC for the data gateway, see Enable Secure Network Communications.
To migrate from an earlier managed (non-ISE) SAP connector to the current managed SAP connector, follow these steps:
-
If you haven't done so already, update your on-premises data gateway so that you have the latest version. For more information, see Install an on-premises data gateway for Azure Logic Apps.
-
In the logic app that uses the older SAP connector, delete the Send to SAP action.
-
From the latest SAP connector, add the Send message to SAP action. Before you can use this action, recreate the connection to your SAP system.
-
When you're done, save your logic app.
This example uses a logic app that you can trigger with an HTTP request. The logic app sends an IDoc to an SAP server and returns a response to the requestor that called the logic app.
In Azure Logic Apps, every logic app must start with a trigger, which fires when a specific event happens or when a specific condition is met. Each time the trigger fires, the Logic Apps engine creates a logic app instance and starts running your app's workflow.
Note
When a logic app receives IDoc packets from SAP, the request trigger doesn't support the "plain" XML schema generated by SAP's WE60 IDoc documentation. However, the "plain" XML schema is supported for scenarios that send messages from logic apps to SAP. You can use the request trigger with SAP's IDoc XML, but not with IDoc over RFC. Or, you can transform the XML to the necessary format.
In this example, you create a logic app with an endpoint in Azure so that you can send HTTP POST requests to your logic app. When your logic app receives these HTTP requests, the trigger fires and runs the next step in your workflow.
-
In the Azure portal, create a blank logic app, which opens the Logic App Designer.
-
In the search box, enter
http request
as your filter. From the Triggers list, select When a HTTP request is received. -
Now save your logic app so that you can generate an endpoint URL for your logic app. On the designer toolbar, select Save.
The endpoint URL now appears in your trigger, for example:
In Azure Logic Apps, an action is a step in your workflow that follows a trigger or another action. If you haven't added a trigger to your logic app yet and want to follow this example, add the trigger described in this section.
-
In the Logic App Designer, under the trigger, select New step.
-
In the search box, enter
sap
as your filter. From the Actions list, select Send message to SAP.Or, you can select the Enterprise tab, and select the SAP action.
-
If your connection already exists, continue with the next step so you can set up your SAP action. However, if you're prompted for connection details, provide the information so that you can create a connection to your on-premises SAP server.
-
Provide a name for the connection.
-
If you're using the data gateway, follow these steps:
-
In the Data Gateway section, under Subscription, first select the Azure subscription for the data gateway resource that you created in the Azure portal for your data gateway installation.
-
Under Connection Gateway, select your data gateway resource in Azure.
-
-
Continue providing information about the connection. For the Logon Type property, follow the step based on whether the property is set to Application Server or Group:
-
For Application Server, these properties, which usually appear optional, are required:
-
For Group, these properties, which usually appear optional, are required:
By default, strong typing is used to check for invalid values by performing XML validation against the schema. This behavior can help you detect issues earlier. The Safe Typing option is available for backward compatibility and only checks the string length. Learn more about the Safe Typing option.
-
-
When you're finished, select Create.
Logic Apps sets up and tests your connection to make sure that the connection works properly.
-
-
Now find and select an action from your SAP server.
-
In the SAP Action box, select the folder icon. From the file list, find and select the SAP message you want to use. To navigate the list, use the arrows.
This example selects an IDoc with the Orders type.
If you can't find the action you want, you can manually enter a path, for example:
[!TIP] Provide the value for SAP Action through the expression editor. That way, you can use the same action for different message types.
For more information about IDoc operations, see Message schemas for IDoc operations.
-
Click inside the Input Message box so that the dynamic content list appears. From that list, under When a HTTP request is received, select the Body field.
This step includes the body content from your HTTP Request trigger and sends that output to your SAP server.
When you're finished, your SAP action looks like this example:
-
-
Save your logic app. On the designer toolbar, select Save.
Now add a response action to your logic app's workflow and include the output from the SAP action. That way, your logic app returns the results from your SAP server to the original requestor.
-
In the Logic App Designer, under the SAP action, select New step.
-
In the search box, enter
response
as your filter. From the Actions list, select Response. -
Click inside the Body box so that the dynamic content list appears. From that list, under Send message to SAP, select the Body field.
-
Save your logic app.
Note
The SAP trigger receives IDocs over tRFC, which doesn't have a response parameter by design.
You must create a request and response pattern if you need to receive replies by using a remote function call (RFC) to Logic Apps from SAP ABAP. To receive IDocs in your logic app, you should make its first action an HTTP request with a status code of 200 OK
and no content. This recommended step completes the SAP LUW asynchronous transfer over tRFC immediately, which leaves the SAP CPIC conversation available again. You can then add further actions in your logic app to process the received IDoc without blocking further transfers.
To implement a request and response pattern, you must first discover the RFC schema using the generate schema
command. The generated schema has two possible root nodes:
- The request node, which is the call that you receive from SAP.
- The response node, which is your reply back to SAP.
In the following example, a request and response pattern is generated from the STFC_CONNECTION
RFC module. The request XML is parsed to extract a node value in which SAP requests <ECHOTEXT>
. The response inserts the current timestamp as a dynamic value. You receive a similar response when you send a STFC_CONNECTION
RFC from a logic app to SAP.
<STFC_CONNECTIONResponse xmlns="http://Microsoft.LobServices.Sap/2007/03/Rfc/">
<ECHOTEXT>@{first(xpath(xml(triggerBody()?['Content']), '/*[local-name()="STFC_CONNECTION"]/*[local-name()="REQUTEXT"]/text()'))}</ECHOTEXT>
<RESPTEXT>Azure Logic Apps @{utcNow()}</RESPTEXT>
-
If your logic app isn't already enabled, on your logic app menu, select Overview. On the toolbar, select Enable.
-
On the designer toolbar, select Run. This step manually starts your logic app.
-
Trigger your logic app by sending an HTTP POST request to the URL in your HTTP Request trigger. Include your message content with your request. To the send the request, you can use a tool such as Postman.
For this article, the request sends an IDoc file, which must be in XML format and include the namespace for the SAP action you're using, for example:
<?xml version="1.0" encoding="UTF-8" ?> <Send xmlns="http://Microsoft.LobServices.Sap/2007/03/Idoc/2/ORDERS05//720/Send"> <idocData> <...> </idocData> </Send>
-
After you send your HTTP request, wait for the response from your logic app.
[!NOTE] Your logic app might time out if all the steps required for the response don't finish within the request timeout limit. If this condition happens, requests might get blocked. To help you diagnose problems, learn how you can check and monitor your logic apps.
You've now created a logic app that can communicate with your SAP server. Now that you've set up an SAP connection for your logic app, you can explore other available SAP actions, such as BAPI and RFC.
This example uses a logic app that triggers when the app receives a message from an SAP system.
-
In the Azure portal, create a blank logic app, which opens the Logic App Designer.
-
In the search box, enter
sap
as your filter. From the Triggers list, select When a message is received from SAP.Or, you can select the Enterprise tab, and then select the trigger:
-
If your connection already exists, continue with the next step so you can set up your SAP action. However, if you're prompted for connection details, provide the information so that you can create a connection to your on-premises SAP server now.
-
Provide a name for the connection.
-
If you're using the data gateway, follow these steps:
-
In the Data Gateway section, under Subscription, first select the Azure subscription for the data gateway resource that you created in the Azure portal for your data gateway installation.
-
Under Connection Gateway, select your data gateway resource in Azure.
-
-
Continue providing information about the connection. For the Logon Type property, follow the step based on whether the property is set to Application Server or Group:
-
For Application Server, these properties, which usually appear optional, are required:
-
For Group, these properties, which usually appear optional, are required:
By default, strong typing is used to check for invalid values by performing XML validation against the schema. This behavior can help you detect issues earlier. The Safe Typing option is available for backward compatibility and only checks the string length. Learn more about the Safe Typing option.
-
-
When you're finished, select Create.
Logic Apps sets up and tests your connection to make sure that the connection works properly.
-
-
Provide the required parameters based on your SAP system configuration.
You can filter the messages that you receive from your SAP server by specifying a list of SAP actions.
You can select an SAP action from the file picker:
Or, you can manually specify an action:
Here's an example that shows how the action appears when you set up the trigger to receive more than one message.
For more information about the SAP action, see Message schemas for IDoc operations
-
Now save your logic app so you can start receiving messages from your SAP system. On the designer toolbar, select Save.
Your logic app is now ready to receive messages from your SAP system.
Note
The SAP trigger isn't a polling trigger but is a webhook-based trigger instead. If you're using the data gateway, the trigger is called from the data gateway only when a message exists, so no polling is necessary.
Along with simple string and number inputs, the SAP connector accepts the following table parameters (Type=ITAB
inputs):
- Table direction parameters, both input and output, for older SAP releases.
- Changing parameters, which replace the table direction parameters for newer SAP releases.
- Hierarchical table parameters
You can optionally filter the messages that your logic app receives from your SAP server by providing a list, or array, with a single or multiple SAP actions. By default, this array is empty, which means that your logic app receives all the messages from your SAP server without filtering.
When you set up the array filter, the trigger only receives messages from the specified SAP action types and rejects all other messages from your SAP server. However, this filter doesn't affect whether the typing of the received payload is weak or strong.
Any SAP action filtering happens at the level of the SAP adapter for your on-premises data gateway. For more information, see how to send test IDocs to Logic Apps from SAP.
If you can't send IDoc packets from SAP to your logic app's trigger, see the Transactional RFC (tRFC) call rejection message in the SAP tRFC dialog box (T-code SM58). In the SAP interface, you might get the following error messages, which are clipped due to the substring limits on the Status Text field.
-
The RequestContext on the IReplyChannel was closed without a reply being
: Unexpected failures happen when the catch-all handler for the channel terminates the channel due to an error, and rebuilds the channel to process other messages.-
To acknowledge that your logic app received the IDoc, add a Response action that returns a
200 OK
status code. The IDoc is transported through tRFC, which doesn't allow for a response payload. -
If you need to reject the IDoc instead, respond with any HTTP status code other than
200 OK
so that the SAP Adapter returns an exception back to SAP on your behalf.
-
-
The segment or group definition E2EDK36001 was not found in the IDoc meta
: Expected failures happen with other errors, such as the failure to generate an IDoc XML payload because its segments are not released by SAP, so the segment type metadata required for conversion is missing.- To have these segments released by SAP, contact the ABAP engineer for your SAP system.
For full error messages, check your SAP adapter's extended logs.
For on-premises data gateway releases from June 2020 and later, you can enable gateway logs in the app settings.
For on-premises data gateway releases from April 2020 and earlier, logs are disabled by default. To retrieve extended logs, follow these steps:
-
In your on-premises data gateway installation folder, open the
Microsoft.PowerBI.DataMovement.Pipeline.GatewayCore.dll.config
file. -
For the SapExtendedTracing setting, change the value from False to True.
-
Optionally, for fewer events, change the SapTracingLevel value from Informational (default) to Error or Warning. Or, for more events, change Informational to Verbose.
-
Save the configuration file.
-
Restart your data gateway. Open your on-premises data gateway installer app, and go to the Service Settings menu. Under Restart the gateway, select Restart now.
-
Reproduce your issue.
-
Export your gateway logs. In your data gateway installer app, go to the Diagnostics menu. Under Gateway logs, select Export logs. These files include SAP logs organized by date. Depending on log size, multiple log files might exist for a single date.
-
In the configuration file, revert the SapExtendedTracing setting to False.
-
Restart the gateway service.
-
To trigger your logic app, send a message from your SAP system.
-
On the logic app menu, select Overview. Review the Runs history for any new runs for your logic app.
-
Open the most recent run, which shows the message sent from your SAP system in the trigger outputs section.
To send IDocs from SAP to your logic app, you need the following minimum configuration:
Important
Use these steps only when you test your SAP configuration with your logic app. Production environments require additional configuration.
-
To open the Configuration of RFC Connections settings, in your SAP interface, use the sm59 transaction code (T-code) with the /n prefix.
-
Select TCP/IP Connections > Create.
-
Create a new RFC destination with the following settings:
-
For your RFC Destination, enter a name.
-
On the Technical Settings tab, for Activation Type, select Registered Server Program. For your Program ID, enter a value. In SAP, your logic app's trigger will be registered by using this identifier.
-
On the Unicode tab, for Communication Type with Target System, select Unicode.
-
-
Save your changes.
-
Register your new Program ID with Azure Logic Apps.
-
To test your connection, in the SAP interface, under your new RFC Destination, select Connection Test.
-
To open the Configuration of RFC Connections settings, in your SAP interface, use the sm59* transaction code (T-code) with the /n prefix.
-
Select ABAP Connections > Create.
-
For RFC Destination, enter the identifier for your test SAP system.
-
Save your changes.
-
To test your connection, select Connection Test.
-
To open the Ports In IDOC processing settings, in your SAP interface, use the we21 transaction code (T-code) with the /n prefix.
-
Select Ports > Transactional RFC > Create.
-
In the settings box that opens, select own port name. For your test port, enter a Name. Save your changes.
-
In the settings for your new receiver port, for RFC destination, enter the identifier for your test RFC destination.
-
Save your changes.
-
To open the Ports In IDOC processing settings, in your SAP interface, use the we21 transaction code (T-code) with the /n prefix.
-
Select Ports > Transactional RFC > Create.
-
In the settings box that opens, select own port name. For your test port, enter a Name that starts with SAP. All sender port names must start with the letters SAP, for example, SAPTEST. Save your changes.
-
In the settings for your new sender port, for RFC destination, enter the identifier for your ABAP connection.
-
Save your changes.
-
To open the Change View "Logical Systems": Overview settings, in your SAP interface, use the bd54 transaction code (T-code).
-
Accept the warning message that appears: Caution: The table is cross-client
-
Above the list that shows your existing logical systems, select New Entries.
-
For your new logical system, enter a Log.System identifier and a short Name description. Save your changes.
-
When the Prompt for Workbench appears, create a new request by providing a description, or if you already created a request, skip this step.
-
After you create the workbench request, link that request to the table update request. To confirm that your table was updated, save your changes.
For production environments, you must create two partner profiles. The first profile is for the sender, which is your organization and SAP system. The second profile is for the receiver, which is your logic app.
-
To open the Partner profiles settings, in your SAP interface, use the we20 transaction code (T-code) with the /n prefix.
-
Under Partner Profiles, select Partner Type LS > Create.
-
Create a new partner profile with the following settings:
-
For Partner No., enter your logical system partner's identifier.
-
For Partn. Type, enter LS.
-
For Agent, enter the identifier for the SAP user account to use when you register program identifiers for Azure Logic Apps or other non-SAP systems.
-
-
Save your changes. If you haven't created the logical system partner, you get the error, Enter a valid partner number.
-
In your partner profile's settings, under Outbound parmtrs., select Create outbound parameter.
-
Create a new outbound parameter with the following settings:
-
Enter your Message Type, for example, CREMAS.
-
Enter your receiver port's identifier.
-
Enter an IDoc size for Pack. Size. Or, to send IDocs one at a time from SAP, select Pass IDoc Immediately.
-
-
Save your changes.
-
To open the Test Tool for IDoc Processing settings, in your SAP interface, use the we19 transaction code (T-code) with the /n prefix.
-
Under Template for test, select Via message type, and enter your message type, for example, CREMAS. Select Create.
-
Confirm the Which IDoc type? message by selecting Continue.
-
Select the EDIDC node. Enter the appropriate values for your receiver and sender ports. Select Continue.
-
Select Standard Outbound Processing.
-
To start outbound IDoc processing, select Continue. When processing finishes, the IDoc sent to SAP system or external program message appears.
-
To check for processing errors, use the sm58 transaction code (T-code) with the /n prefix.
You can set up SAP to send IDocs in packets, which are batches or groups of IDocs. To receive IDoc packets, the SAP connector, and specifically the trigger, doesn't need extra configuration. However, to process each item in an IDoc packet after the trigger receives the packet, some additional steps are required to split the packet into individual IDocs.
Here's an example that shows how to extract individual IDocs from a packet by using the xpath()
function:
-
Before you start, you need a logic app with an SAP trigger. If you don't already have this logic app, follow the previous steps in this topic to set up a logic app with an SAP trigger.
For example:
-
Get the root namespace from the XML IDoc that your logic app receives from SAP. To extract this namespace from the XML document, add a step that creates a local string variable and stores that namespace by using an
xpath()
expression:xpath(xml(triggerBody()?['Content']), 'namespace-uri(/*)')
-
To extract an individual IDoc, add a step that creates an array variable and stores the IDoc collection by using another
xpath()
expression:xpath(xml(triggerBody()?['Content']), '/*[local-name()="Receive"]/*[local-name()="idocData"]')
The array variable makes each IDoc available for your logic app to process individually by enumerating over the collection. In this example, the logic app transfers each IDoc to an SFTP server by using a loop:
Each IDoc must include the root namespace, which is the reason why the file content is wrapped inside a
<Receive></Receive
element along with the root namespace before sending the IDoc to the downstream app, or SFTP server in this case.
You can use the quickstart template for this pattern by selecting this template in the Logic App Designer when you create a new logic app.
This example uses a logic app that you can trigger with an HTTP request. To generate the schemas for the specified IDoc and BAPI, the SAP action Generate schema sends a request to an SAP system.
This SAP action returns an XML schema, not the contents or data of the XML document itself. Schemas returned in the response are uploaded to an integration account by using the Azure Resource Manager connector. Schemas contain the following parts:
- The request message's structure. Use this information to form your BAPI
get
list. - The response message's structure. Use this information to parse the response.
To send the request message, use the generic SAP action Send message to SAP, or the targeted Call BAPI actions.
If you're learning how to generate an XML schema for use in creating a sample document, see the following samples. These examples show how you can work with many types of payloads, including:
- RFC requests
- BAPI requests
- IDoc requests
- Simple or complex XML schema data types
- Table parameters
- Optional XML behaviors
You can begin your XML schema with an optional XML prolog. The SAP connector works with or without the XML prolog.
<?xml version="1.0" encoding="utf-8">
The following example is a basic RFC call. The RFC name is STFC_CONNECTION
. This request uses the default namespace xmlns=
, however, you can assign and use namespace aliases such as xmmlns:exampleAlias=
. The namespace value is the namespace for all RFCs in SAP for Microsoft services. There is a simple input parameter in the request, <REQUTEXT>
.
<STFC_CONNECTION xmlns="http://Microsoft.LobServices.Sap/2007/03/Rfc/">
<REQUTEXT>exampleInput</REQUTEXT>
</STFC_CONNECTION>
The following example is an RFC call with a table parameter. This example call and its group of test RFCs are available as part of all SAP systems. The table parameter's name is TCPICDAT
. The table line type is ABAPTEXT
, and this element repeats for each row in the table. This example contains a single line, called LINE
. Requests with a table parameter can contain any number of fields, where the number is a positive integer (n).
<STFC_WRITE_TO_TCPIC xmlns="http://Microsoft.LobServices.Sap/2007/03/Rfc/">
<RESTART_QNAME>exampleQName</RESTART_QNAME>
<TCPICDAT>
<ABAPTEXT xmlns="http://Microsoft.LobServices.Sap/2007/03/Rfc/">
<LINE>exampleFieldInput1</LINE>
<ABAPTEXT xmlns="http://Microsoft.LobServices.Sap/2007/03/Rfc/">
<LINE>exampleFieldInput2</LINE>
<ABAPTEXT xmlns="http://Microsoft.LobServices.Sap/2007/03/Rfc/">
<LINE>exampleFieldInput3</LINE>
</ABAPTEXT>
</TCPICDAT>
</STFC_WRITE_TO_TCPIC>
The following example is an RFC call with a table parameter that has an anonymous field. An anonymous field is when the field has no name assigned. Complex types are declared under a separate namespace, in which the declaration sets a new default for the current node and all its child elements. The example uses the hex codex002F
as an escape character for the symbol /, because this symbol is reserved in the SAP field name.
<RFC_XML_TEST_1 xmlns="http://Microsoft.LobServices.Sap/2007/03/Rfc/">
<IM_XML_TABLE>
<RFC_XMLCNT xmlns="http://Microsoft.LobServices.Sap/2007/03/Rfc/">
<_x002F_AnonymousField>exampleFieldInput</_x002F_AnonymousField>
</RFC_XMLCNT>
</IM_XML_TABLE>
</RFC_XML_TEST_1>
The following example includes prefixes for the namespaces. You can declare all prefixes at once, or you can declare any number of prefixes as attributes of a node. The RFC namespace alias ns0
is used as the root and parameters for the basic type.
Note
complex types are declared under a different namespace for RFC types with the alias ns3
instead of the regular RFC namespace with the alias ns0
.
<ns0:BBP_RFC_READ_TABLE xmlns:ns0="http://Microsoft.LobServices.Sap/2007/03/Rfc/" xmlns:ns3="http://Microsoft.LobServices.Sap/2007/03/Types/Rfc/">
<ns0:DELIMITER>0</ns0:DELIMITER>
<ns0:QUERY_TABLE>KNA1</ns0:QUERY_TABLE>
<ns0:ROWCOUNT>250</ns0:ROWCOUNT>
<ns0:ROWSKIPS>0</ns0:ROWSKIPS>
<ns0:FIELDS>
<ns3:RFC_DB_FLD>
<ns3:FIELDNAME>KUNNR</ns3:FIELDNAME>
</ns3:RFC_DB_FLD>
</ns0:FIELDS>
</ns0:BBP_RFC_READ_TABLE>
Tip
If you're using the Logic Apps designer to edit your BAPI request, you can use the following search functions:
- Select an object in the designer to see a drop-down menu of available methods.
- Filter business object types by keyword using the searchable list provided by the BAPI API call.
Note
SAP makes business objects available to external systems by describing them in response to RFC RPY_BOR_TREE_INIT
, which Logic Apps issues with no input filter. Logic Apps inspects the output table BOR_TREE
. The SHORT_TEXT
field is used for names of business objects. Business objects not returned by SAP in the output table aren't accessible to Logic Apps.
If you use custom business objects, you must make sure to publish and release these business objects in SAP. Otherwise, SAP doesn't list your custom business objects in the output table BOR_TREE
. You can't access your custom business objects in Logic Apps until you expose the business objects from SAP.
The following example gets a list of banks using the BAPI method GETLIST
. This sample contains the business object for a bank, BUS1011
.
<GETLIST xmlns="http://Microsoft.LobServices.Sap/2007/03/Bapi/BUS1011">
<BANK_CTRY>US</BANK_CTRY>
<MAX_ROWS>10</MAX_ROWS>
</GETLIST>
The following example creates a bank object using the CREATE
method. This example uses the same business object as the previous example, BUS1011
. When you use the CREATE
method to create a bank, be sure to commit your changes because this method isn't committed by default.
Tip
Be sure that your XML document follows any validation rules configured in your SAP system. For example, in this sample document, the bank key (<BANK_KEY>
) needs to be a bank routing number, also known as an ABA number, in the USA.
<CREATE xmlns="http://Microsoft.LobServices.Sap/2007/03/Bapi/BUS1011">
<BANK_ADDRESS>
<BANK_NAME xmlns="http://Microsoft.LobServices.Sap/2007/03/Types/Rfc">ExampleBankName</BANK_NAME>
<REGION xmlns="http://Microsoft.LobServices.Sap/2007/03/Types/Rfc">ExampleRegionName</REGION>
<STREET xmlns="http://Microsoft.LobServices.Sap/2007/03/Types/Rfc">ExampleStreetAddress</STREET>
<CITY xmlns="http://Microsoft.LobServices.Sap/2007/03/Types/Rfc">Redmond</CITY>
</BANK_ADDRESS>
<BANK_COUNTRY>US</BANK_COUNTRY>
<BANK_KEY>123456789</BANK_KEY>
</CREATE>
The following example gets details for a bank using the bank routing number, the value for<BANK_KEY>
.
<GETDETAIL xmlns="http://Microsoft.LobServices.Sap/2007/03/Bapi/BUS1011">
<BANK_COUNTRY>US</BANK_COUNTRY>
<BANK_KEY>123456789</BANK_KEY>
</GETDETAIL>
To generate a plain SAP IDoc XML schema, use the SAP Logon application and the T-code WE-60
. Access the SAP documentation through the GUI and generate XML schemas in XSD format for your IDoc types and extensions. For an explanation of generic SAP formats and payloads, and their built-in dialogs, see the SAP documentation.
This example declares the root node and namespaces. The URI in the sample code, http://Microsoft.LobServices.Sap/2007/03/Idoc/3/ORDERS05//700/Send
, declares the following configuration:
/IDoc
is the root note for all IDocs/3
is the record types version for common segment definitions/ORDERS05
is the IDoc type//
is an empty segment, because there's no IDoc extension/700
is the SAP version/Send
is the action to send the information to SAP
<ns0:Send xmlns:ns0="http://Microsoft.LobServices.Sap/2007/03/Idoc/3/ORDERS05//700/Send" xmlns:ns3="http://schemas.microsoft.com/2003/10/Serialization" xmlns:ns1="http://Microsoft.LobServices.Sap/2007/03/Types/Idoc/Common/" xmlns:ns2="http://Microsoft.LobServices.Sap/2007/03/Idoc/3/ORDERS05//700">
<ns0:idocData>
You can repeat the idocData
node to send a batch of IDocs in a single call. In the example below, there is one control record, EDI_DC40
, and multiple data records.
<...>
<ns0:idocData>
<ns2:EDI_DC40>
<ns1:TABNAM>EDI_DC40</ns1:TABNAM>
<...>
<ns1:ARCKEY>Cor1908207-5</ns1:ARCKEY>
</ns2:EDI_DC40>
<ns2:E2EDK01005>
<ns2:DATAHEADERCOLUMN_SEGNAM>E23DK01005</ns2:DATAHEADERCOLUMN_SEGNAM>
<ns2:CURCY>USD</ns2:CURCY>
</ns2:E2EDK01005>
<ns2:E2EDK03>
<...>
</ns0:idocData>
The following example is a sample IDoc control record, which uses the prefix EDI_DC
. You must update the values to match your SAP installation and IDoc type. For example, your IDoc client code may not be 800
. Contact your SAP team to make sure you're using the correct values for your SAP installation.
<ns2:EDI_DC40>
<ns:TABNAM>EDI_DC40</ns1:TABNAM>
<ns:MANDT>800</ns1:MANDT>
<ns:DIRECT>2</ns1:DIRECT>
<ns:IDOCTYP>ORDERS05</ns1:IDOCTYP>
<ns:CIMTYP></ns1:CIMTYP>
<ns:MESTYP>ORDERS</ns1:MESTYP>
<ns:STD>X</ns1:STD>
<ns:STDVRS>004010</ns1:STDVRS>
<ns:STDMES></ns1:STDMES>
<ns:SNDPOR>SAPENI</ns1:SNDPOR>
<ns:SNDPRT>LS</ns1:SNDPRT>
<ns:SNDPFC>AG</ns1:SNDPFC>
<ns:SNDPRN>ABAP1PXP1</ns1:SNDPRN>
<ns:SNDLAD></ns1:SNDLAD>
<ns:RCVPOR>BTSFILE</ns1:RCVPOR>
<ns:RCVPRT>LI</ns1:RCVPRT>
The following example is a sample data record with plain segments. This example uses the SAP date format. Strong-typed documents can use native XML date formats, such as 2020-12-31 23:59:59
.
<ns2:E2EDK01005>
<ns2:DATAHEADERCOLUMN_SEGNAM>E2EDK01005</ns2:DATAHEADERCOLUMN_SEGNAM>
<ns2:CURCY>USD</ns2:CURCY>
<ns2:BSART>OR</ns2:BSART>
<ns2:BELNR>1908207-5</ns2:BELNR>
<ns2:ABLAD>CC</ns2:ABLAD>
</ns2>
<ns2:E2EDK03>
<ns2:DATAHEADERCOLUMN_SEGNAM>E2EDK03</ns2:DATAHEADERCOLUMN_SEGNAM>
<ns2:IDDAT>002</ns2:IDDAT>
<ns2:DATUM>20160611</ns2:DATUM>
</ns2:E2EDK03>
The following example is a data record with grouped segments. The record includes a group parent node, E2EDKT1002GRP
, and multiple child nodes, including E2EDKT1002
and E2EDKT2001
.
<ns2:E2EDKT1002GRP>
<ns2:E2EDKT1002>
<ns2:DATAHEADERCOLUMN_SEGNAM>E2EDKT1002</ns2:DATAHEADERCOLUMN_SEGNAM>
<NS2:TDID>ZONE</ns2:TDID>
</ns2:E2EDKT1002>
<ns2:E2EDKT2001>
<ns2:DATAHEADERCOLUMN_SEGNAM>E2EDKT2001</ns2:DATAHEADERCOLUMN_SEGNAM>
<ns2:TDLINE>CRSD</ns2:TDLINE>
</ns2:E2EDKT2001>
</ns2:E2EDKT1002GRP>
The recommended method is to create an IDoc identifier for use with tRFC. You can set this transaction identifier, tid
, using the Send IDoc operation in the SAP connector API.
The following example is an alternative method to set the transaction identifier, or tid
. In this example, the last data record segment node and the IDoc data node are closed. Then, the GUID, guid
, is used as the tRFC identifier to detect duplicates.
</E2STZUM002GRP>
</idocData>
<guid>8820ea40-5825-4b2f-ac3c-b83adc34321c</guid>
</Send>
-
In the Azure portal, create a blank logic app, which opens the Logic App Designer.
-
In the search box, enter
http request
as your filter. From the Triggers list, select When a HTTP request is received. -
Now save your logic app so you can generate an endpoint URL for your logic app. On the designer toolbar, select Save.
The endpoint URL now appears in your trigger, for example:
-
In the Logic App Designer, under the trigger, select New step.
-
In the search box, enter
sap
as your filter. From the Actions list, select Generate schemas.Or, you can select the Enterprise tab, and select the SAP action.
-
If your connection already exists, continue with the next step so you can set up your SAP action. However, if you're prompted for connection details, provide the information so that you can create a connection to your on-premises SAP server now.
-
Provide a name for the connection.
-
In the Data Gateway section, under Subscription, first select the Azure subscription for the data gateway resource that you created in the Azure portal for your data gateway installation.
-
Under Connection Gateway, select your data gateway resource in Azure.
-
Continue providing information about the connection. For the Logon Type property, follow the step based on whether the property is set to Application Server or Group:
-
For Application Server, these properties, which usually appear optional, are required:
-
For Group, these properties, which usually appear optional, are required:
By default, strong typing is used to check for invalid values by performing XML validation against the schema. This behavior can help you detect issues earlier. The Safe Typing option is available for backward compatibility and only checks the string length. Learn more about the Safe Typing option.
-
-
When you're finished, select Create.
Logic Apps sets up and tests your connection to make sure that the connection works properly.
-
-
Provide the path to the artifact for which you want to generate the schema.
You can select the SAP action from the file picker:
Or, you can manually enter the action:
To generate schemas for more than one artifact, provide the SAP action details for each artifact, for example:
For more information about the SAP action, see Message schemas for IDoc operations.
-
Save your logic app. On the designer toolbar, select Save.
-
On the designer toolbar, select Run to trigger a run for your logic app.
-
Open the run, and check the outputs for the Generate schemas action.
The outputs show the generated schemas for the specified list of messages.
Optionally, you can download or store the generated schemas in repositories, such as a blob, storage, or integration account. Integration accounts provide a first-class experience with other XML actions, so this example shows how to upload schemas to an integration account for the same logic app by using the Azure Resource Manager connector.
-
In the Logic App Designer, under the trigger, select New step.
-
In the search box, enter
Resource Manager
as your filter. Select Create or update a resource. -
Enter the details for the action, including your Azure subscription, Azure resource group, and integration account. To add SAP tokens to the fields, click inside the boxes for those fields, and select from the dynamic content list that appears.
-
Open the Add new parameter list, and select the Location and Properties fields.
-
Provide details for these new fields as shown in this example.
The SAP Generate schemas action generates schemas as a collection, so the designer automatically adds a For each loop to the action. Here's an example that shows how this action appears:
[!NOTE] The schemas use base64-encoded format. To upload the schemas to an integration account, they must be decoded by using the
base64ToString()
function. Here's an example that shows the code for the"properties"
element:"properties": { "Content": "@base64ToString(items('For_each')?['Content'])", "ContentType": "application/xml", "SchemaType": "Xml" }
-
-
Save your logic app. On the designer toolbar, select Save.
-
On the designer toolbar, select Run to manually trigger your logic app.
-
After a successful run, go to the integration account, and check that the generated schemas exist.
Before you start, make sure that you met the previously listed prerequisites, which apply only when you use the data gateway and your logic apps run in multi-tenant Azure:
-
Make sure the on-premises data gateway is installed on a computer that's in the same network as your SAP system.
-
For Single Sign On (SSO), the data gateway is running as a user that's mapped to an SAP user.
-
The SNC library that provides the additional security functions is installed on the same machine as the data gateway. Some examples include sapseculib, Kerberos, and NTLM.
To enable SNC for your requests to or from the SAP system, select the Use SNC check box in the SAP connection and provide these properties:
Property Description SNC Library Path The SNC library name or path relative to NCo installation location or absolute path. Examples are sapsnc.dll
or.\security\sapsnc.dll
orc:\security\sapsnc.dll
.SNC SSO When you connect through SNC, the SNC identity is typically used for authenticating the caller. Another option is to override so that user and password information can be used for authenticating the caller, but the line is still encrypted. SNC My Name In most cases, this property can be omitted. The installed SNC solution usually knows its own SNC name. Only for solutions that support multiple identities, you might need to specify the identity to be used for this particular destination or server. SNC Partner Name The name for the back-end SNC. SNC Quality of Protection The quality of service to be used for SNC communication of this particular destination or server. The default value is defined by the back-end system. The maximum value is defined by the security product used for SNC. [!NOTE] Don't set the environment variables SNC_LIB and SNC_LIB_64 on the machine where you have the data gateway and the SNC library. If set, they take precedence over the SNC library value passed through the connector.
By default, when you create your SAP connection, strong typing is used to check for invalid values by performing XML validation against the schema. This behavior can help you detect issues earlier. The Safe Typing option is available for backward compatibility and only checks the string length. If you choose Safe Typing, the DATS type and TIMS type in SAP are treated as strings rather than as their XML equivalents, xs:date
and xs:time
, where xmlns:xs="http://www.w3.org/2001/XMLSchema"
. Safe typing affects the behavior for all schema generation, the send message for both the "been sent" payload and the "been received" response, and the trigger.
When strong typing is used (Safe Typing isn't enabled), the schema maps the DATS and TIMS types to more straightforward XML types:
<xs:element minOccurs="0" maxOccurs="1" name="UPDDAT" nillable="true" type="xs:date"/>
<xs:element minOccurs="0" maxOccurs="1" name="UPDTIM" nillable="true" type="xs:time"/>
When you send messages using strong typing, the DATS and TIMS response complies to the matching XML type format:
<DATE>9999-12-31</DATE>
<TIME>23:59:59</TIME>
When Safe Typing is enabled, the schema maps the DATS and TIMS types to XML string fields with length restrictions only, for example:
<xs:element minOccurs="0" maxOccurs="1" name="UPDDAT" nillable="true">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="8" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element minOccurs="0" maxOccurs="1" name="UPDTIM" nillable="true">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="6" />
</xs:restriction>
</xs:simpleType>
</xs:element>
When messages are sent with Safe Typing enabled, the DATS and TIMS response looks like this example:
<DATE>99991231</DATE>
<TIME>235959</TIME>
When you connect to SAP from Logic Apps, the default language for the connection is English. You can set the language for your connection by using the standard HTTP header Accept-Language
with your inbound requests.
Tip
Most web browsers add an Accept-Language
header based on the user's settings. The web browser applies this header when you create a new SAP connection in the Logic Apps designer. If you don't want to create SAP connections in your web browser's preferred language, either update your web browser's settings to use your preferred language, or create your SAP connection using Azure Resource Manager instead of the Logic Apps designer.
For example, you can send a request with the Accept-Language
header to your logic app by using the HTTP Request trigger. All the actions in your logic app receive the header. Then, SAP uses the specified languages in its system messages, such as BAPI error messages.
The SAP connection parameters for a logic app don't have a language property. So, if you use the Accept-Language
header, you might get the following error: Please check your account info and/or permissions and try again. In this case, check the SAP component's error logs instead. The error actually happens in the SAP component that uses the header, so you might get one of these error messages:
"SAP.Middleware.Connector.RfcLogonException: Select one of the installed languages"
"SAP.Middleware.Connector.RfcAbapMessageException: Select one of the installed languages"
When you send transactions to SAP from Logic Apps, this exchange happens in two steps as described in the SAP document, Transactional RFC Server Programs. By default, the Send to SAP action handles both the steps for the function transfer and for the transaction confirmation in a single call. The SAP connector gives you the option to decouple these steps. You can send an IDoc and rather than automatically confirm the transaction, you can use the explicit Confirm transaction ID action.
This capability to decouple the transaction ID confirmation is useful when you don't want to duplicate transactions in SAP, for example, in scenarios where failures might happen due to causes such as network issues. By confirming the transaction ID separately, the transaction is only completed one time in your SAP system.
Here is an example that shows this pattern:
-
Create a blank logic app and add an HTTP trigger.
-
From the SAP connector, add the Send IDOC action. Provide the details for the IDoc that you send to your SAP system.
-
To explicitly confirm the transaction ID in a separate step, in the Confirm TID field, select No. For the optional Transaction ID GUID field, you can either manually specify the value or have the connector automatically generate and return this GUID in the response from the Send IDOC action.
-
To explicitly confirm the transaction ID, add the Confirm transaction ID action, making sure to avoid sending duplicate IDocs to SAP. Click inside the Transaction ID box so that the dynamic content list appears. From that list, select the Transaction ID value that's returned from the Send IDOC action.
After this step runs, the current transaction is marked complete at both ends, on the SAP connector side and on SAP system side.
If you experience an issue with duplicate IDocs being sent to SAP from your logic app, follow these steps to create a string variable to serve as your IDoc transaction identifier. Creating this transaction identifier helps prevent duplicate network transmissions when there are issues such as temporary outages, network issues, or lost acknowledgments.
Note
SAP systems forget a transaction identifier after a specified time, or 24 hours by default. As a result, SAP never fails to confirm a transaction identifier if the ID or GUID is unknown. If confirmation for a transaction identifier fails, this failure indicates that communcation with the SAP system failed before SAP was able to acknowledge the confirmation.
- In the Logic Apps designer, add the action Initialize variable to your logic app.
- In the editor for the action Initialize variable, configure the following settings. Then, save your changes.
- For Name, enter a name for your variable. For example,
IDOCtransferID
. - For Type, select String as the variable type.
- For Value, select the text box Enter initial value to open the dynamic content menu. Select the Expressions tab. In the list of functions, enter the function
guid()
. Then, select OK to save your changes. The Value field is now set to theguid()
function, which generates a GUID.
- For Name, enter a name for your variable. For example,
- After the Initialize variable action, add the action Send IDOC.
- In the editor for the action Send IDOC, configure the following settings. Then, save your changes.
- For IDOC type select your message type, and for Input IDOC message, specify your message.
- For SAP release version, select your SAP configuration's values.
- For Record types version, select your SAP configuration's values.
- For Confirm TID, select No.
- Select Add new parameter list > Transaction ID GUID. Select the text box to open the dynamic content menu. Under the Variables tab, select the name of the variable that you created. For example,
IDOCtransferID
.
- On the title bar of the action Send IDOC, select ... > Settings. For Retry Policy, select None > Done.
- After the action Send IDOC, add the action Confirm transaction ID.
- In the editor for the action Confirm transaction ID, configure the following settings. Then, save your changes.
- For Transaction ID, enter the name of your variable again. For example,
IDOCtransferID
.
- For Transaction ID, enter the name of your variable again. For example,
Here are the currently known issues and limitations for the managed (non-ISE) SAP connector:
-
The SAP trigger doesn't support data gateway clusters. In some failover cases, the data gateway node that communicates with the SAP system might differ from the active node, which results in unexpected behavior. For send scenarios, data gateway clusters are supported.
-
The SAP connector currently doesn't support SAP router strings. The on-premises data gateway must exist on the same LAN as the SAP system you want to connect.
For more technical details about this connector, such as triggers, actions, and limits as described by the connector's Swagger file, see the connector's reference page.
Note
For logic apps in an integration service environment (ISE), this connector's ISE-labeled version uses the ISE message limits instead.
- Connect to on-premises systems from Azure Logic Apps.
- Learn how to validate, transform, and use other message operations with the Enterprise Integration Pack.
- Learn about other Logic Apps connectors.