sap-odata-explorer

name	sap-odata-explorer
description	Query and explore SAP OData endpoints with secure logging and configurable output. Use this skill when the user needs to fetch data from SAP systems, explore SAP entity structures, or query SAP business objects like BusinessPartner, SalesOrder, Product, etc.
allowed-tools	["Bash","Read"]

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"

1. First, use the metadata command to understand the structure:

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

2. 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
   

3. Read and interpret the results from the output

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

1. Check available services:

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

2. Get metadata for relevant service:

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

3. Explain the available entities and properties to the user

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

1. 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
   

2. 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:

1. Credential Masking: Passwords and tokens are never logged
2. URL Sanitization: Credentials stripped from URLs before logging
3. Secure File Storage: Output files stored in configured directory only
4. Error Handling: Automatic retry with exponential backoff
5. 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

1. Always check metadata first if you're unsure about entity structure
2. Use --no-file flag when user wants immediate results
3. Use --top parameter to limit results for exploration
4. Use pretty format for human readability
5. Read output files to analyze results before presenting to user
6. Combine filters for precise queries
7. 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

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

Remember

• Always activate this skill when SAP data is mentioned
• Explore metadata before querying unknown entities
• Use filters to reduce result size
• Pretty-print for user-facing output
• Explain OData syntax to users when helpful
• Read output files before presenting results