Pull from SAP S/4HANA Extraction Views

SAP S/4HANA Cloud, Public Edition is SAP’s cloud-hosted enterprise resource planning (ERP) suite. Organizations use it to run core business operations, including sales orders, product master data, and customer records.

The SAP S/4HANA Extraction Views connector pulls sales orders, sales order line items, products, business partners, and plants from SAP S/4HANA Cloud, Public Edition. It reads extraction views, which are CDS views that SAP has released for data extraction, through SAP Cloud Data Integration (CDI).

Choose which data types to pull. Each data type is read from one extraction view.

Data type

Extraction view

DataSource

Business partners

I_BusinessPartner

IBUSINESSPARTNER$P

Plants

I_Plant

IPLANT$P

Products

I_Product

IPRODUCT$P

Sales order items

I_SalesOrderItem

ISDSLSORDERITEM$P

Sales orders

I_SalesOrder

ISDSALESORDER$P

The DataSource is the name that SAP uses for the extraction view in its own error messages and logs.

Every courier run pulls every record from each selected extraction view. There is no incremental pull. See Full pulls and deleted records.

Amperity lands every field that the extraction view returns for each record. OData structural fields are removed. Field names and values are otherwise landed as SAP returns them. A field that SAP returns as null is landed as null, and a field that SAP returns as empty is landed as an empty value.

Compared with SAP S/4HANA Public Cloud

The SAP S/4HANA Extraction Views connector and the SAP S/4HANA Public Cloud connector read the same SAP tenant, offer the same data types, and can use the same communication user. They read different SAP services:

  • SAP S/4HANA Extraction Views reads extraction views through CDI. One communication scenario covers every data type, and each extraction view must also be on the allowlist for that communication arrangement.

  • SAP S/4HANA Public Cloud reads SAP’s transactional OData APIs. Each API requires its own communication arrangement, and some data types are pulled incrementally.

The two connectors read different views of the same records, so do not assume that their domain tables have the same fields. Review the fields in each domain table before you switch from one connector to the other.

Important

This connector supports SAP S/4HANA Cloud, Public Edition only. SAP S/4HANA on-premise, SAP S/4HANA Cloud, Private Edition, and SAP ECC differ in how they authenticate, which APIs they publish, and how they are reached over a network. Assume this connector does not support them.

Beta

The SAP S/4HANA Extraction Views connector is in beta. Contact your Amperity representative to learn more.

The steps that are required to pull sales orders, sales order line items, products, business partners, and plants to Amperity with the SAP S/4HANA Extraction Views connector:

  1. Configure SAP access

  2. Get details

  3. Add courier

  4. Get sample files

  5. Add feeds

  6. Add load operations

  7. Run courier

  8. Add to courier group

Configure SAP access

Your SAP administrator must configure access in SAP before Amperity can pull any data.

To configure SAP access

  1. Create a communication user for Amperity using the Maintain Communication Users app. Record the user name and password.

    If Amperity already pulls from SAP S/4HANA Public Cloud, use its existing communication user.

  2. Create a communication system that registers Amperity as the calling system, and then assign the communication user to it for inbound communication. If Amperity already pulls from SAP S/4HANA Public Cloud, use its existing communication system.

  3. Create and activate a communication arrangement for communication scenario SAP_COM_0531 that uses this communication system.

  4. Add the extraction view for each data type that Amperity pulls to the allowlist for this communication arrangement. The extraction views are listed in the table at the top of this page.

For more information about extraction views, see Extracting Data Through CDS Views to SAP BW/4HANA in the SAP documentation. That page is written for SAP BW/4HANA.

Important

Amperity reads extraction views through communication scenario SAP_COM_0531. SAP’s documentation for data extraction also describes communication scenario SAP_COM_0532, which Amperity does not use.

Activating SAP_COM_0531 and adding extraction views to its allowlist are separate steps. Amperity checks the first when you save the courier, but cannot check the second. A data type whose extraction view is not on the allowlist passes the connection test, and then fails when a courier run reads it. Adding a data type later requires your SAP administrator to add its extraction view to the allowlist.

Get details

