Pull from SAP S/4HANA Public Cloud

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.

SAP S/4HANA Public Cloud can send sales orders, sales order line items, products, business partners, and plants to Amperity using the OData v2 APIs that SAP publishes for S/4HANA Cloud, Public Edition. Choose which data types to pull: Business partners, Plants, Products, Sales order items, and Sales orders. Amperity creates a feed and domain table for each data type you select.

Amperity lands every field that your SAP tenant returns for the selected records. Fields and field names are not modified, apart from the following: OData structural fields are removed, SAP timestamps are converted to standard timestamps, and fields that SAP returns as null are omitted from the record. A field that SAP returns as empty is landed as an empty value rather than omitted.

Only the fields on the record itself are landed. Data that SAP holds in related records, such as a sales order’s partners or a business partner’s addresses, is not included.

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 Public Cloud source connector is currently 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 from SAP S/4HANA Public Cloud:

  1. Configure SAP access

  2. Get details

  3. Add courier

  4. Run courier

  5. Review feed and domain table

  6. Add to courier group

Configure SAP access

SAP S/4HANA Cloud, Public Edition does not allow an external application to authenticate on its own. 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.

  2. Create a communication system that registers Amperity as the calling system, and then assign the communication user to it for inbound communication.

  3. Create and activate a communication arrangement for each communication scenario in the table below. A communication arrangement is based on a communication scenario, which determines the APIs that the communication user is allowed to call.

Access is granted per communication scenario, not per data type. Each scenario in the following table requires its own communication arrangement, and selecting a data type in Amperity does not grant access to it.

Data type

Communication scenario

Business partners

SAP_COM_0008

Plants

Not identified. See the note below.

Products

SAP_COM_0009

Sales order items

SAP_COM_0109

Sales orders

SAP_COM_0109

Sales orders and sales order items are served by the same scenario, so one communication arrangement covers both.

Note

The communication scenario that exposes plant data is not identified. SAP does not document which scenario publishes this API for Public Edition. Before you select Plants, confirm with your SAP administrator that this data can be read from your tenant. Plant records carry the plant identifier and name and the company code and name. They do not include an address.

Adding a data type later requires a communication arrangement for its scenario, unless a data type you already pull uses the same one. Amperity creates a feed and domain table for each data type that you add.

Get details

SAP S/4HANA Public Cloud requires the following configuration details:

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

    Request the communication user name and password from your SAP administrator. This is a technical user that your administrator creates for Amperity in SAP using the Maintain Communication Users app; it is not an ordinary SAP user account.

    Your SAP administrator must also activate a communication arrangement for each data type that Amperity pulls. A communication user on its own does not grant access to any data.

  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.

Tip

Use SnapPass to securely share configuration details for SAP S/4HANA Public Cloud 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 Public Cloud. The Add Courier page opens.

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

    From the Credential field, select an existing credential or select Create a new credential.

    To add a credential, enter the name of the credential, a description, and the SAP S/4HANA Public Cloud 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. Click Create.

    Amperity creates a feed and domain table for each selected data type.

Note

When you save the configuration, Amperity reads one record from every data type you selected. This verifies that the communication arrangement for each data type is active, rather than verifying only that the communication user can sign in. A data type whose communication arrangement is missing is named on this page, instead of failing later during an unattended courier run.

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

Important

Run the courier manually and select the option to load all available data before you add the courier to a scheduled courier group. A first run is not automatically a full load. A scheduled courier group always pulls a bounded time period, so a first run that is scheduled returns no records if nothing changed during that period. The courier succeeds and the domain table appears to be broken rather than empty.

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 Public Cloud, and then select Run. The Run Courier dialog box opens.

  2. Select the load option, either for a specific time period or all available data. Actual data will be loaded to a domain table because the feed is configured.

  3. Click Run.

    This time the notification will return a message similar to:

    Completed in 5 minutes 12 seconds

Review feed and domain table

