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 multi-tenant Azure.

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.

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 connector gallery under Runtime > Shared. For more information, review the following documentation: - SAP managed connector reference - 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 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.

  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). 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:

  1. Create a session explicitly using the action named [BAPI - RFC] Create stateful session.
  2. In the action named [BAPI] Call method in SAP, disable the auto-commit feature.
  3. 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, 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 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 and DD_LANGU_TO_ISOLA
    BAPI actions	BAPI_TRANSACTION_COMMIT, BAPI_TRANSACTION_ROLLBACK, RPY_BOR_TREE_INIT, SWO_QUERY_METHODS, and SWO_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, and IDOC_RECORD_READ
    Read SAP table action	Either RFC BBP_RFC_READ_TABLE or RFC_READ_TABLE
    Grant strict minimum access to SAP server for your SAP connection	RFC_METADATA_GET and RFC_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.

• 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 to true.

    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.

  • 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 HTTP DELETE 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 uses PATCH as the HTTP method, not DELETE.

    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.

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.

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:

    1. In the Azure portal, open your Standard logic app resource.

    2. On the logic app resource menu, under Settings, select Configuration.

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

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

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

Azure Logic Apps environment prerequisites

Enable Secure Network Communications (SNC)

Convert a binary PSE file into base64-encoded format

1. 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"
   } 
   

2. 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:

1. Create an RFC destination.
2. Create an ABAP connection.
3. Create a receiver port.
4. Create a sender port.
5. Create a logical system partner.
6. Create a partner profile.
7. Test sending messages.

Create RFC destination

This destination identifies your logic app workflow as the receiver port.

1. In SAP, open the Configuration of RFC Connections settings. You can use the sm59 transaction code (T-Code) with the /n prefix.

2. Select TCP/IP Connections > Create.

3. Create a new RFC destination with the following settings:

   1. For RFC Destination, enter a name.

   2. On the Technical Settings tab, for Activation Type, select Registered Server Program.

   3. 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):

      • https://launchpad.support.sap.com/#/notes/2399329
      • https://launchpad.support.sap.com/#/notes/353597

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

4. Save your changes.

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

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

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

1. In SAP, open the Configuration of RFC Connections settings. You can use the sm59 transaction code (T-Code) with the /n prefix.

2. Select ABAP Connections > Create.

3. For RFC Destination, enter the identifier for your test SAP system.

4. In Technical Settings, leave the target host empty to create a local connection to the SAP system.

5. Save your changes.

6. To test your connection, select Connection Test.

Create receiver port

1. In SAP, open the Ports In IDOC processing settings. You can use the we21 transaction code (T-Code) with the /n prefix.

2. Select Ports > Transactional RFC > Create.

3. In the settings box that opens, select own port name. For your test port, enter a Name. Save your changes.

4. In the settings for your new receiver port, for RFC destination, enter the identifier for your test RFC destination.

5. Save your changes.

Create sender port

1. In SAP, open the Ports In IDOC processing settings. You can use the we21 transaction code (T-Code) with the /n prefix.

2. Select Ports > Transactional RFC > Create.

3. In the settings box that opens, select own port name.

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

5. In the settings for your new sender port, for RFC destination, enter the identifier for your ABAP connection.

6. Save your changes.

Create logical system partner

1. In SAP, open the Change View "Logical Systems": Overview settings. You can use the bd54 transaction code (T-Code).

2. Accept the following warning message that appears: Caution: The table is cross-client

3. Above the list that shows your existing logical systems, select New Entries.

4. For your new logical system, enter a Log.System identifier and a short Name description. Save your changes.

5. When the Prompt for Workbench appears, create a new request by providing a description, or if you already created a request, skip this step.

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

1. In SAP, open the Partner profiles settings. You can use the we20 transaction code (T-Code) with the /n prefix.

2. Under Partner Profiles, select Partner Type LS > Create.

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

4. Save your changes.

   If you haven't created the logical system partner, you get the error, Enter a valid partner number.

5. In your partner profile's settings, under Outbound parmtrs., select Create outbound parameter.

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

7. Save your changes.

Test sending messages

1. In SAP, open the Test Tool for IDoc Processing settings. You can use the we19 transaction code (T-Code) with the /n prefix.

2. Under Template for test, select Via message type. Enter your message type, for example, CREMAS. Select Create.

3. Confirm the Which IDoc type? message by selecting Continue.

4. Select the EDIDC node. Enter the appropriate values for your receiver and sender ports. Select Continue.

5. Select Standard Outbound Processing.

6. To start outbound IDoc processing, select Continue.

   When the tool finishes processing, the IDoc sent to SAP system or external program message appears.

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

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:

1. In the PerfView menu, select Collect > Collect to capture the events.

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

3. Keep the other default settings. If you want, you can change the file name or location in the Data File parameter.

4. Select Start Collection to begin your trace.

5. After you've reproduced your issue or collected enough analysis data, select Stop Collection.

6. To share your data with another party, such as Azure support engineers, compress the ETL file.

7. To view the content of your trace:

   1. In PerfView, select File > Open and select the ETL file you just generated.

   2. In the PerfView sidebar, the Events section under your ETL file.

   3. 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:

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:

1. In the Azure portal, open your Standard logic app resource.

2. On the logic app menu, under Settings, select Environment variables to review the application settings.

3. 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:

     1. In the Azure portal, on your workflow menu, select Overview.
     2. 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.

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

1. On Standard logic app resource menu, under Development Tools, select Advanced Tools > Go.

2. On the Kudu toolbar, select Debug Console > CMD.

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

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

5. 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:

1. In the Azure portal, open your Standard logic app resource.

2. On Standard logic app resource menu, under Development Tools, select Advanced Tools > Go.

3. On the Kudu toolbar, select Debug Console > CMD.

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

5. On the logic app menu, under Settings, select Environment variables to review the application settings.

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

7. Save your changes. This step restarts the application.

View the trace

1. On Standard logic app resource menu, under Development Tools, select Advanced Tools > Go.

2. On the Kudu toolbar, select Debug Console > CMD.

3. 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:

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

   2. 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:

• Create an Application Insights resource (classic)

• Workspace-based Application Insights resources

To enable sending SAP telemetry to Application insights, follow these steps:

1. Download the NuGet package for Microsoft.ApplicationInsights.EventSourceListener.dll from this location: https://www.nuget.org/packages/Microsoft.ApplicationInsights.EventSourceListener/2.14.0.

2. Add the downloaded file to your on-premises data gateway installation directory, for example, C:\Program Files\On-Premises Data Gateway.

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

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

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

   • EventSource tracking

   • EventSource events

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

1. In the Azure portal, open your Application Insights resource.

2. 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:

   

3. 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"
   

4. 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:

Next steps

• Create example workflows for common SAP scenarios