README

What this module does

Conneqt_SapBase is the foundation module for SAP integrations in this Magento 2 codebase.

In short, it:

• stores the SAP connection settings in Magento configuration
• creates and maintains an authenticated SAP HTTP client
• retries login and request calls when SAP rate-limits or expires the session
• caches SAP session cookies between requests
• exposes SAP-related customer and address data on orders through extension attributes
• adds an admin Test Connection button so configuration can be checked from the Magento backend

This module does not contain a full business flow by itself. Instead, it provides the shared SAP connection and order-enrichment pieces that other SAP-related modules can build on.

Packages that use this module

This module is intended to be shared by other SAP-related Magento packages.

Known packages using it include:

• conneqt/module-sap-my-account
• conneqt/module-sap-service-layer-special-prices

Dependency

This module depends on Conneqt_Base.

See:

• composer.json
• etc/module.xml

How it works

1. Configuration is read from Magento admin

The module adds a SAP configuration section in the Magento admin where you can configure:

• SAP base URL
• username and password
• company database
• optional API manager header key/value
• default request timeouts
• login-specific timeouts and retry limits
• cooldown after repeated login failures
• optional proxy settings
• request/response logging

Main files:

• etc/adminhtml/system.xml - defines the admin configuration fields
• etc/config.xml - provides default timeout, retry, cooldown, and logging values
• Helper/ScopeConfigHelper.php - reads the configured values for the current store scope

2. A reusable SAP client is created

Helper/SapClient.php is the low-level integration helper.

It is responsible for:

• building the Guzzle client with the configured base URL and headers
• adding the optional proxy configuration
• loading cached SAP cookies into a cookie jar
• logging in when no valid SAP session is available
• saving updated cookies back into Magento cache
• preventing repeated failed logins by storing a temporary cooldown flag

This means the module tries to reuse the SAP session instead of logging in again on every request.

3. API calls go through a wrapper helper

Helper/Api.php wraps the actual GET, POST, and PATCH requests.

This helper:

• uses the shared client from SapClient
• logs requests and responses when logging is enabled
• saves cookies after successful calls
• retries when SAP returns HTTP 429
• tries to log in again when SAP returns HTTP 401

This keeps the SAP request behavior consistent for any module that uses this helper.

4. SAP data is added to order extension attributes

The module extends Magento order and order address data with SAP-specific values.

Exposed order extension attributes:

• sap_interncode
• card_code

Exposed order address extension attributes:

• sap_address_name
• sap_address_type

Main files:

• etc/extension_attributes.xml - declares the extra API attributes on orders and order addresses
• etc/di.xml - registers plugins on Magento\Sales\Api\OrderRepositoryInterface
• Plugin/Order/SapInternCodePlugin.php - copies the customer SAP internal code onto loaded orders
• Plugin/Order/CardCodePlugin.php - copies the customer card code onto loaded orders
• Plugin/Order/SapAddressPlugin.php - copies SAP address metadata from customer addresses onto order addresses

These plugins run after Magento loads orders from the repository, so API consumers and custom code can read the SAP values from extension attributes.

5. Customer and address attributes are created during setup

The module adds custom EAV attributes used by the plugins.

Customer attributes:

• card_code
• sap_interncode

Customer address attributes:

• sap_address_name
• sap_address_type

Main files:

• Setup/Patch/Data/AddCustomerAttributesPatch.php - creates the card_code customer attribute
• Setup/Patch/Data/AddCustomerInternCodePatch.php - creates the sap_interncode customer attribute
• Setup/Patch/Data/AddAddressAttributesPatch.php - creates the SAP address fields on customer addresses

These attributes are mainly intended for admin-side maintenance and for exposing SAP values on order data after an order is loaded.

6. Admin users can test the connection

The module includes a backend button for testing the current SAP configuration.

How that flow works:

1. the system config page renders a custom button
2. a small admin JavaScript file sends an AJAX request when the button is clicked
3. the controller clears cached config/session state and tries to create a fresh SAP client
4. the result is returned as JSON and shown in the admin UI

Main files:

• Block/Adminhtml/Config/TestConnectionButton.php - renders the custom config field/button
• view/adminhtml/templates/system/config/test-connection-button.phtml - button markup and Magento init script
• view/adminhtml/web/js/test-connection.js - sends the AJAX request and shows success/error feedback
• Controller/Adminhtml/Config/TestConnection.php - performs the actual connection test and returns JSON

Important files at a glance

• composer.json - package metadata and dependency on conneqt/m2-base
• registration.php - registers the Magento module
• etc/module.xml - declares the module and its dependency sequence
• etc/adminhtml/system.xml - admin configuration UI for SAP settings
• etc/config.xml - default config values
• Helper/ScopeConfigHelper.php - central config lookup helper
• Helper/SapClient.php - authenticated SAP client, cookie cache, login retry handling
• Helper/Api.php - request wrapper with logging and automatic retry/login refresh
• etc/extension_attributes.xml - declares extra order and order-address attributes
• etc/di.xml - plugs SAP enrichment into order repository results
• Plugin/Order/*.php - fills order extension attributes with SAP values
• Setup/Patch/Data/*.php - creates customer and address EAV attributes used by the integration
• Controller/Adminhtml/Config/TestConnection.php - admin connection test endpoint

Typical usage in custom code

If another module needs to call SAP, it should usually use:

• Conneqt\SapBase\Helper\Api for request execution
• Conneqt\SapBase\Helper\SapClient only when low-level client access is needed

If another module needs SAP values on loaded orders, it can read them from the order extension attributes populated by this module.

Notes

• Configuration is store-scoped through ScopeConfigHelper
• SAP cookies and login-failure state are cached in Magento cache
• Logging is optional and can affect performance if many SAP calls are made
• The module is intended as shared infrastructure for SAP integrations, not as a complete end-user feature on its own