After running the SAP S/4HANA Public Cloud courier, Amperity creates a feed and domain table for each data type you selected. You may apply semantic tags to the fields in these tables and you may make each domain table available to Stitch, depending on your use case.

The fields in each domain table are the fields that your SAP tenant returns for that record type, which vary between SAP customers because SAP customers activate different parts of the product. Expect a wide table: a sales order header in SAP’s own sample data carries around 94 fields. Expect many of its columns to be empty. SAP returns an empty value for every field that your tenant does not use, and those fields are landed rather than dropped, so more than half of the columns in a domain table can be empty. That is normal for SAP data and is not a sign that the pull was incomplete. The authoritative field list for your tenant comes from your own SAP system rather than from SAP’s general documentation. Contact your Amperity representative if you need the exact field list for your tenant.

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 Public Cloud”.

  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

Leave Only retrieve files dropped in the past day? cleared unless the courier group runs daily. A scheduled courier group calculates the start of its time period from the schedule, not from the last successful run, so a failed run loses that period permanently.

The courier group settings do not offer a longer look-back period than one day. Contact your Amperity representative to set a look-back period that is at least twice the schedule interval. Pulling the same time period twice has no adverse effect, because loading the same record again updates it.

Incremental pulls and deleted records

A courier group that runs on a schedule pulls records that changed during the scheduled time period, for the data types that support it. The remaining data types are pulled in full on every run.

Data type

Pulled incrementally

Notes

Business partners

No

Pulled in full on every run. SAP does not populate a last-changed date on business partner records reliably enough to filter on, and filtering on it would omit records without reporting an error.

Plants

No

Pulled in full on every run. SAP does not publish a last-changed timestamp for this record type.

Products

Yes

Filtered on the product’s last-changed timestamp.

Sales order items

Yes

Filtered on the parent sales order’s last-changed timestamp. SAP does not maintain a last-changed timestamp on line items.

Sales orders

Yes

Filtered on the sales order’s last-changed timestamp.

Deleted records

SAP does not expose deleted records through these APIs. A record that is deleted in SAP stops being readable, and SAP provides no indication that it was deleted. An incremental pull can therefore never remove a record from Amperity after it is deleted in SAP. Do not treat an incremental pull as a complete replica of your SAP data.

Sales orders are less affected than other data types, because SAP users typically reject a sales order rather than delete it. A rejection is an ordinary field change that an incremental pull collects.

To clear records that were deleted in SAP, configure a second courier that uses the Truncate and upsert load option, and then add it to a courier group that runs infrequently. Whether a courier empties a table before loading is a property of the courier rather than of an individual run, so a single courier cannot do this only sometimes. Point the second courier at the same feeds, settings, and credential as the first. This courier group requires a look-back period that is longer than the history held in your SAP tenant, which is longer than the courier group settings offer. Contact your Amperity representative to set it.

Troubleshoot errors

The following errors may occur when you test the connection to SAP S/4HANA Public Cloud or when a courier runs.

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.

The communication arrangement for that data type is not active for this user. The error names the data type and the communication scenario to activate. Only your SAP administrator can resolve this.

SAP returned Not Found for a data type.

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 a missing communication arrangement.

SAP is rate limiting this tenant.

Try again shortly.

Amperity could not reach the SAP OData service.

Confirm that the API URL is correct and that the host is reachable.

SAP returned a server error.

A problem on the SAP side. Amperity retries these before reporting the run as failed. If it persists, ask your SAP administrator to check the tenant.

The connection to SAP was lost while reading a data type.

A network interruption during the pull. Run the courier again.

SAP rejected the request as invalid.

Retrying does not resolve this. Contact your Amperity representative.

SAP returned a partial page while reading a data type.

The pull stopped rather than loading an incomplete set of records. Contact your Amperity representative.

Landing stalled while reading a data type.

The pull stopped making progress 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. This is not usually caused by SAP. Contact your Amperity representative.

If one data type fails, the entire courier run is reported as failed, even though the data that was already pulled is retained. A partially loaded set of ERP data that was reported as a success would be harder to detect than a clear failure.