SAP IDoc Connector Guide > SAP IDoc connections > Creating an SAP IDoc connection
  

Creating an SAP IDoc connection

You can create an SAP IDoc connection to read data from or write data to SAP through IDocs.
    1In Application Integration, click New > App Connections > App Connection > Create.
    The Connection page appears.
    2Select SAP IDoc as the connection type.
    3Enter a name and description for the connection.
    4Select a runtime environment on which the connection must run.
    5 Enter the SAP IDoc connection properties.
    The OData-Enabled option is not applicable to the SAP IDoc connection.
    6Test the connection.
    7Save and publish the connection.
    Click the Metadata tab to view the IDoc metadata that the connection accesses in the SAP system.

Basic connection properties

When you select SAP IDoc as the connection type, you can configure the IDoc-specific connection properties on the connection creation page.
To create the SAP IDoc connection, configure the following properties on the Properties tab of the connection creation page:
Property
Description
Name
Enter a unique name for the connection that identifies it in the Process Designer.
The name must be unique within the organization. It can contain alphanumeric characters, spaces, and the following special characters: _ . + -,
Maximum length is 255 characters.
Location
The location of the project or folder where you want to save the connection. Click Browse to select a location.
If the Explore page is currently active and a project or folder is selected, the default location for the connection is the selected project or folder. Otherwise, the default location is the location of the most recently saved asset.
Description
Optional. Description of the connection. Maximum length is 4000 characters.
Type
Required. The type of connection you want to use for the connector or service connector. Select SAP IDoc.
Runtime Environment
Required. The run-time environment for the connection. You can run the connection on a Secure Agent group or a Secure Agent machine.
Connection Test
Indicates whether the connection test was successful or not. By default, the property displays the results of the connection test.
OData-Enabled
Not supported for SAP IDoc Connector.
Use Secret Vault
Stores sensitive credentials for this connection in the secrets manager that is configured for your organization.
This property appears only if secrets manager is set up for your organization.
When you enable the secret vault in the connection, you can select which credentials the Secure Agent retrieves from the secrets manager. If you don't enable this option, the credentials are stored in the repository or on a local Secure Agent, depending on how your organization is configured.
For information about how to configure and use a secrets manager, see "Secrets manager configuration" in the Administrator help.
Along with these basic properties, you must define the properties depending on the authentication type. You must also configure the event source properties and event target properties for the SAP IDoc connection. After you publish the SAP IDoc connection, the Metadata tab displays the generated process objects.

SAP server connection types

You can configure application server, application server Secure Network Communications (SNC), load balancing server, and load balancing server SNC connection types to access SAP IDocs.
Select the required connection type, and configure the connection-specific parameters.

Application server connection

The application server connection is the default type and requires your SAP client details.
The following table describes the connection properties for an application server connection:
Property
Description
User Name
The user name to connect to the SAP system.
Password
The password to connect to the SAP system.
Client
The client number of the SAP application server.
Language
The language code of the SAP application server.
Application Server
The host name or IP address of the SAP application server.
System Number
The system number of the SAP application server.
RFC Trace
The RFC trace records the logs in the trace file.
Additional Parameters
Optional. Enter a list of additional parameters to connect to the SAP system. Configure multiple parameters as key-value pairs separated by semicolons.
Use the following format:
<parameter name1>=<value1>;<parameter name2>=<value2>;<parameter name3>=<value3>....
The following table describes the listener connection properties for an application server connection:
Property
Description
Program ID
The ID of the SAP program. The Program ID must be the same as the Program ID for the logical system that you define in the SAP system to send or receive IDocs.
Gateway Host
The host name of the SAP gateway.
Gateway Server
The server name of the SAP gateway.
The following table describes the reader properties for an application server connection:
Property
Description
Idle Time
Optional. The number of seconds that the Secure Agent waits for IDocs to arrive before it stops reading from the SAP source.
Default is -1, means it reads continuously without stopping.
Connection Pool Size
Optional. The maximum number of simultaneous connections that can be maintained for SAP communication. Default is 2.
Minimum Worker Threads
Optional. The minimum number of active worker threads available for processing the IDoc requests. Default is 5.
Gateway Thread Count
Optional. The number of dedicated gateway threads to handle communication between the SAP gateway and Application Integration. Default is 5.
Maximum Worker Threads
Optional. The maximum number of threads to process SAP IDoc requests in parallel. Default is 50.
Startup Delay
Optional. The number of seconds that the connector must wait before processing IDocs. Default is 30,000.
Trace Logging Level
Optional. Determines the level of detail to be written to the activity log for error and status messages. Default is 1.
In the Custom Attributes section, enter the filters for the Search Filter Options property to read the IDoc metadata. You can separate multiple filter options with a comma. For more information about the Search Filter Options property, see Search filter.