The SAP S/4HANA Extraction Views connector requires the following configuration details:

  1. The Communication User and Password for the communication user that your SAP administrator created for Amperity.

    Your SAP administrator provides the user name and password of the communication user for Amperity. A communication user is a technical user for system-to-system access, not an ordinary SAP user account.

    This connector uses the same credential type as the SAP S/4HANA Public Cloud connector. If you already pull from SAP S/4HANA Public Cloud, select that credential instead of creating a new one. Your SAP administrator then creates a communication arrangement for communication scenario SAP_COM_0531 that uses the communication system this user is assigned to.

  2. The API URL for your SAP tenant. This must start with https://. For example: https://my123456-api.s4hana.cloud.sap.

    Important

    The API URL is not the address that your staff use to sign in to SAP. It is a separate host, and the two are easily confused. Amperity verifies that the API URL is a secure address, but cannot verify that it is the correct host, so an incorrect value appears as a failed connection rather than as a validation message.

  3. The Data types to pull. Select any combination of Business partners, Plants, Products, Sales order items, and Sales orders. Select at least one.

  4. The Requests per second (optional), which is the rate at which Amperity calls SAP. The default is 1. Enter a positive number, such as 0.5, 1, or 2. Values below 1 are allowed, so 0.5 means one call every two seconds.

    SAP does not publish a rate limit for S/4HANA Cloud, Public Edition. The default is a conservative rate that Amperity sets, not a limit that SAP enforces. Lower this value if your SAP administrator asks for less traffic.

  5. The Delay between pages (optional), which is the number of milliseconds that Amperity waits between calls within a data type. Enter a value from 0 to 20000. The default is 100 milliseconds. Enter 0 for no delay.

    Raising this value spreads a long pull over more time without changing the amount of data that it requests.

SAP decides how many records each call returns, so there is no page size setting.

Note

Amperity pulls one data type at a time rather than pulling several at once. The rate and the delay apply to a single courier run, so two courier runs that overlap place twice this load on your tenant. This includes a courier for SAP S/4HANA Public Cloud that reads the same tenant.

Tip

Use SnapPass to securely share configuration details for SAP S/4HANA Extraction Views between your company and your Amperity representative.

Add courier

A courier brings data from an external system to Amperity.

To add a courier

  1. From the Sources page, click Add Courier. The Add Courier page opens.

  2. Find, and then click the icon for SAP S/4HANA Extraction Views. The Add Courier page opens.

    The SAP S/4HANA Public Cloud connector has the same icon. Select the one named SAP S/4HANA Extraction Views.

  3. Enter the name of the courier. For example: “SAP S/4HANA Extraction Views”.

    From the Credential field, select an existing credential or select Create a new credential. A credential created for SAP S/4HANA Public Cloud is listed here.

    To add a credential, enter the name of the credential, a description, and the SAP communication user and password. Click Save.

    When finished click Continue.

  4. Enter the API URL for your SAP tenant.

  5. Under Data types, select the data types to pull.

  6. Optionally, set the Requests per second and Delay between pages.

  7. Click Create.

Note

When you save the configuration, Amperity reads the list of extraction views from your SAP tenant. This verifies that the API URL is correct, that the communication user can sign in, and that communication scenario SAP_COM_0531 is active for that user. It does not verify that each selected extraction view is on the allowlist.

Get sample files

Newline-delimited JSON (NDJSON) is a data format for structured data that defines the structure of JSON data using lines as separators. Each line in a NDJSON file is a valid JSON value.

Every SAP S/4HANA Extraction Views file that is pulled to Amperity must be configured as a feed. Before you can configure each feed you need to know the schema of that file. Run the courier without load operations to bring sample files from SAP S/4HANA Extraction Views to Amperity, and then use each of those files to configure a feed.

Amperity pulls one file for each selected data type, and names each file after its data type.

Data type

File name

Name in load operations

Business partners

business-partners.ndjson

business-partners

Plants

plants.ndjson

plants

Products

products.ndjson

products

Sales order items

sales-order-items.ndjson

sales-order-items

Sales orders

sales-orders.ndjson

sales-orders

To get sample files

  1. From the Sources tab, open the menu for a courier configured for SAP S/4HANA Extraction Views with empty load operations, and then select Run. The Run Courier dialog box opens.

  2. Select Load all data. This is the only load option that SAP S/4HANA Extraction Views supports.

    Every run is a full pull, so getting sample files reads every record from each selected extraction view. This can take a long time for a large SAP tenant.

  3. Click Run.

    The files that the courier pulls are available for selection as an existing source from the Add Feed dialog box.

Add feeds

A feed defines how to load data into a domain table, including specifying required columns and columns with semantic tags for customer profile (PII) or transactions data.

Note

A feed must be added for each file that is pulled from SAP S/4HANA Extraction Views, including all files that contain customer records and interaction records, along with any other files that is used to support downstream workflows.

Use the sample file for each data type to configure its feed. The fields in each file are the fields that the extraction view returns on your SAP tenant. They depend on your SAP release and on how your tenant is configured, so they vary between SAP customers. The authoritative field list for your tenant comes from your own SAP system rather than from SAP’s general documentation.

Fields that SAP returns as null are landed as null rather than omitted, so a record is not rejected because a field is empty in that record.

Every run is a full pull, so each record is loaded again on every run. Give each feed a primary key that identifies one record, so that loading a record again updates it rather than adding a duplicate.

