# SAP (IDoc and RFC)

The **SAP** connector allows integration with SAP systems by using the **RFC** protocol and the **IDoc** standard for data exchange.

## **Parameters**

Take a look at the configuration options for the connector. Parameters supported by [Double Braces expressions](https://docs.digibee.com/documentation/connectors-and-triggers/double-braces) are marked with `(DB)`.

### **Authorization tab**

<table data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Default value</th><th>Data type</th></tr></thead><tbody><tr><td><strong>Use Dynamic Account</strong></td><td>When active, the connector will use the account dynamically. Otherwise, it will use the account statically. Learn more about <a href="https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/development-cycle/overview/runtime/pipeline-engine/dynamic-accounts">Dynamic Accounts</a>.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Scoped</strong></td><td>When active, the stored account is isolated from other subprocesses. In this case, the subprocesses see their own version of the stored account data. It is only available if the <strong>Use Dynamic Account</strong> parameter is enabled.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Account Name</strong> <code>(DB)</code></td><td>The name of the dynamic account used by the connector. This account must have been previously configured in a <a href="../tools/store-account"><strong>Store Account</strong></a> connector in the pipeline for this process to take effect. It is only available if the <strong>Use Dynamic Account</strong> parameter is enabled.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Account</strong></td><td>The account used by the connector. Supported type: <a href="https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/platform-administration/settings/accounts"><strong>Basic</strong></a> (user and password). It is only available if the <strong>Use Dynamic Account</strong> parameter is disabled.</td><td>N/A</td><td>Account</td></tr><tr><td><strong>Host</strong> <code>(DB)</code></td><td>Hostname of the SAP system. To support "IP" and "Port", VPN connectivity is required (you can configure VPN via SAP GUI). To resolve the hostname to an IP address, you must add a mapping entry to the host file on the machine where the agent is installed.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Client ID</strong> <code>(DB)</code></td><td>SAP client ID, typically a 3-digit number used to connect to SAP.</td><td>400</td><td>String</td></tr><tr><td><strong>System Number</strong> <code>(DB)</code></td><td>SAP system number, typically 2 digits. You can find this information in the SAP GUI.</td><td>01</td><td>Integer</td></tr><tr><td><strong>Language</strong> <code>(DB)</code></td><td>Language used for the SAP system connection (for example, "EN" for English).</td><td>en</td><td>String</td></tr></tbody></table>

### **General tab**

<table data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Default value</th><th>Data type</th></tr></thead><tbody><tr><td><strong>Alias</strong></td><td>Name (alias) for this connector’s output, allowing you to reference it later in the flow using Double Braces expressions. <a href="../../double-braces/how-to-reference-data-using-double-braces/previous-steps-access">Learn more</a>.</td><td>sap-1</td><td>String</td></tr><tr><td><strong>SAP Operation</strong></td><td>SAP system connection type. Supported options: <strong>RFC</strong> or <strong>IDoc</strong>.</td><td>RFC</td><td>String</td></tr></tbody></table>

{% tabs fullWidth="true" %}
{% tab title="RFC" %}

<table data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Default value</th><th>Data type</th></tr></thead><tbody><tr><td><strong>RFC</strong> <code>(DB)</code></td><td>Name of the RFC used to connect to the SAP system. This value is provided by the client. The import parameters of the SAP function must be mapped.</td><td>YYPCL_RFC_ORDEM_FATURA</td><td>String</td></tr><tr><td><strong>Search Template</strong></td><td>Button that automatically populates the <strong>Template (XML)</strong> parameter with an RFC template when all authorization details and the RFC name are valid.</td><td>N/A</td><td>Button</td></tr><tr><td><strong>Send as File</strong></td><td>When enabled, a file can be defined and sent.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>File Name</strong> <code>(DB)</code></td><td>File that contains the body to be sent to the SAP server. Use this option when the payload is too large for the <strong>Template</strong> field. It's recommended to use other connectors like <a href="../tools/template-transformer"><strong>Template Transformer</strong></a> and <a href="../files/file-writer"><strong>File Writer</strong></a> to generate the file content.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Template (XML)</strong> <code>(DB)</code></td><td>Defines the Apache FreeMarker template for the SOAP message sent in the request. For RFC calls, a template is generated through the <strong>Search Template</strong> button when authorization details and the RFC name are valid.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Fail On Error</strong></td><td>If enabled, interrupts the pipeline execution when an error occurs. If disabled, execution continues, but the <code>"success"</code> property will be set to <code>false</code>.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Raw Mode</strong></td><td>When enabled the result will be returned in original SAP XML format, wrapped in a JSON.</td><td>False</td><td>Boolean</td></tr></tbody></table>
{% endtab %}

{% tab title="IDoc" %}

<table data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Default value</th><th>Data type</th></tr></thead><tbody><tr><td><strong>IDoc Type</strong> <code>(DB)</code></td><td>Basic IDoc Type of the IDoc to be sent.</td><td>N/A</td><td>String</td></tr><tr><td><strong>IDoc Type Extension</strong> <code>(DB)</code></td><td>IDoc Type Extension of the IDoc, if applicable.</td><td>N/A</td><td>String</td></tr><tr><td><strong>System Release</strong> <code>(DB)</code></td><td>SAP Basis Release associated with the IDoc.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Application Release</strong> <code>(DB)</code></td><td>Application Release associated with the IDoc.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Send as File</strong></td><td>When enabled, a file can be defined and sent.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>File Name</strong> <code>(DB)</code></td><td>File that contains the body to be sent to the SAP server. Use this option when the payload is too large for the <strong>Template</strong> field. It's recommended to use other connectors like <strong>Template Transformer</strong> and <strong>File Writer</strong> to generate the file content.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Template (XML)</strong> <code>(DB)</code></td><td>Defines the Apache FreeMarker template for the SOAP message sent in the request.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Fail On Error</strong></td><td>If enabled, interrupts the pipeline execution when an error occurs. If disabled, execution continues, but the <code>"success"</code> property will be set to <code>false</code>.</td><td>False</td><td>Boolean</td></tr></tbody></table>

{% hint style="info" %}
IDocs are processed asynchronously in SAP. When an IDoc is sent, there is no immediate confirmation of success or failure. If it fails, the user must resend the IDoc.
{% endhint %}
{% endtab %}
{% endtabs %}

### **Documentation tab**

<table data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Default value</th><th>Data type</th></tr></thead><tbody><tr><td><strong>Documentation</strong></td><td>Optional field to describe the connector configuration and any relevant business rules.</td><td>N/A</td><td>String</td></tr></tbody></table>

## **SAP connector – Usage guide**

### **File size limits**

When using the SAP connector, note the maximum file size per deployment type. These limits apply when the connector is used independently. If other connectors are present in the pipeline, sizes may vary:

* **Small:** 10 MB
* **Medium:** 28 MB
* **Large:** 67 MB

### **Global variable configuration**

To simplify dynamic configuration and promote reusability, it’s recommended to define [Global variables](https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/platform-administration/settings/globals) in your pipeline.

#### **Required Globals**

| Variable      | Description     |
| ------------- | --------------- |
| `environment` | SAP environment |

#### **Optional Globals for Templates**

| Variable    | Description                       |
| ----------- | --------------------------------- |
| `[rfc]`     | RFC function name                 |
| `[table]`   | Table related to the RFC call     |
| `[columns]` | Table columns used in the request |

For more details, see the [SAP connectivity guide](https://app.gitbook.com/s/boT4qPJIk6PZotrxlJWL/connectivity-guides/digibee-sap).

### **RFC integration**

#### **JSON input example**

For RFC connections, include the "**SAP JSON to RFC**" [capsule](https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/development-cycle/build-overview/capsulas/public-capsules/sap-collection) before the SAP connector. This ensures the input is properly formatted for the SAP system.

Example of an RFC call in a [**JSON Generator**](https://docs.digibee.com/documentation/connectors-and-triggers/connectors/tools/json-generator) connector:

```json
{
  "sid": "{{sap-test-sid}}", 
  "rfc": "BAPI_BUPA_ADDRESS_GETDETAIL", 
  "importParameters": { 
    "attributes": { 
      "BUSINESSPARTNER": {{ message.BUSINESSPARTNER }}, 
      "VALID_DATE": {{FORMATDATE(NOW(), "timestamp", "yyyy-MM-dd", null , "GMT-3") }} 
    } 
  }
}
```

#### **Best practices**

* Always specify the `sid` (Environment/System Name/System ID).
* The `rfc` function can be set in the JSON payload or directly in the connector.
* Define `importParameters` with only the necessary fields for the function call.

### **Template (XML) configuration**

The **Template (XML)** field allows automatic generation for RFCs and also supports manual customization of both RFC and IDoc structures.

#### **Automatic RFC template generation**

When an RFC function is selected, the **Search Template** button becomes available. If the authorization details are correct and the RFC name is valid, clicking it automatically fills the **Template (XML)** field with a template that only requires you to replace the values.

**Example of generated template:**

```xml
<BBP_RFC_READ_TABLE:Request xmlns:BBP_RFC_READ_TABLE="http://sap.fusesource.org/rfc/EC1/BBP_RFC_READ_TABLE">
    <DELIMITER>${body.DELIMITER}</DELIMITER>
    <NO_DATA>${body.NO_DATA}</NO_DATA>
    <QUERY_TABLE>${body.QUERY_TABLE}</QUERY_TABLE>
    <ROWCOUNT>${body.ROWCOUNT?c}</ROWCOUNT>
    <ROWSKIPS>${body.ROWSKIPS?c}</ROWSKIPS>
    <FIELDS>
        <#if body.FIELDS??>
            <#list body.FIELDS as item>
            <row>
                <FIELDNAME>${item.FIELDNAME}</FIELDNAME>
                <OFFSET>${item.OFFSET}</OFFSET>
                <LENGTH>${item.LENGTH}</LENGTH>
                <TYPE>${item.TYPE}</TYPE>
                <FIELDTEXT>${item.FIELDTEXT}</FIELDTEXT>
            </row>
            </#list>
        </#if>
    </FIELDS>
    <OPTIONS>
        <#if body.OPTIONS??>
            <#list body.OPTIONS as item>
            <row>
                <TEXT>${item.TEXT}</TEXT>
            </row>
            </#list>
        </#if>
    </OPTIONS>
</BBP_RFC_READ_TABLE:Request>
```

#### **Manual template examples**

**IDoc template example**

```xml
<?xml version="1.0" encoding="ASCII"?> 
<idoc:Document 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:FLCUSTOMER_CREATEFROMDATA01---="http://sap.fusesource.org/idoc/{_YOUR_ENVIRONMENT_}/FLCUSTOMER_CREATEFROMDATA01///" 
    xmlns:idoc="http://sap.fusesource.org/idoc" 
    creationDate="2015-01-28T12:39:13.980-0500" 
    creationTime="2015-01-28T12:39:13.980-0500" 
    iDocType="FLCUSTOMER_CREATEFROMDATA01" 
    iDocTypeExtension="" 
    messageType="FLCUSTOMER_CREATEFROMDATA" 
    recipientPartnerNumber="QUICKCLNT" 
    recipientPartnerType="LS" 
    senderPartnerNumber="QUICKSTART" 
    senderPartnerType="LS"> 
  <rootSegment xsi:type="FLCUSTOMER_CREATEFROMDATA01---:ROOT" document="/">
    <segmentChildren parent="//@rootSegment"> 
      <E1SCU_CRE parent="//@rootSegment" document="/"> 
        <segmentChildren parent="//@rootSegment/@segmentChildren/@E1SCU_CRE.0"> 
          <E1BPSCUNEW parent="//@rootSegment/@segmentChildren/@E1SCU_CRE.0" 
              document="/" 
              CUSTNAME="Fred Flintstone" FORM="Mr." 
              STREET="123 Rubble Lane" 
              POSTCODE="01234" 
              CITY="Bedrock" 
              COUNTR="US" 
              PHONE="800-555-1212" 
              EMAIL="fred@bedrock.com"
              CUSTTYPE="P" 
              DISCOUNT="005" 
              LANGU="E"/> 
        </segmentChildren> 
      </E1SCU_CRE> 
    </segmentChildren> 
  </rootSegment> 
</idoc:Document>  
```

{% hint style="warning" %}
Replace `{_YOUR_ENVIRONMENT_}` with your SAP SID.
{% endhint %}

**RFC – Single Query**

Elementary Fields/Import Parameters:

```xml
<?xml version="1.0" encoding="ASCII"?> 
<[rfc]:Request xmlns:[rfc]="http://sap.fusesource.org/rfc/{{global.environment}}/[rfc]" 
  [columns]="20180801" 
  [columns]="20180806" 
  [columns]="050" />
```

Example:

```xml
<?xml version="1.0" encoding="ASCII"?> 
<ABCD_RFC_ORDEM_FATURA:Request 
    xmlns:ABCD_RFC_ORDEM_FATURA="http://sap.fusesource.org/rfc/QAS/ABCD_RFC_ORDEM_FATURA" 
    P_ERDAT_INI="2018-07-01T00:00:00.000" 
    P_ERDAT_FIM="2018-08-01T00:00:00.000" 
    CLIENTE="" 
    VKORG="0010" 
    AUART="" /> 
```

**RFC – Table Query**

Table fields:

```xml
<?xml version="1.0" encoding="ASCII"?> 
<[rfc]:Request ">xmlns:[rfc]="http://sap.fusesource.org/rfc/{{global.environment}}/[rfc]"> 
 <[table]> 
  <row> 
   <[columns]>${VBELN}</[columns]> 
   <[columns]>${ABDC}</[columns]> 
  </row> 
 </[table]> 
</[rfc]:Request> 
```

Example:

```xml
<?xml version="1.0" encoding="ASCII"?> 
<ABCD_RFC_MATERIAIS:Request ">xmlns:ABCD_RFC_MATERIAIS:Request="http://sap.fusesource.org/rfc/{{global.environment}}/ABCD_RFC_MATERIAIS:Request"> 
 <T_TIPO> 
  <row> 
   <MTART>${type}</MTART> 
  </row> 
 </T_TIPO> 
</ABCD_RFC_MATERIAIS:Request>
```

**Input**

```json
{  
    "body":{     
        "type": "S"   
    } 
}
```

* `${type}`**:** Variable that must be provided inside the `body` tag.

#### **Template variables and escaping**

When using variables like `sapRequestTemplate`, keep in mind:

* Special characters (such as `-`, `.`, `:`) in variable names must be **escaped** with a backslash (`\`).
* Use Apache FreeMarker functions for formatting and conversion:

```
<#assign x=42>
${x}
${x?string} <#-- the same as ${x} -->
${x?string.number}
${x?string.currency}
${x?string.percent}
${x?string.computer}
```

**Outputs:**

```
42
42
42
$42.00
4,200%
42
```

### **Message flow**

#### **Input**

The connector accepts input in any format but looks for a specific path based on the `modelPath` configuration.

#### **Output**

* The output mirrors the input but replaces the defined model property with the rendered XML string (from the Template).
* On error, the property `property_error` is added at the same level as the original model.