SAP OData Explorer Skill

This skill enables Claude to query and explore SAP OData endpoints securely and efficiently.

When to Use This Skill

Activate this skill when the user:

Asks to fetch data from SAP
Wants to query SAP entities or business objects
Needs to explore SAP OData service structures
Mentions SAP terms like BusinessPartner, SalesOrder, Material, Product, etc.
Wants to see metadata or entity definitions
Needs to understand what data is available in SAP

Available Commands

1. Query Entities

Query SAP OData entities with filtering, selection, and pagination.

cd .claude/skills/sap-odata-explorer
npm run query -- --service <service> --entity <entity> [options]

Required Arguments:

--service: OData service name (e.g., API_BUSINESS_PARTNER)
--entity: Entity set name (e.g., A_BusinessPartner)

Optional Arguments:

--filter: OData filter expression (e.g., "Status eq 'Active'")
--select: Comma-separated fields (e.g., ID,Name,Status)
--top: Number of records (e.g., 10)
--skip: Skip records for pagination (e.g., 20)
--orderby: Sort expression (e.g., Name asc)
--expand: Navigation properties (e.g., to_Address)
--output: Custom output filename
--format: Output format (json or pretty)
--no-file: Print to console instead of file

Examples:

# Get first 10 business partners
npm run query -- --service API_BUSINESS_PARTNER --entity A_BusinessPartner --top 10

# Query with filter and select specific fields
npm run query -- --service API_BUSINESS_PARTNER --entity A_BusinessPartner \
  --filter "BusinessPartnerCategory eq '1'" \
  --select BusinessPartner,FirstName,LastName \
  --top 5

# Query with sorting
npm run query -- --service API_BUSINESS_PARTNER --entity A_BusinessPartner \
  --orderby LastName --top 10

# Pretty print to console
npm run query -- --service API_BUSINESS_PARTNER --entity A_BusinessPartner \
  --top 5 --format pretty --no-file

2. Get Metadata

Fetch and explore OData service metadata to understand available entities and their properties.

cd .claude/skills/sap-odata-explorer
npm run metadata -- --service <service> [options]

Required Arguments:

--service: OData service name

Optional Arguments:

--format: Output format (summary, json, or pretty)
--raw: Get raw XML metadata
--output: Custom output filename
--no-file: Print to console

Examples:

# Get summary of service metadata
npm run metadata -- --service API_BUSINESS_PARTNER

# Get full JSON metadata
npm run metadata -- --service API_BUSINESS_PARTNER --format json

# Get raw XML metadata
npm run metadata -- --service API_BUSINESS_PARTNER --raw

# Print to console
npm run metadata -- --service API_BUSINESS_PARTNER --no-file

3. List Services

List common SAP OData services available in the system.

cd .claude/skills/sap-odata-explorer
npm run list-services

Common SAP OData Services

API_BUSINESS_PARTNER: Business partner data (customers, vendors, contacts)
API_SALES_ORDER_SRV: Sales orders and related data
API_PRODUCT_SRV: Product and material master data
API_PURCHASEORDER_PROCESS_SRV: Purchase orders
API_MATERIAL_STOCK_SRV: Material stock and inventory

Workflow Examples

Example 1: User asks "Show me the first 10 active business partners from SAP"

First, use the metadata command to understand the structure:

cd .claude/skills/sap-odata-explorer
npm run metadata -- --service API_BUSINESS_PARTNER --no-file

Then query with appropriate filter:

npm run query -- --service API_BUSINESS_PARTNER --entity A_BusinessPartner \
  --filter "BusinessPartnerIsBlocked eq false" \
  --top 10 --format pretty --no-file

Read and interpret the results from the output

Example 2: User asks "What customer data is available in SAP?"

Check available services:

cd .claude/skills/sap-odata-explorer
npm run list-services

Get metadata for relevant service:

npm run metadata -- --service API_BUSINESS_PARTNER --no-file

Explain the available entities and properties to the user

Example 3: User asks "Get sales orders from last month"

Query with date filter:

cd .claude/skills/sap-odata-explorer
npm run query -- --service API_SALES_ORDER_SRV --entity A_SalesOrder \
  --filter "CreationDate ge datetime'2024-01-01T00:00:00' and CreationDate le datetime'2024-01-31T23:59:59'" \
  --top 50 --format pretty --no-file

Analyze and present the results to the user

OData Query Syntax

Filter Operators

Comparison: eq (equal), ne (not equal), gt (greater than), lt (less than), ge (>=), le (<=)
Logical: and, or, not
Functions: startswith(), endswith(), contains(), length(), tolower(), toupper()

Filter Examples

Status eq 'Active'
Price gt 100
CreationDate ge datetime'2024-01-01T00:00:00'
startswith(Name, 'A')
contains(Description, 'premium') and Price lt 1000

Select Syntax

--select ID,Name,Status
--select BusinessPartner,FirstName,LastName,City

OrderBy Syntax

--orderby Name asc
--orderby CreationDate desc
--orderby LastName asc, FirstName asc

Security Features

This skill implements comprehensive security measures:

Credential Masking: Passwords and tokens are never logged
URL Sanitization: Credentials stripped from URLs before logging
Secure File Storage: Output files stored in configured directory only
Error Handling: Automatic retry with exponential backoff
Audit Trail: All operations logged securely

Output Files

By default, query results are saved to files in the configured output directory (see OUTPUT_DIR in .env).

File locations are printed after each command. Use the Read tool to examine output files:

# After running a query, read the output file
# (The skill will tell you the path)

Error Handling

The skill automatically handles:

Network errors: Retries with exponential backoff
Authentication errors: Clear error messages
Authorization errors: Permission denied notifications
Timeout errors: Automatic retry up to 3 times

Exit codes:

0: Success
1: Generic error
2: Authentication/authorization error
3: Network error

Tips for Claude

Always check metadata first if you're unsure about entity structure
Use --no-file flag when user wants immediate results
Use --top parameter to limit results for exploration
Use pretty format for human readability
Read output files to analyze results before presenting to user
Combine filters for precise queries
Use --select to reduce payload size and improve performance

Installation

If dependencies aren't installed:

cd .claude/skills/sap-odata-explorer
npm install

Configuration

Configuration is managed via environment variables in .env. Key settings:

SAP_HOST: SAP system host and port
SAP_USER: SAP username
SAP_PASSWORD: SAP password
OUTPUT_DIR: Directory for output files (default: ./output)
LOG_LEVEL: Logging level (default: info)

Troubleshooting

Connection Issues

# Test SAP connectivity
cd .claude/skills/sap-odata-explorer
npm run query -- --service API_BUSINESS_PARTNER --entity A_BusinessPartner --top 1 --no-file

View Logs

Error logs are automatically written to ${OUTPUT_DIR}/errors.log

Common Issues

401 Unauthorized: Check SAP credentials in .env
403 Forbidden: User lacks permissions for the operation
404 Not Found: Service or entity name is incorrect
ECONNREFUSED: SAP system is not reachable

Remember

Always activate this skill when SAP data is mentioned
Explore metadata before querying unknown entities
Use filters

sap-odata-explorer