Connect to SAP from workflows in Azure Logic Apps
Applies to: Azure Logic Apps (Consumption + Standard)
This multipart how-to guide shows how to access your SAP server from a workflow in Azure Logic Apps using the SAP connector. You can use the SAP connector's operations to create automated workflows that run when triggered by events in your SAP server or in other systems and run actions to manage resources on your SAP server.
Both Standard and Consumption logic app workflows offer the SAP managed connector that's hosted and run in multitenant Azure. Standard workflows also offer the SAP built-in connector that's hosted and run in single-tenant Azure Logic Apps. For more information, see Connector technical reference.
SAP compatibility
The SAP connector is compatible with the following types of SAP systems:
On-premises and cloud-based HANA-based SAP systems, such as S/4 HANA.
Classic on-premises SAP systems, such as R/3 and ECC.
SAP must support the SAP system version that you want to connect. Otherwise, any issues that you might encounter might not be resolvable. For more information about SAP system versions and maintenance information, review the SAP Product Availability Matrix (PAM).
The SAP connector supports the following message and data integration types from SAP NetWeaver-based systems:
Intermediate Document (IDoc)
Business Application Programming Interface (BAPI)
Remote Function Call (RFC) and Transactional RFC (tRFC)
The SAP connector uses the SAP .NET Connector (NCo) library.
To use the SAP connector operations, you have to first authenticate your connection and have the following options:
You can provide a username and password.
The SAP connector supports authentication with SAP Secure Network Communications (SNC).
You can use SNC for SAP NetWeaver single sign-on (SSO) or for security capabilities from external products. If you choose to use SNC, review the SNC prerequisites and the SNC prerequisites for the ISE connector.
Connector technical reference
The SAP connector has different versions, based on logic app type and host environment.
Logic app | Environment | Connector version |
---|---|---|
Consumption | Multitenant Azure Logic Apps | Managed connector, which appears in the designer under the Enterprise label. For more information, review the following documentation: - SAP managed connector reference - Managed connectors in Azure Logic Apps |
Consumption | Integration service environment (ISE) | Managed connector, which appears in the designer under the Enterprise label, and the ISE-native version, which appears in the designer with the ISE label and has different message limits than the managed connector. Note: Make sure to use the ISE-native version, not the managed version. For more information, review the following documentation: - SAP managed connector reference - ISE message limits - Managed connectors in Azure Logic Apps |
Standard | Single-tenant Azure Logic Apps and App Service Environment v3 (Windows plans only) | Managed connector, which appears in the connector gallery under Runtime > Shared, and the built-in connector, which appears in the connector gallery under Runtime > In-App and is service provider-based. The built-in connector can directly access Azure virtual networks with a connection string without an on-premises data gateway. For more information, review the following documentation: - SAP managed connector reference - SAP built-in connector reference - Managed connectors in Azure Logic Apps - Built-in connectors in Azure Logic Apps |
Connector differences
The SAP built-in connector significantly differs from the SAP managed connector and SAP ISE-versioned connector in the following ways:
On-premises connections don't require the on-premises data gateway.
Instead, the SAP built-in connector communicates directly with your SAP server in the integrated virtual network, which avoids hops, latency, and failure points for a network gateway. Make sure that you upload or deploy the non-redistributable SAP client libraries with your logic app workflow application. For more information, see the Prerequisites in this guide.
Payload sizes up to 100 MB are supported, so you don't have to use a blob URI for large requests.
Specific actions are available for Call BAPI, Call RFC, and Send IDoc. These dedicated actions provide a better experience for stateful BAPIs, RFC transactions, and IDoc deduplication, and don't use the older SOAP Windows Communication Foundation (WCF) messaging model.
The Call BAPI action includes up to two responses with the returned JSON, the XML response from the called BAPI, and the BAPI commit or BAPI rollback response as well and if you use auto-commit. This capability addresses the problem with the SAP managed connector where the outcome from the auto-commit is silent and observable only through logs.
Longer timeout at 5 minutes compared to managed connector and ISE-versioned connector.
The SAP built-in connector doesn't use the shared or global connector infrastructure, which means timeouts are longer at 5 minutes compared to the SAP managed connector (two minutes) and the SAP ISE-versioned connector (four minutes). Long-running requests work without you having to implement the long-running webhook-based request action pattern.
By default, the SAP built-in connector operations are stateless. However, you can enable stateful mode (affinity) for these operations.
In stateful mode, the SAP built-in connector supports high availability and horizontal scale-out configurations. By comparison, the SAP managed connector has restrictions regarding the on-premises data gateway limited to a single instance for triggers and to clusters only in failover mode for actions. For more information, see SAP managed connector - Known issues and limitations.
Standard logic app workflows require and use the SAP NCo 3.1 client library, not the SAP NCo 3.0 version. For more information, see Prerequisites.
Standard logic app workflows provide application settings where you can specify a Personal Security Environment (PSE) and PSE password.
This change prevents you from uploading multiple PSE files, which isn't supported and results in SAP connection failures. In Consumption logic app workflows, the SAP managed connector lets you specify these values through connection parameters, which allowed you to upload multiple PSE files and isn't supported, causing SAP connection failures.
Generate Schema action
You can select from multiple operation types, such as BAPI, IDoc, RFC, and tRFC, versus the same action in the SAP managed connector, which uses the SapActionUris parameter and a file system picker experience.
You can directly provide a parameter name as a custom value. For example, you can specify the RFC Name parameter from the Call RFC action. By comparison, in the SAP managed connector, you had to provide a complex Action URI parameter name.
By design, this action doesn't support generating multiple schemas for RFCs, BAPIs, or IDocs in single action execution, which the SAP managed connector supports. This capability change now prevents attempts to send large amounts of content in a single call.
Connector parameters
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.
- Parameter changes, which replace the table direction parameters for newer SAP releases.
- Hierarchical table parameters.
Known issues and limitations
SAP managed connector
The SAP connector currently doesn't support SAP router strings. The on-premises data gateway must exist on a virtual network where the gateway can directly reach the SAP system that you want to connect.
In general, 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 message scenarios, data gateway clusters in failover mode are supported.
Stateful SAP actions don't support data gateway clusters in load-balancing mode. Stateful communications must remain on the same data gateway cluster node. Either use the data gateway in non-cluster mode or in a cluster that's set up for failover only. For example, these actions include the following:
- All actions that specify a Session ID value
- [BAPI] Commit transaction
- [BAPI] Rollback transaction
- [BAPI - RFC] Close stateful session
- [BAPI - RFC] Create stateful session
In the action named [BAPI] Call method in SAP, the auto-commit feature won't commit the BAPI changes if at least one warning exists in the CallBapiResponse object returned by the action. To commit BAPI changes despite any warnings, follow these steps:
- Create a session explicitly using the action named [BAPI - RFC] Create stateful session.
- In the action named [BAPI] Call method in SAP, disable the auto-commit feature.
- Call the action named [BAPI] Commit transaction instead.
IP-based connections to SAP Message Server (load-balanced configuration)
If you specify an IP address to connect to an SAP Message Server, for example, a load balancer, the connection might still fail with an error message similar to "hostname SAPDBSERVER01.example.com unknown". The message server instructs the SAP connector to use a hostname for the connection to the backend SAP Application Server, or the server behind the load balancer. If DNS can't resolve the hostname, the connection fails.
For this problem, the following workarounds or solutions exist:
Make sure that the client making the connection, such as the computer with the on-premises data gateway for the SAP connector or the ISE connector host for the ISE-based SAP connector, can resolve the hostnames returned by the message server.
In the transaction named RZ11, change or add the SAP setting named ms/lg_with_hostname=0.
Problem context or background
SAP upgraded their .NET connector (NCo) to version 3.1, which changed the way that the connector requests connections to backend servers from message servers. The connector now uses a new API for application server resolution by the message server unless you force the connector to use the previous API through the setting named ms/lg_with_hostname=0`. For more information, see SAP KB Article 3305039 - SMLG IP Address setting not considered during Logon Group login.
Prerequisites
An Azure account and subscription. If you don't have an Azure subscription yet, sign up for a free Azure account.
The SAP Application server or SAP Message server that you want to access from Azure Logic Apps.
Set up your SAP server and user account to allow using RFC.
For more information, which includes the supported user account types and the minimum required authorization for each action type (RFC, BAPI, IDoc), review the following SAP note: 460089 - Minimum authorization profiles for external RFC programs.
Your SAP user account needs access to the
RFC_METADATA
function group and the respective function modules for the following operations:Operations Access to function modules RFC actions RFC_GROUP_SEARCH
andDD_LANGU_TO_ISOLA
BAPI actions BAPI_TRANSACTION_COMMIT
,BAPI_TRANSACTION_ROLLBACK
,RPY_BOR_TREE_INIT
,SWO_QUERY_METHODS
, andSWO_QUERY_API_METHODS
IDoc actions IDOCTYPES_LIST_WITH_MESSAGES
,IDOCTYPES_FOR_MESTYPE_READ
,INBOUND_IDOCS_FOR_TID
,OUTBOUND_IDOCS_FOR_TID
,GET_STATUS_FROM_IDOCNR
, andIDOC_RECORD_READ
Read SAP table action Either RFC BBP_RFC_READ_TABLE
orRFC_READ_TABLE
Grant strict minimum access to SAP server for your SAP connection RFC_METADATA_GET
andRFC_METADATA_GET_TIMESTAMP
The logic app workflow from where you want to access your SAP server.
For a Consumption workflow in multitenant Azure Logic Apps, see Multitenant prerequisites.
For a Standard workflow in single-tenant Azure Logic Apps, see Single-tenant prerequisites.
For a Consumption workflow in a Premium-level integration service environment (ISE), see ISE prerequisites.
Note
When you use a Premium-level ISE, use the ISE-native SAP connector, not the SAP managed connector, which doesn't natively run in an ISE. For more information, review the ISE prerequisites.
By default, the SAP built-in connector operations are stateless. To run these operations in stateful mode, see Enable stateful mode for stateless built-in connectors.
To use either the SAP managed or built-in connector trigger named When a message is received, complete the following tasks:
Set up your SAP gateway security permissions or Access Control List (ACL). In the Gateway Monitor (T-Code SMGW) dialog box, which shows the secinfo and reginfo files, open the Goto menu, and select Expert Functions > External Security > Maintenance of ACL Files.
The following permission setting is required:
P TP=LOGICAPP HOST=<on-premises-gateway-server-IP-address> ACCESS=*
This line has the following format:
P TP=<trading-partner-identifier-(program-name)-or-*-for-all-partners> HOST=<comma-separated-list-with-external-host-IP-or-network-names-that-can-register-the-program> ACCESS=<*-for-all-permissions-or-a-comma-separated-list-of-permissions>
If you don't configure the SAP gateway security permissions, you might receive the following error:
Registration of tp Microsoft.PowerBI.EnterpriseGateway from host <host-name> not allowed
For more information, review SAP Note 1850230 - GW: "Registration of tp <program ID> not allowed".
Set up your SAP gateway security logging to help find Access Control List (ACL) issues. For more information, review the SAP help topic for setting up gateway logging.
In the Configuration of RFC Connections (T-Code SM59) dialog box, create an RFC connection with the TCP/IP type. Make sure that the Activation Type is set to Registered Server Program. Set the RFC connection's Communication Type with Target System value to Unicode.
If you use this SAP trigger with the IDOC Format parameter set to FlatFile along with the Flat File Decode action, you have to use the
early_terminate_optional_fields
property in your flat file schema by setting the value totrue
.This requirement is necessary because the flat file IDoc data record that's sent by SAP on the tRFC call
IDOC_INBOUND_ASYNCHRONOUS
isn't padded to the full SDATA field length. Azure Logic Apps provides the flat file IDoc original data without padding as received from SAP. Also, when you combine this SAP trigger with the Flat File Decode action, the schema that's provided to the action must match.
Note
In Consumption and Standard workflows, the SAP managed trigger named When a message is received 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
.In Standard workflows, the SAP built-in trigger named When a message is received uses the Azure Functions trigger instead, and shows only the actual callbacks from SAP.
- For the SAP built-in connector trigger named When a message is received, you have to enable virtual network integration and private ports by following the article at Enabling Service Bus and SAP built-in connectors for stateful Logic Apps in Standard. You can also run the workflow in Visual Studio Code to fire the trigger locally. For Visual Studio Code setup requirements and more information, see Create a Standard logic app workflow in single-tenant Azure Logic Apps using Visual Studio Code. You must also set up the following environment variables on the computer where you install Visual Studio Code:
- WEBSITE_PRIVATE_IP: Set this environment variable value to 127.0.0.1 as the localhost address.
- WEBSITE_PRIVATE_PORTS: Set this environment variable value to two free and usable ports on your local computer, separating the values with a comma (,), for example, 8080,8088.
The message content to send to your SAP server, such as a sample IDoc file. This content must be in XML format and include the namespace of the SAP action that you want to use. You can send IDocs with a flat file schema by wrapping them in an XML envelope.
Network connectivity prerequisites
The SAP system requires network connectivity from the host of the SAP .NET Connector (NCo) library:
For Consumption logic app workflows in multitenant Azure Logic Apps, the on-premises data gateway hosts the SAP .NET Connector (NCo) library. If you use an on-premises data gateway cluster, all nodes of the cluster require network connectivity to the SAP system.
For Standard logic app workflows in single-tenant Azure Logic Apps, the logic app resource hosts the SAP .NET Connector (NCo) library. So, the logic app resource itself must enable virtual network integration, and that virtual network must have network connectivity to the SAP system.
For Consumption logic app workflows in an ISE, the ISE virtual network hosts the SAP .NET Connector (NCo) library.
The SAP system-required network connectivity includes the following servers and services:
SAP Application Server, Dispatcher service (for all Logon types)
Your SAP system can include multiple SAP Application Servers. The host of the SAP .NET Connector (NCo) library requires access to each server and their services.
SAP Message Server, Message service (for Logon type Group)
The Message Server and service will redirect to one or more Application Server's Dispatcher services. The host of the SAP .NET Connector (NCo) library requires access to each server and their services.
SAP Gateway Server, Gateway service
SAP Gateway Server, Gateway secured service
The SAP system-required network connectivity also includes this server and service to use with Secure Network Communications (SNC).
Redirection of requests from Application Server, Dispatcher service to Gateway Server, Gateway service automatically happens within the SAP .NET Connector (NCo) library. This redirection occurs even if only the Application Server, Dispatcher service information is provided in the connection parameters.
If you're using a load balancer in front of your SAP system, you must redirect all the services to their respective servers. For more information about SAP services and ports, review the TCP/IP Ports of All SAP Products.
Note
Make sure you enabled network connectivity from the host of the SAP .NET Connector (NCo) library and that the required ports are open on firewalls and network security groups. Otherwise, you get errors such as partner not reached from the NI (network interface) component and error text such as WSAECONNREFUSED: Connection refused.
SAP NCo client library prerequisites
To use the SAP connector, you have to install the SAP Connector NCo client library for Microsoft .NET 3.1. The following list describes the prerequisites for the SAP NCo client library, based on the workflow where you're using the SAP connector:
Version:
For Consumption logic app workflows that use the on-premises data gateway, make sure that you install the latest 64-bit version, SAP Connector for Microsoft .NET 3.1.3.0 for Windows 64bit (x64). The data gateway runs only on 64-bit systems. Installing the unsupported 32-bit version results in a "bad image" error.
For Standard logic app workflows, you can install the latest 64-bit or 32-bit version for SAP Connector (NCo 3.1) for Microsoft .NET 3.1.3.0 compiled with .NET Framework 4.6.2. However, make sure that you install the version that matches the configuration in your Standard logic app resource. To check the version used by your logic app, follow these steps:
In the Azure portal, open your Standard logic app resource.
On the logic app resource menu, under Settings, select Configuration.
On the Configuration page, select the General settings tab. Under Platform settings, check whether the Platform value is set to 64 Bit or 32 Bit.
Make sure to install the version of the SAP Connector (NCo 3.1) for Microsoft .NET 3.1.3.0 compiled with .NET Framework 4.6.2 that matches your platform configuration.
From the client library's default installation folder, copy the assembly (.dll) files to another location, based on your scenario as follows. Or, optionally, if you're using only the SAP managed connector, when you install the SAP NCo client library, select Global Assembly Cache registration. The ISE zip archive and SAP built-in connector currently doesn't support GAC registration.
For a Consumption workflow that runs in multitenant Azure Logic Apps and uses your on-premises data gateway, copy the following assembly (.dll) files to the on-premises data gateway installation folder, for example, C:\Program Files\On-Premises Data Gateway. The SAP NCo 3.0 client library contains the following assemblies:
- libicudecnumber.dll
- rscp4n.dll
- sapnco.dll
- sapnco_utils.dll
Make sure that you copy the assembly files to the data gateway's installation folder. Otherwise, your SAP connection might fail with the error message, Please check your account info and/or permissions and try again. You can troubleshoot further issues using the .NET assembly binding log viewer. This tool lets you check that your assembly files are in the correct location.
For Standard workflows, copy the following assembly (.dll) files to a location from where you can upload them to your logic app resource or project where you're building your workflow, either in the Azure portal or locally in Visual Studio Code, respectively. The SAP NCo 3.1 client library includes the following assemblies:
- rscp4n.dll
- sapnco.dll
- sapnco_utils.dll
For a Consumption workflow in an ISE, follow the ISE prerequisites instead.
The following relationships exist between the SAP NCo client library, the .NET Framework, the .NET runtime, and the data gateway:
The Microsoft SAP Adapter and the gateway host service both use .NET Framework 4.7.2.
The SAP NCo for .NET Framework 4.0 works with processes that use .NET runtime 4.0 to 4.8.
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.
SNC prerequisites
For Consumption workflows in multitenant Azure Logic Apps that use the on-premises data gateway, and optionally SNC, you must also configure the following settings.
Make sure that your SNC library version and its dependencies are compatible with your SAP environment. To troubleshoot any library compatibility issues, you can use your on-premises data gateway and data gateway logs.
Make sure that you copied the following assembly (.dll) files in the SAP NCo 3.0 client library to the on-premises data gateway's installation folder, for example, C:\Program Files\On-Premises Data Gateway.
- libicudecnumber.dll
- rscp4n.dll
- sapnco.dll
- sapnco_utils.dll
For the SAPGENPSE utility, you must specifically use sapgenpse.exe.
If you provide a Personal Security Environment (PSE) with your connection, you don't need to copy and set up the PSE and SECUDIR for your on-premises data gateway.
If you enable SNC through an external security product, such as sapseculib, Kerberos, or NTLM, make sure that the SNC library exists on the same computer as your data gateway installation. For this task, copy the SNC library's binary files to the same folder as the data gateway installation on your local computer, for example, C:\Program Files\On-Premises Data Gateway.
Note
On the computer with the data gateway installation and SNC library, don't set the environment variables for SNC_LIB and SNC_LIB_64. Otherwise, these variables take precedence over the SNC library value passed through the connector.
To use SNC with single sign-on (SSO), make sure the data gateway service is running as a user who is mapped to an SAP user. To change the default account for the gateway service account, select Change account, and enter the user credentials.
For more information about enabling SNC, review Enable Secure Network Communications (SNC).
Azure Logic Apps environment prerequisites
For a Consumption workflow in multitenant Azure Logic Apps, the SAP managed connector integrates with SAP systems through an on-premises data gateway. For example, in scenarios where your workflow sends a message to the SAP system, the data gateway acts as an RFC client and forwards the requests received from your workflow to SAP. Likewise, in scenarios where your workflow receives a message from SAP, the data gateway acts as an RFC server that receives requests from SAP and forwards them to your workflow.
On a host computer or virtual machine that exists in the same virtual network as the SAP system to which you're connecting, download and install the on-premises data gateway.
The data gateway helps you securely access on-premises data and resources. Make sure to use a supported version of the gateway. If you experience an issue with your gateway, try upgrading to the latest version, which might include updates to resolve your problem.
In the Azure portal, create an Azure gateway resource for your on-premises data gateway installation.
On the same local computer as your on-premises data gateway installation, download and install the latest SAP NCo client library.
For the host computer with your on-premises data gateway installation, configure the network host names and service names resolution.
To use the host names or service names for connections from Azure Logic Apps, you have to set up name resolution for each SAP Application, Message, and Gateway server along with their services:
In the %windir%\System32\drivers\etc\hosts file or in the DNS server that's available to the host computer for your on-premises data gateway installation, set up the network host name resolution.
In the %windir%\System32\drivers\etc\services file, set up the service name resolution.
If you don't intend to use network host names or service names for the connection, you can use host IP addresses and service port numbers instead.
If you don't have a DNS entry for your SAP system, the following example shows a sample entry for the hosts file:
10.0.1.9 sapserver # SAP single-instance system host IP by simple computer name 10.0.1.9 sapserver.contoso.com # SAP single-instance system host IP by fully qualified DNS name
The following list shows a sample set of entries for the services files:
sapdp00 3200/tcp # SAP system instance 00 dialog (application) service port sapgw00 3300/tcp # SAP system instance 00 gateway service port sapmsDV6 3601/tcp # SAP system ID DV6 message service port
Enable Secure Network Communications (SNC)
For a Consumption workflow that runs in multitenant Azure Logic Apps, you can enable SNC for authentication, which applies only when you use the data gateway. Before you start, make sure that you met all the necessary prerequisites and SNC prerequisites.
In the Azure portal, open your Consumption logic app and workflow in the designer.
Add or edit an SAP managed connector operation.
In the SAP connection information box, provide the following required information. The Authentication Type that you select changes the available options.
Note
The SAP Username and SAP Password fields are optional. If you don't provide a username and password, the connector uses the client certificate provided in a later step for authentication.
To enable SNC, in the SAP connection information box, provide the following required information instead:
Parameter Description Use SNC Select the checkbox. SNC Library Enter one of the following values:
- The name for your SNC library, for example, sapsnc.dll
- The relative path to the NCo installation location, for example, .\security\sapsnc.dll
- The absolute path to the NCo installation location, for example, c:\security\sapsnc.dllSNC SSO Select either Logon using the SNC identity or Logon with the username/password provided on RFC level.
Typically, the SNC identity is used to authenticate the caller. You can choose to authenticate with a username and password instead, but this parameter value is still encrypted.SNC My Name In most cases, you can omit this value. The installed SNC solution usually knows its own SNC name. In the case where your solution supports multiple identities, you might have to specify the identity to use for this particular destination or server. SNC Partner Name Enter the name for the backend SNC, for example, p:CN=DV3, OU=LA, O=MS, C=US. SNC Quality of Protection Select the quality of service to use for SNC communication with this particular destination or server. The default value is defined by the backend system. The maximum value is defined by the security product used for SNC. SNC Certificate Enter the base64-encoded public key for the certificate to use for identifying your client to SAP.
Note: - Don't include the PEM header or footer.
- Don't enter the private key for the client certificate here. Your Personal Security Environment (PSE) must contain the matching private key for this certificate and might contain other private certificates. For more information, review the next parameter.PSE Enter your SNC Personal Security Environment (PSE) as a base64-encoded binary.
- Your PSE must contain the private key for the client certificate where the thumbprint matches the public key for the client certificate in the SNC Certificate parameter.
- Although your PSE might contain multiple client certificates, to use different client certificates, create separate workflows instead.
- If you're using more than one SNC client certificate for your Standard logic app resource, you must provide the same PSE for all connections. Your PSE must contain the matching private key for the client certificate for each and all the connections. You must set the SNC Certificate parameter to match the specific private certificate for each connection.To finish creating your connection, select Create.
If the parameters are correct, the connection is created. If there's a problem with the parameters, the connection creation dialog displays an error message. To troubleshoot connection parameter issues, you can use the on-premises data gateway installation and the gateway's local logs.
Convert a binary PSE file into base64-encoded format
Use a PowerShell script, for example:
Param ([Parameter(Mandatory=$true)][string]$psePath, [string]$base64OutputPath) $base64String = [convert]::ToBase64String((Get-Content -path $psePath -Encoding byte)) if ($base64OutputPath -eq $null) { Write-Output $base64String } else { Set-Content -Path $base64OutputPath -Value $base64String Write-Output "Output written to $base64OutputPath" }
Save the script as a pseConvert.ps1 file, and then invoke the script, for example:
.\pseConvert.ps1 -psePath "C:\Temp\SECUDIR\request.pse" -base64OutputPath "connectionInput.txt" Output written to connectionInput.txt
If you don't provide the output path parameter, the script's output to the console contains line breaks. Remove the line breaks in the base 64-encoded string for the connection input parameter.
Set up and test sending IDocs to your workflow from SAP
Follow these steps only for testing your SAP configuration with your logic app workflow. Production environments require additional configuration.
To send IDocs from SAP to your workflow, you need the following minimum configuration:
- Create an RFC destination.
- Create an ABAP connection.
- Create a receiver port.
- Create a sender port.
- Create a logical system partner.
- Create a partner profile.
- Test sending messages.
Create RFC destination
This destination identifies your logic app workflow as the receiver port.
In SAP, open the Configuration of RFC Connections settings. You can 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 RFC Destination, enter a name.
On the Technical Settings tab, for Activation Type, select Registered Server Program.
For Program ID, enter a value. In your SAP server, your workflow's trigger is registered using this identifier.
Important
The SAP Program ID is case-sensitive. Make sure that you consistently use the same case format for your Program ID when you configure your workflow and SAP server. Otherwise, you might receive the following errors in the tRFC Monitor (T-Code SM58) when you attempt to send an IDoc to SAP:
- Function IDOC_INBOUND_ASYNCHRONOUS not found
- Non-ABAP RFC client (partner type ) not supported
For more information from SAP, review the following notes (login required):
On the Unicode tab, for Communication Type with Target System, select Unicode.
Note
SAP .NET Client libraries support only Unicode character encoding. If you get the error Non-ABAP RFC client (partner type) not supported when you send an IDoc from SAP to Azure Logic Apps, check that the Communication Type with Target System value is set to Unicode.
Save your changes.
Register your new Program ID with Azure Logic Apps by creating a logic app workflow that starts with the SAP managed trigger named When a message is received.
That way, when you save your workflow, Azure Logic Apps registers the Program ID on the SAP Gateway.
In your workflow's trigger history, the on-premises data gateway SAP Adapter logs, if applicable, and the SAP Gateway trace logs, check the registration status.
In the SAP Gateway monitor box (T-Code SMGW), under Logged-On Clients, the new registration appears as Registered Server.
To test your connection, under your new RFC Destination, select Connection Test.
Create ABAP connection
This destination identifies your SAP system as the sender port.
In SAP, open the Configuration of RFC Connections settings. You can 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.
In Technical Settings, leave the target host empty to create a local connection to the SAP system.
Save your changes.
To test your connection, select Connection Test.
Create receiver port
In SAP, open the Ports In IDOC processing settings. You can 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.
Create sender port
In SAP, open the Ports In IDOC processing settings. You can 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. Save your changes.
All sender port names must start with the letters SAP, for example, SAPTEST.
In the settings for your new sender port, for RFC destination, enter the identifier for your ABAP connection.
Save your changes.
Create logical system partner
In SAP, open the Change View "Logical Systems": Overview settings. You can use the bd54 transaction code (T-Code).
Accept the following 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.
Create partner profiles
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 resource and workflow.
In SAP, open the Partner profiles settings. You can 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:
Setting Description Partner No. Enter your logical system partner's identifier. Partn. Type Enter LS. 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.
Test sending messages
In SAP, open the Test Tool for IDoc Processing settings. You can use the we19 transaction code (T-Code) with the /n prefix.
Under Template for test, select Via message type. 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 the tool finishes processing, 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.
Create workflows for common SAP scenarios
For the how-to guide to creating workflows for common SAP integration workloads, see the following steps:
- Receive message from SAP
- Receive IDoc packets from SAP
- Send IDocs to SAP
- Generate schemas for artifacts in SAP
Create workflows for advanced SAP scenarios
- Change language headers for sending data to SAP
- Confirm transaction separately and avoid duplicate IDocs
Find extended error logs (Managed connector only)
If you're using the SAP managed connector, you can find full error messages by checking your SAP Adapter's extended logs. You can also enable an extended log file for the SAP connector.
For on-premises data gateway releases from April 2020 and earlier, logs are disabled by default.
For on-premises data gateway releases from June 2020 and later, you can enable gateway logs in the app settings.
The default logging level is Warning.
If you enable Additional logging in the Diagnostics settings of the on-premises data gateway app, the logging level is increased to Informational.
To increase the logging level to Verbose, update the following setting in your configuration file. Typically, the configuration file is located at
C:\Program Files\On-premises data gateway\Microsoft.PowerBI.DataMovement.Pipeline.GatewayCore.dll.config
.<setting name="SapTraceLevel" serializeAs="String"> <value>Verbose</value> </setting>
Set up extended SAP logging in on-premises data gateway (Managed connector only)
If you use an on-premises data gateway for Azure Logic Apps, you can configure an extended log file for the SAP connector. You can use your on-premises data gateway to redirect Event Tracing for Windows (ETW) events into rotating log files that are included in your gateway's logging .zip files.
You can export all of your gateway's configuration and service logs to a .zip file in from the gateway app's settings.
Note
Extended logging might affect your workflow's performance when always enabled. As a best practice, turn off extended log files after you're finished with analyzing and troubleshooting an issue.
Capture ETW events
As an optional advanced logging task, you can directly capture ETW events, and then consume the data in Azure Diagnostics in Event Hubs or collect your data to Azure Monitor Logs. For more information, review the best practices for collecting and storing data.
To work with the resulting ETL files, you can use PerfView, or you can write your own program. The following walkthrough uses PerfView:
In the PerfView menu, select Collect > Collect to capture the events.
In the Additional Provider parameter, enter
*Microsoft-LobAdapter
to specify the SAP provider to capture SAP Adapter events. If you don't specify this information, your trace only includes general ETW events.Keep the other default settings. If you want, you can change the file name or location in the Data File parameter.
Select Start Collection to begin your trace.
After you've reproduced your issue or collected enough analysis data, select Stop Collection.
To share your data with another party, such as Azure support engineers, compress the ETL file.
To view the content of your trace:
In PerfView, select File > Open and select the ETL file you just generated.
In the PerfView sidebar, the Events section under your ETL file.
Under Filter, filter by
Microsoft-LobAdapter
to only view relevant events and gateway processes.
Test your workflow
Based on whether you have a Consumption workflow in multitenant Azure Logic Apps or a Standard workflow in single-tenant Azure Logic Apps, follow the corresponding steps:
If your Consumption logic app resource isn't already enabled, on your logic app menu, select Overview. On the toolbar, select Enable.
On the designer toolbar, select Run Trigger > Run to manually start your workflow.
To trigger your workflow, send a message from your SAP system.
Return to your logic app's Overview pane. Under Runs history, find any new runs for your workflow.
Open the most recent run, which shows a manual run. Find and review the trigger outputs section.
Enable SAP client library (NCo) logging and tracing (built-in connector only)
When you have to investigate any problems with this component, you can set up custom text file-based NCo tracing, which SAP or Microsoft support might request from you. By default, this capability is disabled because enabling this trace might negatively affect performance and quickly consume the application host's storage space.
You can control this tracing capability at the application level by adding the following settings:
In the Azure portal, open your Standard logic app resource.
On the logic app menu, under Settings, select Environment variables to review the application settings.
On the Environment variables page, on the App settings tab, add the following application settings:
SAP_RFC_TRACE_DIRECTORY: The directory where to store the NCo trace files, for example, C:\home\LogFiles\NCo.
SAP_RFC_TRACE_LEVEL: The NCo trace level with Level4 as the suggested value for typical verbose logging. SAP or Microsoft support might request that you set a different trace level.
Note
For Standard logic app workflows that use runtime version 1.69.0 or later, you can enable logging for multiple trace levels by separating each trace level with a comma (,).
To find your workflow's runtime version, follow these steps:
- In the Azure portal, on your workflow menu, select Overview.
- In the Essentials section, find the Runtime Version property.
SAP_CPIC_TRACE_LEVEL: The Common Programming Interface for Communication (CPI-C) trace level with Verbose as the suggested value for typical verbose logging. SAP or Microsoft support might request that you set a different trace level.
For more information about adding application settings, see Edit host and app settings for Standard logic app workflows.
Save your changes. This step restarts the application.
Trace levels available
NCo Trace Levels
Value | Description |
---|---|
Level1 | The level for tracing remote function calls. |
Level2 | The level for tracing remote function calls and public API method calls. |
Level3 | The level for tracing remote function calls, public API method calls, and internal API method calls. |
Level4 | The level for tracing remote function calls, public API method calls, internal API method calls, hex dumps for the RFC protocol, and network-related information. |
Locking | Writes data to the trace files that shows when threads request, acquire, and release locks on objects. |
Metadata | Traces the metadata involved in a remote function call for each call. |
None | The level for suppressing all trace output. |
ParameterData | Traces the container data sent and received during each remote function call. |
Performance | Writes data to the trace files that can help with analyzing performance issues. |
PublicAPI | Traces most methods of the public API, except for getters, setters, or related methods. |
InternalAPI | Traces most methods of the internal API, except for getters, setters, or related methods. |
RemoteFunctionCall | Traces remote function calls. |
RfcData | Traces the bytes sent and received during each remote function call. |
SessionProvider | Traces all methods of the currently used implementation of ISessionProvider. |
SetValue | Writes information to the trace files regarding values set for parameters of functions, or fields of structures or tables. |
CPIC Trace Levels
Value | Description |
---|---|
Off | No logging |
Basic | Basic logging |
Verbose | Verbose logging |
VerboseWithData | Verbose logging with all server response dump |
View the trace
On Standard logic app resource menu, under Development Tools, select Advanced Tools > Go.
On the Kudu toolbar, select Debug Console > CMD.
Browse to the folder for the application setting named $SAP_RFC_TRACE_DIRECTORY.
A new folder named NCo, or whatever folder name that you used, appears for the application setting value, C:\home\LogFiles\NCo, that you set earlier.
Open the $SAP_RFC_TRACE_DIRECTORY folder, which contains the following :
NCo trace logs: A file named dev_nco_rfc.log, one or multiple files named nco_rfc_NNNN.log, and one or multiple files named nco_rfc_NNNN.trc files where NNNN is a thread identifier.
CPIC trace logs: One or multiple files named nco_cpic_NNNN.trc files where NNNN is thread identifier.
To view the content in a log or trace file, select the Edit button next to a file.
Note
If you download a log or trace file that your logic app workflow opened and is currently in use, your download might result in an empty file.
Enable SAP Common Crypto Library (CCL) tracing (built-in connector only)
If you have to investigate any problems with the crypto library while using SNC authentication, you can set up custom text file-based CCL tracing. You can use these CCL logs to troubleshoot SNC authentication issues, or share them with Microsoft or SAP support, if requested. By default, this capability is disabled because enabling this trace might negatively affect performance and quickly consume the application host's storage space.
You can control this tracing capability at the application level by adding the following settings:
In the Azure portal, open your Standard logic app resource.
On Standard logic app resource menu, under Development Tools, select Advanced Tools > Go.
On the Kudu toolbar, select Debug Console > CMD.
Browse to a location under C:\home\site\wwwroot, and create a text file, for example: CCLPROFILE.txt.
For more information about logging parameters, see Tracing > SAP NOTE 2338952. The following sample provides an example tracing configuration:
ccl/trace/directory=C:\home\LogFiles\CCLLOGS ccl/trace/level=4 ccl/trace/rotatefilesize=10000000 ccl/trace/rotatefilenumber=10
On the logic app menu, under Settings, select Environment variables to review the application settings.
On the Environment variables page, on the App settings tab, add the following application setting:
CCL_PROFILE: The directory where CCLPROFILE.txt was created, for example, C:\home\site\wwwroot\CCLPROFILE.txt.
Save your changes. This step restarts the application.
View the trace
On Standard logic app resource menu, under Development Tools, select Advanced Tools > Go.
On the Kudu toolbar, select Debug Console > CMD.
Browse to the folder for the $ccl/trace/directory parameter, which is from the CCLPROFILE.txt file.
Usually, the trace files are named sec-Microsoft.Azure.Work-$processId.trc and sec-sapgenpse.exe-$processId.trc.
Your logic app workflow performs SNC authentication as a two-step process:
Your logic app workflow invokes sapgenpse.exe to generate a cred_v2 file from the PSE file.
You can find the traces related to this step in a file named sec-sapgenpse.exe-$processId.trc.
Your logic app workflow authenticates access to your SAP server by consuming the generated cred_v2 file, with the SAP client library invoking the common crypto library.
You can find the traces related to this step in a file named sec-Microsoft.Azure.Work-$processId.trc.
Send SAP telemetry for on-premises data gateway to Azure Application Insights
With the August 2021 update for the on-premises data gateway, SAP connector operations can send telemetry data from the SAP NCo client library and traces from the Microsoft SAP Adapter to Application Insights, which is a capability in Azure Monitor. This telemetry primarily includes the following data:
Metrics and traces based on SAP NCo metrics and monitors.
Traces from Microsoft SAP Adapter.
Metrics and traces from SAP NCo client library
SAP NCo-based metrics are numeric values that might or might not vary over a time period, based on the usage and availability of resources on the on-premises data gateway. You can use these metrics to better understand system health and to create alerts about the following activities:
- System health decline.
- Unusual events.
- Heavy system load.
This information is sent to the Application Insights table named customMetrics. By default, metrics are sent at 30-second intervals.
SAP NCo-based traces include text information that's used with metrics. This information is sent to the Application Insights table named traces. By default, traces are sent at 10-minute intervals.
SAP NCo metrics and traces are based on SAP NCo metrics, specifically the following NCo classes:
- RfcDestinationMonitor.
- RfcConnectionMonitor.
- RfcServerMonitor.
- RfcRepositoryMonitor.
For more information about the metrics that each class provides, see the SAP NCo documentation (sign-in required).
Set up SAP telemetry for Application Insights
Before you can send SAP telemetry for your gateway installation to Application Insights, you need to have created and set up your Application Insights resource. For more information, review the following documentation:
To enable sending SAP telemetry to Application insights, follow these steps:
Download the NuGet package for Microsoft.ApplicationInsights.EventSourceListener.dll from this location: https://www.nuget.org/packages/Microsoft.ApplicationInsights.EventSourceListener/2.14.0.
Add the downloaded file to your on-premises data gateway installation directory, for example, C:\Program Files\On-Premises Data Gateway.
In your on-premises data gateway installation directory, check that the Microsoft.ApplicationInsights.dll file has the same version number as the Microsoft.ApplicationInsights.EventSourceListener.dll file that you added. The gateway currently uses version 2.14.0.
In the ApplicationInsights.config file, add your Application Insights instrumentation key by uncommenting the line with the
<InstrumentationKey></InstrumentationKey>
element. Replace the placeholder, your-Application-Insights-instrumentation-key, with your key, for example:<?xml version="1.0" encoding="utf-8"?> <ApplicationInsights schemaVersion="2014-05-30" xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings"> <!-- Uncomment this element and insert your Application Insights key to receive ETW telemetry about your gateway <InstrumentationKey>*your-instrumentation-key-placeholder*</InstrumentationKey> --> <TelemetryModules> <Add Type="Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule, Microsoft.ApplicationInsights"> <IsHeartbeatEnabled>false</IsHeartbeatEnabled> </Add> <Add Type="Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule, Microsoft.ApplicationInsights.EventSourceListener"> <Sources> <Add Name="Microsoft-LobAdapter" Level="Verbose" /> </Sources> </Add> </TelemetryModules> </ApplicationInsights>
In the ApplicationInsights.config file, you can change the required traces
Level
value for your SAP connector operations, per your requirements, for example:<Add Type="Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule, Microsoft.ApplicationInsights.EventSourceListener"> <Sources> <Add Name="Microsoft-LobAdapter" Level="Verbose" /> </Sources> </Add>
For more information, review the following documentation:
Level
values: EventLevel Enum
After you apply your changes, restart the on-premises data gateway service.
Review metrics in Application Insights
After your SAP operations run in your logic app workflow, you can review the telemetry that was sent to Application Insights.
In the Azure portal, open your Application Insights resource.
On the resource menu, under Monitoring, select Logs.
The following screenshot shows the Azure portal with Application Insights, which is open to the Logs pane:
On the Logs pane, you can create a query using the Kusto Query Language (KQL) that's based on your specific requirements.
You can use a query pattern similar to the following example query:
customMetrics | extend DestinationName = tostring(customDimensions["DestinationName"]) | extend MetricType = tostring(customDimensions["MetricType"]) | where customDimensions contains "RfcDestinationMonitor" | where name contains "MaxUsedCount"
After you run your query, review the results.
The following screenshot shows the example query's metrics results table:
MaxUsedCount is "The maximal number of client connections that were simultaneously used by the monitored destination." as described in the SAP NCo documentation (sign-in required). You can use this value to understand the number of simultaneously open connections.
The valueCount column shows 2 for each reading because metrics are generated at 30-second intervals. Application Insights aggregates these metrics by the minute.
The DestinationName column contains a character string that is a Microsoft SAP Adapter internal name.
To better understand this Remote Function Call (RFC) destination, use this value with
traces
, for example:customMetrics | extend DestinationName = tostring(customDimensions["DestinationName"]) | join kind=inner (traces | extend DestinationName = tostring(customDimensions["DestinationName"]), AppServerHost = tostring(customDimensions["AppServerHost"]), SncMode = tostring(customDimensions["SncMode"]), SapClient = tostring(customDimensions["Client"]) | where customDimensions contains "RfcDestinationMonitor" ) on DestinationName , $left.DestinationName == $right.DestinationName | where customDimensions contains "RfcDestinationMonitor" | where name contains "MaxUsedCount" | project AppServerHost, SncMode, SapClient, name, valueCount, valueSum, valueMin, valueMax
You can also create metric charts or alerts using those capabilities in Application Insights, for example:
Traces from Microsoft SAP Adapter
You can use traces sent from Microsoft SAP Adapter for issue post-analysis and to find any existing internal system errors that might or might not surface from SAP connector operations. These traces have message
set to "n\a"
because they come from an earlier event source framework that predates Application Insights, for example:
traces
| where message == "n/a"
| where severityLevel > 0
| extend ActivityId = tostring(customDimensions["ActivityId"])
| extend fullMessage = tostring(customDimensions["fullMessage"])
| extend shortMessage = tostring(customDimensions["shortMessage"])
| where ActivityId contains "8ad5952b-371e-4d80-b355-34e28df9b5d1"
The following screenshot shows the example query's traces results table: