Skip to content

feat(adms): add SAP ADMS module with sync/async clients and BDD tests#138

Open
adwitiyasushant wants to merge 5 commits into
SAP:mainfrom
adwitiyasushant:contrib/adms
Open

feat(adms): add SAP ADMS module with sync/async clients and BDD tests#138
adwitiyasushant wants to merge 5 commits into
SAP:mainfrom
adwitiyasushant:contrib/adms

Conversation

@adwitiyasushant
Copy link
Copy Markdown

@adwitiyasushant adwitiyasushant commented May 26, 2026

Summary

Adds a new sap_cloud_sdk.adms module providing a Python client for SAP's
Attachment Document Management Service (ADMS), along with the shared SDK
building blocks it depends on (IAS X.509 token fetcher, mTLS support, async
HTTP client, telemetry entry).

ADMS is the BTP service that lets agentic and business applications attach
documents to business object nodes (purchase orders, sales orders, etc.) with
virus scanning, scoped downloads, and audit metadata. This module is the
prerequisite for higher-level agent workflows that read/write documents on
behalf of users.

What's included

Public API (sap_cloud_sdk.adms)

  • AdmsClient (sync) and AsyncAdmsClient with sub-namespaces:
    • client.documents.* — document CRUD, content download URLs, scan-state
      gating
    • client.relations.*DocumentRelation lifecycle (create / get / list /
      update / delete) plus draft create-validate-activate-discard flow
    • client.config.*ConfigurationService reads (allowed domains,
      document types, BO node types, type→BO mappings)
  • create_client() / create_async_client() factories that load the IAS
    binding from a mounted secret volume with env-var fallback.

Auth / HTTP

  • IasTokenFetcher (core.auth) — IAS client_credentials flow with the
    resource parameter that scopes the JWT's aud claim to the ADM
    application.
  • AdmsHttp / async variant — typed get / get_list / post / patch /
    delete helpers with OData error → typed exception mapping
    (DocumentNotFoundError, ScanNotCleanError, ConfigError, etc.).
  • mTLS helpers in core.auth._mtls.

Tests

  • 187 unit tests covering models, HTTP layer, sub-namespace APIs, retry/error
    mapping, and config resolution.
  • pytest-bdd integration tests with Gherkin scenarios
    (tests/adms/integration/document_flow.feature,
    async_flow.feature) — skipped when the service URL isn't configured.
  • Adds Module.ADMS to the telemetry enum.

Why one squashed commit

This branch was rebased onto main and squashed before opening the PR to
remove unrelated UCL prototype commits and version drift. Full review-by-review
history is preserved on my fork at backup/contrib-adms-pre-rebase.

Verification

uv run ruff check src/sap_cloud_sdk/adms/   #
uv run ty check --python-version 3.11 src/sap_cloud_sdk/adms/   #
uv run python -m pytest tests/adms/unit/ -q   # ✓ 187 passed

Adds a full-featured ADMS (Attachment Document Management Service) module to the SDK with sync and async clients, IAS X.509 token authentication, OData V4 service support (DocumentService, ConfigurationService, AdminService), and pytest-bdd integration tests with Gherkin scenarios.

Also adds shared SDK building blocks consumed by ADMS: IAS token fetcher, mTLS support, async HTTP client, and the ADMS telemetry module entry.

> **Disclaimer:** Do not include SAP-internal or customer-specific information in this PR (e.g. internal system URLs, customer names, tenant IDs, or confidential configurations). This is a public repository.

## Description

Provide a clear description of your changes here.

## Related Issue

Closes #<issue_number>

(Link to the GitHub issue this PR addresses)

## Type of Change

Please check the relevant option:

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Dependency update

## How to Test

Describe how reviewers can test your changes:

1. Step 1
2. Step 2
3. Expected result

## Checklist

Before submitting your PR, please review and check the following:

- [ ] I have read the [Contributing Guidelines](../CONTRIBUTING.md)
- [ ] I have verified that my changes solve the issue
- [ ] I have added/updated automated tests to cover my changes
- [ ] All tests pass locally
- [ ] I have verified that my code follows the [Code Guidelines](../docs/GUIDELINES.md)
- [ ] I have updated documentation (if applicable)
- [ ] I have added type hints for all public APIs
- [ ] My code does not contain sensitive information (credentials, tokens, etc.)
- [ ] I have followed [Conventional Commits](https://www.conventionalcommits.org/) for commit messages

## Breaking Changes

If this PR introduces breaking changes, please describe:

- What breaks
- Migration path for users
- Alternative approaches considered

## Additional Notes

Add any additional context, screenshots, or information that would help reviewers.

@adwitiyasushant adwitiyasushant requested a review from a team as a code owner May 26, 2026 13:10
@cla-assistant
Copy link
Copy Markdown

cla-assistant Bot commented May 26, 2026

CLA assistant check
All committers have signed the CLA.

Adds a full-featured ADMS (Attachment Document Management Service) module
to the SDK with sync and async clients, IAS X.509 token authentication,
OData V4 service support (DocumentService, ConfigurationService,
AdminService), and pytest-bdd integration tests with Gherkin scenarios.

Also adds shared SDK building blocks consumed by ADMS: IAS token fetcher,
mTLS support, async HTTP client, and the ADMS telemetry module entry.
Required by upstream's "Enforce version bump when src/ is modified" CI check.
- Revert global [tool.pytest.ini_options] integration marker description and
  remove asyncio_mode=auto so the change does not leak into other modules'
  test runs.
- Extract /etc/secrets/appfnd and CLOUD_SDK_CFG as module-level constants in
  adms/config.py for consistency with the existing _SERVICE_PATH /
  _ADMIN_SERVICE_PATH constants.
Upstream's data-anonymization PR (SAP#93) also bumped to 0.20.0 — bumping
to 0.20.1 to satisfy the version-bump CI check on the rebased branch.
Required for pytest-asyncio strict mode (the project default after
asyncio_mode auto was scoped out). Matches the convention already in
use in tests/agentgateway/.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant