# Configuring AWS SDK for SAP ABAP Before using AWS SDK for SAP ABAP, you must configure the SDK with technical and functional settings that are necessary for the SDK operations. Some settings are transportable and some are runtime settings. Many of the settings are directly analogous to the settings defined in `.INI` files for other SDKs. The SDK configurations, except for Runtime settings, must be completed in your development environment. You can transport configurations to QA and production following the usual transport and change control rules. Transportable configuration is not recommended for production environments. If you do not have permissions to configure AWS SDK, see [SAP authorizations](https://docs.aws.amazon.com/sdk-for-sapabap/latest/developer-guide/authorizations.html). **Configuring AWS SDK for SAP ABAP** To run the configuration transaction, enter `/n/AWS1/IMG` in the SAPGUI command bar. **Configuring AWS SDK for SAP ABAP - BTP edition** Use the following steps to configure SDK for SAP ABAP - BTP edition. 1. Open your ABAP environment in a web browser. 1. Navigate to Custom Business Configurations application. To create a customizing request using the Export Customizing Transports application, see [Working in the Export Customizing Transports App - Create Request](https://help.sap.com/docs/btp/sap-business-technology-platform/working-in-export-customizing-transports-app#create-request). In the Custom Business Configuration application, you can group configurations based on the type of SDK settings. Use the following steps to group configurations. 1. Open your ABAP environment in a web browser, and navigate to the Custom Business Configurations application. 1. Select **Settings** > **Group**, and choose **Configuration Group** from the drop-down list. Select **OK**. 1. The configurations are now available in a hierarchical structure as displayed in the image. To save the view, see [Views (Variant Management) - Components](https://www.sap.com/design-system/fiori-design-web/ui-elements/variant-management/). ![\[An example of grouped configurations.\]](http://docs.aws.amazon.com/sdk-for-sapabap/latest/developer-guide/images/custom-business-configurations.png) This section covers the following topics. **Topics** + [Global settings](global-settings.md) + [Application configuration](application-configuration.md) + [Runtime settings](runtime-settings.md) + [Advanced connectivity scenarios](connectivity-scenarios.md) + [Service provider settings](service-provider-settings.md) + [Refresh, trace, and telemetry topics for AWS SDK for SAP ABAP](additional-setup.md) # Global settings Use `/n/AWS1/IMG` IMG transacation for AWS SDK for SAP ABAP, and Custom Business Configuration application for AWS SDK for SAP ABAP - BTP edition to configure the global settings. This topic uses IMG and Custom Business Configuration interchangeably. This section covers the following topics. **Topics** + [Technical settings](#technical-settings) + [Configure scenarios](#configure-scenarios) ## Technical settings The Global settings of `/AWS1/IMG` transaction affect the behavior of the entire SDK. These settings are generally configured by a Basis administrator. You can set these values to the following recommended settings. + Select **New Entries**. + **S3 regionalization**: Access us-east-1 buckets by using [s3.amazonaws.com](http://s3.amazonaws.com). + **STS regionalization**: Access STS by using global endpoint. + **Disable EC2 metadata**: Keep this field blank. This field is read-only in the BTP edition, and is set to 'Yes' by default. + **Metadata Endpt Mode**: Use IPv4 metadata endpoint. This field is read-only in the BTP edition, and is auto-updated. + **Metadata Endpt URL**: Keep this field blank. This field is read-only in the BTP edition. + Select **Save**. ## Configure scenarios Scenarios enable AWS SDK to more efficiently switch settings during a multi-Region disaster testing or disaster recovery testing scenario. You may not need this feature, and instead need only to configure the following DEFAULT scenario. + Select **New Entries**. + Scenario ID:`DEFAULT` + Scenario Description: Default Scenario + Select **Save**. If you have a multi-Region disaster recovery setup or other unique cases that require a quick change of settings, then you can configure multiple scenarios. + `DEFAULT` - Standard operation. + `DR` - Special configuration if a disaster requires moving the entire system to another Region. + `DR_TEST` - Special configuration for simulating a disaster, for example, in a temporary clone of production. # Application configuration Configuring SDK for SAP ABAP is similar to configuring other ABAP-based applications. It is organized into different *profiles* to group the settings of various scenarios. An ABAP SDK profile defines the settings required for a specific application scenario. For example, if transactions `ZVA01`, `ZVA02`, and `ZVA03` are invoice-related transactions enhanced and runs on AWS services, such as Amazon S3, AWS Lambda, and Amazon SageMaker AI, then an SDK profile called `ZINVOICE` can be made. This profile can group the technical settings, SAP authorizations, and IAM role mappings for the invoice-related functionality. Use `/n/AWS1/IMG` transacation for AWS SDK for SAP ABAP, and Custom Business Configuration application for AWS SDK for SAP ABAP - BTP edition to configure the global settings. This topic uses IMG and Custom Business Configuration interchangeably. **Topics** + [SDK profile](#sdk-profile) + [Logical resource resolver](#logical-resource) + [Example](#example) ## SDK profile An ABAP SDK profile defines the following for each SID and client. **Note** The client is always 100 in SAP BTP, ABAP environment. + The default AWS Region for all API calls. For example, if your SAP systems are running in the `us-east-1` Region, it is likely that your other AWS resources are also in the same Region, and this should be your default Region. Your ABAP code can override the default Region. + Authentication method + For SAP systems running on Amazon EC2, we strongly recommend choosing instance role metadata to benefit from the short-lived, automatically rotating credentials. + For SAP systems running on-premises or in another cloud, you must choose credentials from SSF storage. + For ABAP systems running on SAP BTP, you must choose credentials from SAP Credential Store. For more information, see [Using SAP Credential Store for authentication](https://docs.aws.amazon.com/). + For cross-account role chaining scenarios, choose Source Profile and specify a source profile ID. This enables automatic resolution and execution of role assumption chains. For more information, see [Using Source Profile for Cross-Account Access](https://docs.aws.amazon.com/sdk-for-sapabap/latest/developer-guide/source-profile.html). + A mapping of logical IAM roles to IAM roles. + This mapping is sorted in the order of descending priority. + An IAM role of highest priority for which a user is authorized in a PFCG role will automatically be selected for the user. + An optional mapping of services to custom endpoints. This configuration is discussed in [Advanced connectivity scenarios](https://docs.aws.amazon.com/sdk-for-sapabap/latest/developer-guide/connectivity-scenarios.html#advanced-routing) **Note** PFGC roles are called Business Roles in SAP BTP, ABAP environment. When an ABAP program wants to connect to an AWS service, it will specify an ABAP SDK profile that pulls the necessary settings. An `AUTHORIZATION-CHECK` will be performed to confirm that the user has permissions to access the SDK profile. Your SAP Security Administrator can define a PFCG role granting you access to the appropriate users. ## Logical resource resolver Logical resource resolver enables you with a standard place to store resource names. It ships with SDK for SAP ABAP. Its action is similar to the way that `FILE` transaction maps logical file names to physical file names. A logical resource defines the concept of an AWS resource, such as the Amazon S3 bucket that holds our invoices. This logical resource, for example, can be named `ZINVOICES_OUTBOUND` and it can map to a different physical bucket name, depending on whether the SAP system is development, QA, or production. SDK for SAP ABAP is set up such that a QA system resolves logical resources to the QA physical resources, even after a system refresh from production. The resource mappings for ALL systems is defined in your development SAP system and transported forward. This approach is different from the usual setup in SAP systems where the mapping is handled as master data and set in each system. The advantage of logical resource resolver offered by SDK for SAP ABAP is that the chances of a mistaken transport after system refreshes are almost none. ## Example There are four separate Amazon S3 buckets - one each for development, production, and QA, as well as a second QA bucket for regression testing. When the SDK resolves a logical resource like `ZINVOICE_OUTBOUND` to a physical resource, it checks `SY-SYSID` and `SY-MANDT` to ask *Which SID and client am I running in?*, and automatically selects the correct physical resource. If the mapping of a resource in production needs to change, you must change the mapping in the `IMG` of the development system and transport it forward. This ensures that reassigning AWS resources to an SAP system is subject to change control as with any other transport. **Note** As the SDK configuration is client-dependent, reassignment of resources is transported in a customizing request, and the transport must be imported into each client. # Runtime settings This section covers the following topics. **Note** These settings are not transportable and are local to each SAP system. **Topics** + [Log and trace](#log-trace) + [OPT-IN: enhanced telemetry](#enhanced-telemetry) + [Active scenario](#active-scenario) ## Log and trace You can activate a trace for debugging purposes. It is recommended to keep the trace level at **No Trace**, unless diagnosing a technical issue. For more information, see secure operation. These settings are not applicable to SDK for SAP ABAP - BTP edition. ## OPT-IN: enhanced telemetry All SDKs send telemetry information to AWS for support purposes. You can opt in for enhanced telemetry. This is particularly useful when you contact Support to identify the source of a particular API call. For more information, see [Trace](https://docs.aws.amazon.com/sdk-for-sapabap/latest/developer-guide/additional-topics.html#trace) and [Telemetry](https://docs.aws.amazon.com/sdk-for-sapabap/latest/developer-guide/additional-topics.html#telemetry). These settings are not applicable to SDK for SAP ABAP - BTP edition. ## Active scenario Activate your `DEFAULT` scenario in this transaction. This activation is required only once for each system and should not be changed unless the system is undergoing a multi-Region disaster recovery. In a multi-Region setup, you can use this setting to switch your SAP system to a disaster recovery environment or disaster recovery test scenarios. # Advanced connectivity scenarios AWS SDK for SAP ABAP consumes AWS services by making HTTPS calls to AWS endpoints. In general, AWS endpoints are accessible over the internet. An SAP system must be able to reach out to the internet to establish these outbound connections. SDK for SAP ABAP never requires an inbound connection from the internet into the SAP system. The following scenarios offer different ways to establish the outbound connection. **Topics** + [Connection through a proxy server](#proxy-server) + [Connection through a packet inspecting firewall](#packet-firewall) + [Gateway endpoints](#gateway-endpoints) + [Custom interface endpoints](#interface-endpoints) + [Advanced routing](#advanced-routing) + [Accessing endpoints in multiple Regions](#multiple-regions) ## Connection through a proxy server To establish a connection through a proxy server, use the following steps. 1. In the SDK, go to Transaction **`SICF`**. 1. Choose **Execute**. 1. In the menu, choose **Client** > **Proxy server**. 1. Set **Proxy setting** as **Active**. 1. In the field for **No Proxy for the Following Addresses**, list any exceptions separated by semicolons. 1. In the **HTTP Protocol** and **HTTPs Protocol** fields, specify the connection details for your proxy server. The SDK is unaware of the proxy server, and does not require any settings to use the SAP system's proxy server configuration. **Note** If you use [Amazon EC2 instance metadata authentication](https://docs.aws.amazon.com/sdk-for-sapabap/latest/developer-guide/system-authentication.html#metadata-authentication), then the SAP system cannot use the proxy server to access the local instance metadata at `http://169.254.169.254`. You must include `169.254.169.254` in the field for *No Proxy for the Following Addresses*. ## Connection through a packet inspecting firewall You can configure a packet inspecting firewall for outbound connection. These firewalls decrypt the SSL traffic, and then re-encrypt it before passing it on to the endpoint. This configuration usually requires the firewall to issue its own certificates to the SAP system that is consuming an AWS service. You must install your firewall’s CA certificate in `STRUST`. For more information, see [HTTPS connectivity](https://docs.aws.amazon.com/sdk-for-sapabap/latest/developer-guide/prerequisites.html#https-connectivity). ## Gateway endpoints Some AWS services offer gateway endpoints to provide a VPC with high-performance access without internet. These endpoints are transparent to SDK for SAP ABAP, and do not require any configuration. For more information, see [Gateway endpoints](https://docs.aws.amazon.com/vpc/latest/privatelink/gateway-endpoints.html). ## Custom interface endpoints If you need to override the default endpoint resolution with a custom endpoint, you can use an interface endpoint to provide your VPC with high-performance access without internet. For more information, see [Configure an interface endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/interface-endpoints.html). When not using private DNS, these endpoints have their own DNS addresses, and an ABAP program must explicitly override the usual endpoint resolution logic. For more information, see AWS re:Post – [Why can't I resolve service domain names for an interface VPC endpoint?](https://repost.aws/knowledge-center/vpc-interface-configure-dns) In the following example, an interface endpoint is created for AWS STS and Amazon Translate. The SAP system is not using private DNS, and calls the services with custom endpoint. The logical resources defined in `/AWS1/IMG` represent the physical interface endpoint addresses, such as `vpce-0123456789abcdef-hd52vxz.translate.us-west-2.vpce.amazonaws.com`. This avoids hard coding the DNS in code. In the following code, the logical resources in `/AWS1/IMG` are first resolved to physical endpoint names. They are then provided to the factory methods of AWS session class (that uses AWS STS to assume an IAM role) and translate API class. ``` " This example assumes we have defined our logical endpoints in /AWS1/IMG " as logical resources so that we don't hardcode our endpoints in code. " The endpoints may be different in Dev, QA and Prod environments. DATA(lo_config) = /aws1/cl_rt_config=>create( 'DEMO' ). DATA(lo_resolver) = /aws1/cl_rt_lresource_resolver=>create( lo_config ). " logical resource STS_ENDPOINT should resolve to the interface endpoint " for example vpce-0123456789-abcdefg.sts.us-west-2.vpce.amazonaws.com DATA(lv_sts_endpoint) = lo_resolver->resolve_lresource( 'STS_ENDPOINT' ). " logical resource XL8_ENDPOINT should resolve to the interface endpoint " e.g. vpce-0123456789abcdefg-12345567.translate.us-west-2.vpce.amazonaws.com DATA(lv_xl8_endpoint) = lo_resolver->resolve_lresource( 'XL8_ENDPOINT' ). " the session itself uses the sts service to assume a role, so the " session creation process requires a custom endpoint, specified here DATA(lo_session) = /aws1/cl_rt_session_aws=>create( iv_profile_id = 'DEMO' iv_custom_sts_endpoint = |https://{ lv_sts_endpoint }| ). " now we create an API object, and override the default endpoint with " the custom endpoint DATA(lo_xl8) = /aws1/cl_xl8_factory=>create( io_session = lo_session iv_custom_endpoint = |https://{ lv_xl8_endpoint }| " provide custom endpoint ). " now calls to lo_xl8 go to custom endpoint... ``` As shown in the example, any method calls on `go_xl8` go to the endpoint `https://vpce-0123456789abcdefg-12345567.translate.us-west-2.vpce.amazonaws.com`. It is also possible to define the routing custom endpoint in the IMG configuration instead of in code, as shown in the next section. ## Advanced routing In the previous section we showed how a custom endpoint can be specified in the `iv_custom_endpoint` argument of the factory methods for the SDK modules. As the number of ABAP programs using the SDK increases, this can become difficult to manage. It is possible to configure a mapping from an AWS service to a custom endpoint in the SDK Profile. For each SID, client, and scenario, the service three-letter abbreviation (TLA) can be mapped to an endpoint URL: | TLA | Custom Endpoint URL | | --- | --- | | BDR | https://vpce-23456789abcdef012-3c4d5e6f.bedrock-runtime.us-east-1.vpce.amazonaws.com | | LMD | https://vpce-123456789abcdef01-2b3c4d5e.lambda.us-east-1.vpce.amazonaws.com | | S3 | https://vpce-0123456789abcdef0-1a2b3c4d.s3.us-east-1.vpce.amazonaws.com | With this configuration, you do not need to specify `iv_custom_endpoint` in the factory method calls. The custom endpoint is selected automatically from the configuration table. The configuration is specific to the SDK Profile so you can create multiple profiles with different routing to suit your needs. As with other SDK Profile configuration, the routing is SID and client specific so separate routing can be defined for different systems. ## Accessing endpoints in multiple Regions AWS endpoint is automatically determined from your default AWS Region that is defined in the SDK profile. You can also specify a region programmatically, overriding the default region. This can be overridden in the factory `CREATE()` method, or later with the SDK’s configuration object. For more information, see [Programmatic configuration](https://docs.aws.amazon.com/sdk-for-sapabap/latest/developer-guide/features.html#programmatic-configuration). In the following example, the factory `CREATE()` method is used to set the region and list the Amazon SQS queues in both `us-east-1` and `us-west-2` Regions. ``` REPORT zdemo_sqs_queue_list. parameters: profile type /AWS1/RT_PROFILE_ID OBLIGATORY. START-OF-SELECTION. DATA(go_session) = /aws1/cl_rt_session_aws=>create( profile ). data(lt_region) = VALUE stringtab( ( |us-east-1| ) ( |us-west-2| ) ). LOOP AT lt_region INTO DATA(lv_region). DATA(go_sqs) = /aws1/cl_sqs_factory=>create( io_session = go_session iv_region = conv /AWS1/RT_REGION_ID( lv_region ) ). WRITE: / lv_region COLOR COL_HEADING. LOOP AT go_sqs->listqueues( )->get_queueurls( ) INTO DATA(lo_url). WRITE: / lo_url->get_value( ). ENDLOOP. ENDLOOP. ``` # Service provider settings Basis administrators sometimes need to control certain features of the SDK across the entire system, from client `000`. This is a common scenario for hosting and service providers that operate systems in their own AWS account on behalf of their customers. AWS SDK for SAP ABAP supports Service Provider settings. These settings are configured in client `000`, and affect the SDK across all clients. Service Provider settings are not supported in SDK for SAP ABAP - BTP edition. Service Provider settings are configured in transaction `/AWS1/IMG`, and must be configured in client `000`. Service Provider settings in other clients are ignored. The settings in client `000` take effect across all clients, and supercede other `IMG` settings in case of conflict. Use the following steps to configure the Service Provider settings in client `000`. 1. Expand the **Service Provider Settings** branch in transaction `/AWS1/IMG`. 1. Choose **Service Provider Guardrails** 1. Select **New Entries**, and adjust the settings based on your business requirements. 1. *Disable EC2 Metadata* – prevents the SDK from accessing EC2 instance metadata in all clients, even if an SDK Profile is configured to authenticate using EC2 instance metadata. The SDK raises an exception if an ABAP program attempts to access instance metadata using the SDK. 1. Select **Save**. # Refresh, trace, and telemetry topics for AWS SDK for SAP ABAP This section covers the following topics. **Topics** + [SAP system refresh](#refresh) + [Trace](#trace) + [Telemetry](#telemetry) ## SAP system refresh After a system refresh, the primary challenge for a Basis administrator is to ensure that the separate systems are not accessing each other’s resources. For example, you may want to ensure that your QA SAP system is not accessing the resources, such as an S3 bucket, of your Production landscape. SDK for SAP ABAP provides a safety-conscious approach of *logical resources* to this challenge. A business analyst can take the following steps. 1. Define a logical resource, such as `ZINVOICE_OUTBOUND`. 1. Map all systems and clients in the development system. 1. Transport the configuration of ALL systems forward until the production landscape. **Basis steps after a refresh** 1. Check the authentication + If the system is using Secret Access Key authentication, the SSF-encrypted credentials will be invalid because they are stored in master data. The credentials must be re-entered, which may require regenerating a new Secret Access Key in [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). + If the system is authenticating with EC2 instance metadata, no steps are required. Check the trace settings + In `/AWS1/IMG`, ensure that the trace settings are what you want. These settings are not transportable. ## Trace Trace output is controlled in the **IMG runtime settings**. The trace levels that you can use are: + **No Trace** + **Trace API calls** + **Trace API calls and payload** *This option contains unencrypted payload information.* + **Trace API calls, payload, and internal XML transformation** *This option contains unencrypted payload information.* If API trace is activated, traces are written to `DIR_WORK` in `aws1_trace-YYYY-MM-DD.log` file. If payload trace is additionally activated, additional files with the title `aws1_payload_*` are created for each call and payload component. The payload trace length can be limited with the length limit applying to each individual payload trace fail. Payload traces are primarily intended to collect information to be provided to Support in the event of a serialization error. We recommend that you choose **No Trace** unless you're attempting to diagnose an SDK error. **Note** Payload traces can contain unencrypted business information. We recommend turning these traces on only for a request by AWS Support to help you troubleshoot. You can turn these traces off after resolution. Traces are not automatically deleted, and need to be removed by the system administrator when no longer needed. These settings are not applicable to SDK for SAP ABAP - BTP edition. ## Telemetry SDKs send telemetry information to Support. SDK for SAP ABAP collects the following information: + OS release and patch level + `SAP_BASIS` release and patch level + SAP Kernel release and patch level You can opt in to send the following information to Support. + SAP SID and instance name (`host_sid_nn`) + SAP Client (`SY-MANDT`) + Transaction code (`SY-TCODE`) and report (`SY-REPID`) The additional information enables Support to help you better. Support can detect why a certain API call was made and can further find the relevant transaction in a SAP system. Telemetry is limited to the SDK and API versions for SDK for SAP ABAP - BTP edition.