Application server SNC connection

The application server SNC connection requires your SAP client details, the Secure Agent PSE certificate name, the SAP server PSE certificate name, and the path to the X509 certificate file.
For more information, see the How-To article Configure the SAP Secure Network Communication Protocol.
The following table describes the basic connection properties for an application server SNC connection:
Property
Description
User Name
The user name to connect to the SAP system.
Password
The password to connect to the SAP system.
Client
The client number of the SAP application server.
Language
The language code of the SAP application server.
Application Server
The host name or IP address of the SAP application server.
System Number
The system number of the SAP application server.
RFC Trace
The RFC trace records the logs in the trace file.
SNC My Name
Optional. The Personal Security Environment (PSE) or certificate name generated for the Secure Agent.
SNC Partner Name
Optional. The server PSE or certificate name generated on the SAP server.
SNC Quality of Protection (QoP)
Optional. The level of protection applied to a communication path when you create an SAP SNC connection.
Select one of the following options from the list:
  • - 1 - Apply authentication only
  • - 2 - Apply authentication and integrity protection
  • - 3 - Apply authentication, integrity, and privacy protection (encryption)
  • - 8 - Apply global default protection (usually 3)
  • - 9 - Apply the maximum protection
Default is 3 - Apply authentication, integrity, and privacy protection (encryption).
SNC Cryptographic Library Path
Optional. The path to the SNC cryptographic library.
Use X509 Certificate
Optional. Select this option to use an X509 certificate to log in with SNC encryption.
If you don't select this option, you need to enter your SAP user name in the X509 Certificate Path or SAP Username property.
Default is disabled.
X509 Certificate Path or User Name
Optional. The path and file name of the X509 certificate file.
If the X509 certificate file name is abc.crt and the path is \root\<folder name>, enter both the path and file name in the following format:
\root\<folder name>\abc.crt
If you select to use the X509 certificate, you don't need to enter the SAP user name.
If you don't want to use the X509 certificate, enter the SAP user name for which SNC is configured in the SAP server.
Additional Parameters
Optional. Enter a list of additional parameters to connect to the SAP system. Configure multiple parameters as key-value pairs separated by semicolons.
Use the following format:
<parameter name1>=<value1>;<parameter name2>=<value2>;<parameter name3>=<value3>....
The following table describes the listener connection properties for an application server SNC connection:
Property
Description
Program ID
The ID of the SAP program. The Program ID must be the same as the Program ID for the logical system that you define in the SAP system to send or receive IDocs.
Gateway Host
The host name of the SAP gateway.
Gateway Server
The server name of the SAP gateway.
The following table describes the reader properties for an application server SNC connection:
Property
Description
Idle Time
Optional. The number of seconds that the Secure Agent waits for IDocs to arrive before it stops reading from the SAP source.
Default is -1, means it reads continuously without stopping.
Connection Pool Size
Optional. The maximum number of simultaneous connections that can be maintained for SAP communication. Default is 2.
Minimum Worker Threads
Optional. The minimum number of active worker threads available for processing the IDoc requests. Default is 5.
Gateway Thread Count
Optional. The number of dedicated gateway threads to handle communication between the SAP gateway and Application Integration. Default is 5.
Maximum Worker Threads
Optional. The maximum number of threads to process SAP IDoc requests in parallel. Default is 50.
Startup Delay
Optional. The number of seconds that the connector must wait before processing IDocs. Default is 30,000.
Trace Logging Level
Optional. Determines the level of detail to be written to the activity log for error and status messages. Default is 1.
In the Custom Attributes section, enter the filters for the Search Filter Options property to read the IDoc metadata. You can separate multiple filter options with a comma. For more information about the Search Filter Options property, see Search filter.

