SAP BW extraction agent

Use the SAP BW Metadata Audit Tool to collect the SAP BW material for a modernAIze assessment. This is the extraction agent referred to in the SAP BW platform guide: a standalone command-line program that runs on a workstation or host with access to SAP BW. It collects metadata, object definitions, and available routines through SAP RFC connectivity.

The usual workflow is to install the supplied distribution, collect a catalog, extract the object detail for the agreed scope, and review the output before uploading it to modernAIze. Business-data sampling is off by default.

Before you start

Arrange the following with the SAP/Basis team:

The documented authorization requirements are S_RFC, S_TABU_DIS for metadata table reads through RFC_READ_TABLE, and read access to the required BW metadata tables, including the RSD*, RST*, RSB*, RSZ*, and RSPC* families. Ask Basis to determine the appropriate authorizations for the target system and scope; successful connection alone does not establish that every object can be read.

The agent uses a direct application-server RFC connection. Confirm that this connection mode fits the target system with Basis before scheduling collection.

Install the agent

Windows portable bundle

The Windows x64 portable bundle includes its Java runtime and SAP Java Connector (JCo). It does not require a separate Java installation, administrator rights, or changes to PATH.

1. Obtain the supplied bw-audit-tool-<version>-win64.zip bundle.
2. Extract it to a path without spaces or non-ASCII characters, such as C:\bw-audit.
3. Locate bw-audit.exe in the extracted bw-audit directory. Keep the adjacent app and runtime directories together with the launcher.
4. Open Command Prompt and change to the launcher directory.

cd /d C:\bw-audit\bw-audit

The examples below use Windows Command Prompt (cmd.exe). The caret (^) continues a command on the next line; it is not PowerShell continuation syntax. Replace the example host, client, account, password, paths, and object names with the values agreed for your extraction.

Standard distribution on Windows, Linux, or macOS

The standard distribution uses a separately installed Java 17 or later and SAP JCo 3.1 with native libraries matching the host platform and architecture.

Use the same options shown below with the appropriate launcher. In a Unix shell, use backslash for multiline continuation and quote wildcard scope values, for example --infoarea 'ZSALES*'. Use the distribution supplied for your engagement.

Collect the catalog

Start with a catalog-only run to establish connectivity and inspect the available metadata. The catalog is Tier 1; detailed object collection is Tier 2.

bw-audit.exe ^
  --host sap-bw.example.com --sysnr 00 --client 100 ^
  --user AUDIT_USER --password "%SAP_BW_PASSWORD%" ^
  --output C:\audit\catalog-run ^
  --tables-only

Before running the commands, provide SAP_BW_PASSWORD in the Command Prompt session using the credential-handling procedure agreed for the extraction host. The examples reference that environment variable instead of embedding a secret. The agent still receives the expanded password as a command-line argument; restrict access to the extraction host and do not save populated commands in assessment notes or the handover package.

Check catalog/, summary.json, and audit.log under the output directory. Confirm that the expected metadata was returned and investigate read failures. A catalog-only run can still read substantial metadata; it is not merely a connection test.

InfoArea scope does not restrict the Tier 1 catalog scan. The --infoarea option selects objects for Tier 2. Combining it with --tables-only does not produce an InfoArea-only catalog. Agree the catalog collection scope with Basis before running the agent.

Extract the required object detail

For a first scoped extraction, collect the catalog and detail together:

bw-audit.exe ^
  --host sap-bw.example.com --sysnr 00 --client 100 ^
  --user AUDIT_USER --password "%SAP_BW_PASSWORD%" ^
  --output C:\audit\sales-run ^
  --infoarea ZSALES ^
  --include-query-detail

This example keeps the full catalog, including the area hierarchy needed to resolve scope, and limits detail by InfoArea. It leaves sampling disabled. The query-detail option includes additional query element metadata in the catalog.

Select the scope

Area matching uses the available InfoArea or Application Component assignment. A bare * is ignored; it is not a useful scope selection. When both InfoArea and object-key filters are supplied, the key filter narrows the objects resolved from the areas. It does not add objects outside the area selection.

If no objects resolve for the selected areas, the detail run exits with code 2. Review the scope message and any suggested area names, check the catalog, and confirm the assignment with a BW specialist before retrying.

Collect DataSources separately when needed

An InfoArea-scoped detail extraction does not include DataSources (RSDS). If DataSource definitions are needed for manual source review, run a separate detail pass without --infoarea, selecting --object-types RSDS and, where appropriate, --object-keys for the required DataSources. Reuse a catalog that includes their metadata, and retain the source-system context when names repeat.

Current modernAIze analysis uses the DataSource catalog and segment-field metadata; when filtering catalog families with --object-types, include RSDS to retain that material. It does not consume the agent’s separate DataSource object-detail files. This extra pass supports the extraction handover and specialist review, not a promise of additional DataSource detail in Understand.

Reuse a catalog for phased extraction

Use a previous run’s catalog when collecting detail in smaller batches:

bw-audit.exe ^
  --host sap-bw.example.com --sysnr 00 --client 100 ^
  --user AUDIT_USER --password "%SAP_BW_PASSWORD%" ^
  --output C:\audit\detail-run ^
  --catalog-dir C:\audit\catalog-run\catalog ^
  --object-types TRFN ^
  --object-keys EXAMPLE_TRANSFORMATION_KEY

Replace the example key with one from the catalog. --catalog-dir skips the new catalog scan; detail extraction still connects to SAP. Use a catalog from the same system and a suitable collection date. If the metadata has changed or the catalog lacks required query detail, collect a new catalog with the required options before continuing.

Keep both runs. The detail-run directory alone may omit the catalog needed for the final handover. Retain each run’s summary and log so omissions can be traced to the relevant collection step.

Command-line reference

Connection and output

Scope and collection options

Sampling has its own scope. It uses ADSO and Cube providers present in the available catalog. --infoarea and --object-keys do not restrict samples, and --tables-only does not disable sampling. Keep --sample-rows at 0 unless that catalog-wide sampling scope has been explicitly approved.

A catalog table can reach --max-rows without a truncation warning. Reconcile its count with the expected inventory before using it as complete. 0 removes the cap; agree the collection volume with Basis before changing it.

Some detail reads still return active versions. Verify the returned version when non-active definitions are part of the assessment.

The documented object-family codes are IOBJ (InfoObject), ADSO, CUBE (InfoCube), TRFN (transformation), RSDS (DataSource), DTPA (data transfer process), RSPC (process chain), QUERY (BEx query), HIER (hierarchy), HCPR (CompositeProvider), AREA (InfoArea), APCO (Application Component), and LSYS (source system). Organizational families provide catalog context; selecting a family does not guarantee the same detail depth for every object.

Review and hand over the extraction

The output is organized as follows. samples/ appears only when sampling is requested.

extraction/
├── catalog/             Metadata inventory
├── objects/             Object detail grouped by family
├── samples/             Optional business-data samples
├── summary.json         Catalog/object counts and extraction errors
├── audit_metadata.json  Extraction time, system, version, and configuration
└── audit.log            Execution log

1. Confirm the source system, collection time, agent version, and intended scope.
2. Compare expected objects with the catalog and the available object-detail files. Check the relevant transformations and routines, not just object names.
3. Read the summary and log for errors, omissions, and read limits. The agent can continue after an individual object fails; reaching the end of a run is not proof of complete extraction.
4. For phased collection, assemble the applicable catalog and object detail while retaining the original runs and their extraction evidence.
5. Review the material approved for transfer. Metadata and routines can contain business logic and infrastructure identifiers. Include business-data samples only when explicitly agreed for the assessment.
6. Package the reviewed catalog and object files for the modernAIze project, following Prepare source inputs. Keep diagnostic logs and provenance available to the team reviewing the extraction.
7. After analysis, reconcile the expected assets with the represented inventory and detail using the SAP BW platform guide.

A zero error count does not establish that the expected routine source was returned. Inspect the relevant object files as well as the summary.

Prepare the import package

Upload the reviewed native JSON through Folder or as one ZIP, preserving catalog/ and objects/<family>/ paths. Do not flatten the package or select its JSON files individually through Files: filenames alone do not identify the catalog and object families. For example:

assessment/
├── catalog/
│   └── RSDIOBJ.json
└── objects/
    └── IOBJ/
        └── 0MATERIAL.json

This tree illustrates paths, not a sufficient inventory for every assessment. Include the actual catalog and all required object families. Keep diagnostic logs, summaries, provenance, and any samples in the extraction handover; select only the material approved for analysis upload. Check that the uploaded paths still contain the catalog and family directories.

A catalog entry is evidence that an object was inventoried. It does not prove that its routines, complete reporting semantics, or all dependency details were collected. CompositeProvider metadata in particular can be flat and lack the complete composition lineage visible in SAP’s native design tools.

Resolve collection problems

Retain the relevant summary, log, agent version, and object identifiers when requesting help. Confirm the missing source material with the SAP team before treating an extraction gap as a limitation of the modernAIze analysis.

Related reading

• SAP BW source platform
• Prepare source inputs
• Review project setup
• Analysis evidence and limitations