To add a feed

  1. From the Sources tab, click Add Feed. This opens the Add Feed dialog box.

  2. Under Data Source, select Create new source, and then enter “SAP S/4HANA Extraction Views”.

  3. Enter the name of the feed in Feed Name. For example: “Sales orders”.

    Tip

    The name of the domain table will be “<data-source-name>:<feed-name>”. For example: “SAP S/4HANA Extraction Views:Sales orders”.

  4. Under Sample File, select Select existing file, and then choose from the list of files. For example: “sales-orders.ndjson”.

    Tip

    The list of files that is available from this dropdown menu is sorted from newest to oldest.

  5. Select Load sample file on feed activation.

  6. Click Continue. This opens the Feed Editor page.

  7. Select the primary key.

  8. Apply semantic tags to customer records and interaction records, as appropriate.

  9. Under Last updated field, specify which field best describes when records in the table were last updated.

    Tip

    Choose Generate an “updated” field to have Amperity generate this field. This is the recommended option unless there is a field already in the table that reliably provides this data.

  10. For feeds with customer records (PII data), select Make available to Stitch.

  11. Click Activate. Wait for the feed to finish loading data to the domain table, and then review the sample data for that domain table from the Data Explorer.

Add load operations

After the feeds are activated and domain tables are available, add the load operations to the courier used for SAP S/4HANA Extraction Views.

Example load operations

Load operations must specify each file that is pulled to Amperity from SAP S/4HANA Extraction Views.

Refer to each file by its name in load operations, as shown in the table in Get sample files. Add a load operation for each data type that the courier pulls.

Important

A load operation that uses any other name, such as the label shown under Data types or the file name with its extension, matches no file. The courier run succeeds, but no data is loaded.

For example:

{
  "df-A1B2C3": [
    {
      "type": "load",
      "file": "sales-orders"
    }
  ],
  "df-D4E5F6": [
    {
      "type": "load",
      "file": "sales-order-items"
    }
  ]
}

To add load operations

  1. From the Sources tab, open the menu for the courier that was configured for SAP S/4HANA Extraction Views, and then select Edit. The Edit Courier dialog box opens.

  2. Edit the load operations for each of the feeds that were configured for SAP S/4HANA Extraction Views so they have the correct feed ID.

  3. Click Save.

To pull another data type later, ask your SAP administrator to add its extraction view to the allowlist. Then edit the courier to select it under Data types, run the courier to get a sample file, add a feed for that file, and add a load operation for it.

Run courier manually

Run the courier again. This time, because the load operations are present and the feeds are configured, the courier will pull data from SAP S/4HANA Extraction Views.

To run the courier manually

  1. From the Sources tab, open the menu for the courier with updated load operations that is configured for SAP S/4HANA Extraction Views, and then select Run. The Run Courier dialog box opens.

  2. Select Load all data, the only load option that SAP S/4HANA Extraction Views supports. Actual data will be loaded to a domain table because the feed is configured.

  3. Click Run.

After the run, you may apply semantic tags to the fields in each domain table and you may make each domain table available to Stitch, depending on your use case.

Add to courier group

  1. From the Sources tab, click Add Courier Group. This opens the Create Courier Group dialog box.

  2. Enter the name of the courier. For example: “SAP S/4HANA Extraction Views”.

  3. Add a cron string to the Schedule field to define a schedule for the orchestration group.

    A schedule defines the frequency at which a courier group runs. All couriers in the same courier group run as a unit and all tasks must complete before a downstream process starts. Define a schedule using cron.

    Cron syntax specifies the fixed time, date, or interval at which cron runs. Each line represents a job. 30 8 * * * represents “run at 8:30 AM every day” and 30 8 * * 0 represents “run at 8:30 AM every Sunday”.

    For example:

    ┌───────── minute (0 - 59)
    │ ┌─────────── hour (0 - 23)
    │ │ ┌───────────── day of the month (1 - 31)
    │ │ │ ┌────────────── month (1 - 12)
    │ │ │ │ ┌─────────────── day of the week (0 - 6) (Sunday to Saturday)
    │ │ │ │ │
    │ │ │ │ │
    │ │ │ │ │
    * * * * * command to execute
    

    Amperity validates the cron syntax and shows you the results. You may also use crontab guru to validate cron syntax.

  4. Set Status to Enabled.

  5. Specify a time zone.

    A courier group schedule is associated with a time zone. The time zone determines the point at which a courier group’s scheduled start time begins. A time zone should be aligned with the time zone of system from which the data is being pulled.

    Use the Use this time zone for file date ranges checkbox to use the selected time zone to look for files. If unchecked, the courier group uses the current time in UTC to look for files to pick up.

    Note

    The time zone that is chosen for an courier group schedule should consider every downstream business processes that requires the data and also the time zones in which the consumers of that data will operate.

  6. Add at least one courier to the courier group. Select the name of the courier from the Courier dropdown. Click + Add Courier to add more couriers.

  7. Click Add a courier group constraint, and then select a courier group from the dropdown list.

    A wait time is a constraint placed on a courier group that defines an extended time window for data to be made available at the source location.

    Important

    A wait time is not required for a bridge.

    A courier group typically runs on an automated schedule that expects customer data to be available at the source location within a defined time window. However, in some cases, the customer data may be delayed and is not made available within that time window.

  8. For each courier group constraint, apply any offsets.

    A courier can be configured to look for files within range of time that is older than the scheduled time. The scheduled time is in Coordinated Universal Time (UTC), unless the “Use this time zone for file date ranges” checkbox is enabled for the courier group.

    This range is typically 24 hours, but may be configured for longer ranges. For example, it is possible for a data file to be generated with a correct file name and datestamp appended to it, but for that datestamp to represent the previous day because of how an upstream workflow is configured. A wait time helps ensure that the data at the source location is recognized correctly by the courier.

    Warning

    This range of time may affect couriers in a courier group whether or not they run on a schedule. A manually run courier group may not take its schedule into consideration when determining the date range. Only the provided input days to load data from are used as inputs.

  9. Click Save.

Important

Every run that a courier group starts is a full pull of every selected data type. Set the schedule with the size of a full pull in mind, and allow each run to finish before the next one starts. Two runs that overlap place twice the load on your SAP tenant.

Full pulls and deleted records

Every courier run, whether you run it manually or a courier group runs it, pulls every record from each selected extraction view. The SAP S/4HANA Extraction Views connector does not pull only the records that changed since the last run. SAP’s change tracking for extraction views requires Amperity to keep a position between runs, which this connector does not do.

Amperity does not pull a record of deletions from SAP. A record that is deleted in SAP is absent from the next pull, but loading that pull does not remove the record from a domain table that already contains it. To keep a domain table matched to the current contents of the extraction view, add a truncate operation before the load operation for its feed. A truncate operation empties the domain table before each load. For example:

{
  "df-A1B2C3": [
    {
      "type": "truncate"
    },
    {
      "type": "load",
      "file": "sales-orders"
    }
  ]
}

Troubleshoot errors

The following errors may occur when you save the courier, which tests the connection, or when a courier runs. An error that occurs during a courier run names the data type that failed by its name in load operations, such as sales-order-items, rather than by the label shown under Data types.

Error

Resolution

SAP rejected the communication user.

The user name or password is incorrect, or the communication user is locked or expired. Confirm the credential with whoever provided it.

SAP authenticated the communication user but refused to read a data type.

Communication scenario SAP_COM_0531 is not active for this user. When you save the courier, the error names providers, which is the list of extraction views, instead of a data type. The error names the communication scenario to activate. Only your SAP administrator can resolve this.

SAP returned Not Found.

When you save the courier, the API URL is usually incorrect, most often because it is the address used to sign in to SAP rather than the API host. This can also indicate that the communication arrangement is not active.

SAP returned Not Found while reading a data type.

This occurs during a courier run, after the connection test has passed. Confirm with your SAP administrator that the communication arrangement is still active. If it is, contact your Amperity representative.

SAP is rate limiting this tenant.

When you save the courier, try again shortly.

SAP rate limited the pull of a data type and did not recover.

This occurs during a courier run, after Amperity has retried. Lower Requests per second or raise Delay between pages, and then run the courier again.

Could not reach the SAP OData service.

When you save the courier, confirm that the API URL is correct and that the host is reachable.

SAP returned a server error while reading a data type.

Amperity retries these before reporting the run as failed, so the error can take some time to appear. SAP also refuses an extraction view that is not on the allowlist, so first confirm with your SAP administrator that the extraction view for the named data type is included. If it is, ask your SAP administrator to check the tenant.

Lost the connection to SAP while reading a data type.

A network interruption during the pull. Amperity retries this before reporting the run as failed. If the run fails, run the courier again.

SAP rejected the request to read a data type as invalid.

Retrying does not resolve this. Contact your Amperity representative.

SAP returned a paging link pointing at a host other than the tenant’s API URL.

Amperity does not follow a link to a different host, because the request would carry the communication user’s password. Contact your Amperity representative.

Landing stalled while reading a data type.

The pull wrote no records for ten minutes and was ended rather than left running. The error includes the number of records that had been read, which distinguishes a pull that never started from one that stopped partway through. Changing the courier settings does not resolve this. Contact your Amperity representative.

If one data type fails, the entire courier run is reported as failed.