Load balancing server connection

Create a load balancing server connection when you want to connect to the SAP system with the least load at run time. You must provide your SAP client details and the message server group name.
The following table describes the basic connection properties for a load balancing server connection:
Property
Description
User Name
The user name to connect to the SAP system.
Password
The password to connect to the SAP system.
Client
The client number of the SAP application server.
Language
The language code of the SAP application server.
Message Server
The host name or IP address of the SAP message server.
System ID
The system ID of the SAP message server.
Group
The name of the SAP logon group through which you want to connect.
For example, PUBLIC.
RFC Trace
The RFC trace records the logs in the trace file.
Additional Parameters
Optional. Enter a list of additional parameters to connect to the SAP system. Configure multiple parameters as key-value pairs separated by semicolons.
Use the following format:
<parameter name1>=<value1>;<parameter name2>=<value2>;<parameter name3>=<value3>....
The following table describes the listener connection properties for a load balancing server connection:
Property
Description
Program ID
The ID of the SAP program. The Program ID must be the same as the Program ID for the logical system that you define in the SAP system to send or receive IDocs.
Gateway Host
The host name of the SAP gateway.
Gateway Server
The server name of the SAP gateway.
The following table describes the reader properties for a load balancing server connection:
Property
Description
Idle Time
Optional. The number of seconds that the Secure Agent waits for IDocs to arrive before it stops reading from the SAP source.
Default is -1, means it reads continuously without stopping.
Connection Pool Size
Optional. The maximum number of simultaneous connections that can be maintained for SAP communication. Default is 2.
Minimum Worker Threads
Optional. The minimum number of active worker threads available for processing the IDoc requests. Default is 5.
Gateway Thread Count
Optional. The number of dedicated gateway threads to handle communication between the SAP gateway and Application Integration. Default is 5.
Maximum Worker Threads
Optional. The maximum number of threads to process SAP IDoc requests in parallel. Default is 50.
Startup Delay
Optional. The number of seconds that the connector must wait before processing IDocs. Default is 30,000.
Trace Logging Level
Optional. Determines the level of detail to be written to the activity log for error and status messages. Default is 1.
In the Custom Attributes section, enter the filters for the Search Filter Options property to read the IDoc metadata. You can separate multiple filter options with a comma. For more information about the Search Filter Options property, see Search filter.

Load balancing server SNC connection

Create a load balancing server SNC connection when you want to use the SNC protocol to connect to the SAP system with the least load at run time.
You must provide your SAP client details, the message server group name, the Secure Agent PSE certificate name, the SAP server PSE certificate name, and the path to the X509 certificate file.
For more information, see the How-To article Configure the SAP Secure Network Communication Protocol.
The following table describes the basic connection properties for a load balancing server SNC connection:
Property
Description
User Name
The user name to connect to the SAP system.
Password
The password to connect to the SAP system.
Client
The client number of the SAP application server.
Language
The language code of the SAP application server.
Message Server
The host name or IP address of the SAP application server.
System ID
The system ID of the SAP message server.
Group
Optional. The name of the SAP logon group through which you want to connect.
For example, PUBLIC.
RFC Trace
Optional. The RFC trace records the logs in the trace file.
SNC My Name
Optional. The Personal Security Environment (PSE) or certificate name generated for the Secure Agent.
SNC Partner Name
Optional. The server PSE or certificate name generated on the SAP server.
SNC Quality of Protection QoP*
Optional. The level of protection applied to a communication path when you create an SAP SNC connection.
Select one of the following options from the list:
  • - 1 - Apply authentication only
  • - 2 - Apply authentication and integrity protection
  • - 3 - Apply authentication, integrity, and privacy protection (encryption)
  • - 8 - Apply global default protection (usually 3)
  • - 9 - Apply the maximum protection
Default is 3 - Apply authentication, integrity, and privacy protection (encryption).
SNC Cryptographic Library Path
Optional. The path to the SNC cryptographic library.
Use X509 Certificate
Optional. Select this option to use an X509 certificate to log in with SNC encryption.
If you don't select this option, you need to enter your SAP user name in the X509 Certificate Path or SAP Username property.
Default is disabled.
X509 Certificate Path or User Name
Optional. The path and file name of the X509 certificate file.
If the X509 certificate file name is abc.crt and the path is \root\<folder name>, enter both the path and file name in the following format:
\root\<folder name>\abc.crt
If you select to use the X509 certificate, you don't need to enter the SAP user name.
If you don't want to use the X509 certificate, enter the SAP user name for which SNC is configured in the SAP server.
Additional Parameters
Optional. Enter a list of additional parameters to connect to the SAP system. Configure multiple parameters as key-value pairs separated by semicolons.
Use the following format:
<parameter name1>=<value1>;<parameter name2>=<value2>;<parameter name3>=<value3>....
The following table describes the listener connection properties for a load balancing server SNC connection:
Property
Description
Program ID
The ID of the SAP program. The Program ID must be the same as the Program ID for the logical system that you define in the SAP system to send or receive IDocs.
Gateway Host
The host name of the SAP gateway.
Gateway Server
The server name of the SAP gateway.
The following table describes the reader properties for a load balancing server SNC connection:
Property
Description
Idle Time
Optional. The number of seconds that the Secure Agent waits for IDocs to arrive before it stops reading from the SAP source.
Default is -1, means it reads continuously without stopping.
Connection Pool Size
Optional. The maximum number of simultaneous connections that can be maintained for SAP communication. Default is 2.
Minimum Worker Threads
Optional. The minimum number of active worker threads available for processing the IDoc requests. Default is 5.
Gateway Thread Count
Optional. The number of dedicated gateway threads to handle communication between the SAP gateway and Application Integration. Default is 5.
Maximum Worker Threads
Optional. The maximum number of threads to process SAP IDoc requests in parallel. Default is 50.
Startup Delay
Optional. The number of seconds that the connector must wait before processing IDocs. Default is 30,000.
Trace Logging Level
Optional. Determines the level of detail to be written to the activity log for error and status messages. Default is 1.
In the Custom Attributes section, enter the filters for the Search Filter Options property to read the IDoc metadata. You can separate multiple filter options with a comma. For more information about the Search Filter Options property, see Search filter.

Search filter

You must enter the filters to read the IDoc metadata. The event used in a process is an object that contains a process object with a payload representing the IDoc message. The message consists of two main parts:
When you use specific IDoc types like MATMAS05, configure a search filter in the custom attributes section to represent the IDoc type format. The search filter uses the syntax to specify the IDoc type, message type, and extension type.
For example, configure the search filters as follows:
{
"searchFilter": [
{ "IDoctype": "MATMAS05",
"MessageType": "MATMAS",
"extType": ""
}
]
}
Including this filter ensures that when you publish the connection, metadata specific to that IDoc type is fetched automatically.
Handling multiple IDoc types in a single listener
If the listener receives multiple IDoc types on the same connection, such as MATMAS05 and MATMAS07, specify multiple search filters to fetch the metadata for all these types simultaneously.
For example, the search filter would appear as:
{
"searchFilter": [
{
"IDoctype": "MATMAS05",
"MessageType": "MATMAS",
"extType": ""
},
{
"IDoctype": "MATMAS07",
"MessageType": "MATMAS",
"extType": ""
}
]
}
With this configuration, you fetch metadata for both MATMAS05 and MATMAS07, enabling the listener to process both the IDoc types.
At the message structure level, the Headers remain consistent with the same keys regardless of the IDoc type. The Body is a string that can represent different IDoc types, such as MATMAS05 and MATMAS07, depending on the SAP settings, allowing you to handle multiple IDoc message formats.

Event source properties

You define an SAP IDoc event source to read data from SAP through IDocs and consume events from SAP IDoc listeners.
For each SAP IDoc connection you create, you can add only one event source. An event source serves as a start event that listens to or monitors a specified SAP IDoc queue for new messages. After you define an event source for an SAP IDoc connection, you must publish the connection only on a Secure Agent. You use the event source in a process to consume messages from a queue as process objects. Then, you deploy the process on the same Secure Agent where you published the SAP IDoc connection.
To create an event source in an SAP IDoc connection, click Add Event Source on the Event Sources tab. Select the event source type as Event Source.
The following image shows the event source properties:
The list of event source properties you can configure in a SAP IDoc connection.
The following table describes the basic event source properties that you can configure:
Properties
Description
Name
The event source name that appears in the Process Designer. The name must be unique for the connection.You can change this property after you create the connection. The name cannot exceed 128 characters, contain spaces, or contain the following special characters:
~ ` ! $ % ^ & * ( ) - + = { [ } ] | \ : ; " ' < , > . ? /
Description
Optional. Description for the event source that appears in the Process Designer.
The description cannot exceed 4,000 characters.
Enabled
Select Yes to make the event source available immediately after it is published.
Select No to disable the event source until you are ready to use it.
Default is Yes.
The following table describes the event source properties that you can configure:
Properties
Description
Object Name
The name of the object from which you want to read messages.
Object Path
Optional. The path of the object from which you want to read messages.

Event target properties

Create an event target to publish or write SAP IDoc messages.
For each SAP IDoc connection you create, you can add only one event target that specifies an operation and call the event target from a process to send messages to an SAP IDoc exchange.
To create an event target in an SAP IDoc connection, click Add Event Target on the Event Targets tab. Select the event source type as Event Target.
The following image shows the event target properties:
The list of event target properties you can configure in a SAP IDoc connection.
The following table describes the basic target properties that you can configure:
Properties
Description
Name
The event target name that appears in the Process Designer. The name must be unique for the connection.
The name cannot exceed 128 characters, contain spaces, or contain the following special characters:
~ ` ! $ % ^ & * ( ) - + = { [ } ] | \ : ; " ' < , > . ? /
Description
Optional. Description for the event target that appears in the Process Designer.
The description cannot exceed 4,000 characters.
The following table describes the target properties that you can configure:
Properties
Description
Object Name
The name of the object where you want to publish messages.
Object Path
Optional. The path of the object where you want to publish messages.

SAP IDoc connection metadata

After you create or update an SAP IDoc connection, you validate, save, and publish the connection. You can view the actions and process objects for the connection on the Metadata tab.
The Metadata tab displays the process objects generated when you publish the SAP IDoc connection. The process objects are based on the search filter options you provide.
In the Actions section on the Metadata tab, you can view the event source and event target configured for the connection.
In the Objects section on the Metadata tab, you can view the objects associated with the SAP IDoc connection.
The published metadata for the connection consists of the following objects:
Headers
The Header object contains name and type fields that represent the SAP IDoc header name and its type.
Messages
IDoc messages consist of headers and a body. The headers in an IDoc message are a list of name-value pairs that contain multiple attributes for the IDoc message. The IDoc message body contains the message payload, which the process accesses as a process object of type $po:$any.
The following image shows the published metadata of an SAP IDoc connection:
View the published metadata of an SAP IDoc connection
When you publish an SAP IDoc connection, the system refreshes the Metadata tab by default. When you create an SAP IDoc connection, you click Save and then click Publish to download the metadata.