# S4hana Create Record

> Generic create-record fallback for SAP S/4HANA Cloud Public or on-prem private edition. Use when the user wants to create / post / add / generate / seed a record type that does NOT have a dedicated specific skill — for example fixed asset masters, purchase requisitions, purchase contracts / outline agreements, inbound deliveries, sales orders, billing documents, work centers, classification data,…

- **Type:** Skill
- **Install:** `agentstack add skill-ilia-inovaflow-s4hana-create-record-skills-s4hana-create-record`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ilia-inovaflow](https://agentstack.voostack.com/s/ilia-inovaflow)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ilia-inovaflow](https://github.com/ilia-inovaflow)
- **Source:** https://github.com/ilia-inovaflow/s4hana-create-record-skills/tree/main/skills/s4hana-create-record

## Install

```sh
agentstack add skill-ilia-inovaflow-s4hana-create-record-skills-s4hana-create-record
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# s4hana-create-record (generic create fallback)

Research-on-the-go creator for any SAP S/4HANA entity that doesn't have a dedicated specific skill yet. **⚠️ Unverified path — every record type encountered here should be probed once and confirmed by the user before bulk creation.**

## Phase 0 — Setup check (MANDATORY, no exceptions)

**Before any API call, before any tool use, do this check. Even if you already know credentials from earlier in the conversation — IGNORE that knowledge and re-check from scratch each invocation.**

1. **Announce**: tell the user "Checking for SAP credentials in ``..."
2. **Check ONLY these two sources:**
   - A `.env` file at `./.env` (in the current working directory — NOT parent dirs, NOT `~/.env`, NOT any memory file)
   - Shell-exported env vars: `SAP_HOST` AND `SAP_AUTH_MODE` both present
3. **If neither**: auto-create `./.env` from the bundled template (curl from `https://raw.githubusercontent.com/ilia-inovaflow/s4hana-create-record-skills/main/.env.example`), append `.env` to `.gitignore` if not already there, tell the user clearly what to fill in (auth mode + host + creds), and **wait** for them to say "ready" before making any API call. Never overwrite an existing `.env`.
4. **If credentials are present**: report back to the user: "✓ Loaded credentials for `` in `` mode. Proceeding with [task]."

**Never use credentials from conversation memory, from another project's `.env`, or from any tenant the user previously worked with in a different session.** Each project gets its own `.env`. See [`shared/setup-check.md`](../../shared/setup-check.md) for the full rationale and edge cases.

## When to trigger

Use this skill ONLY when a more specific skill doesn't match. Defer to specific skills first:

| User intent | Use this generic skill? |
|---|---|
| "Create supplier invoice" | ❌ → `s4hana-create-invoice` |
| "Create PO" / "create purchase order" | ❌ → `s4hana-create-po` |
| "Create supplier / vendor / customer / BP" | ❌ → `s4hana-create-business-partner` |
| "Create service entry sheet" | ❌ → `s4hana-create-service-entry-sheet` |
| "Create PIR / purchasing info record" | ❌ → `s4hana-create-pir` |
| "Create goods receipt / material document" | ❌ → `s4hana-create-goods-receipt` |
| "Create PO confirmation / supplier confirmation" | ❌ → `s4hana-create-po-confirmation` |
| "Update / change / modify any existing record" | ❌ → `s4hana-update-record` |
| "Create asset master / fixed asset" | ✅ |
| "Create purchase requisition" | ✅ |
| "Create purchase contract / outline agreement" | ✅ |
| "Create inbound delivery / ASN" | ✅ |
| "Create sales order" | ✅ |
| "Create billing document" | ✅ |
| "Create production order / work center / classification" | ✅ |
| Anything else creatable on S/4HANA not in the deferred list above | ✅ |

## Hard rules

1. ⚠️ **Always warn the user**: "Unverified path — confirm before bulk." Even after a successful 1-record probe, don't run >5 records without explicit confirmation.
2. Always do a 1-record live POST as a probe before bulk (≥3 records).
3. Never invent master-data IDs — check tenant for existence first.
4. If a required field has no sensible default and the user didn't specify → ask once, then auto-pick.
5. Scripts go in a per-session temp folder under the user's current working directory (e.g. `/.s4hana-tmp/create--/`). Never commit, never modify `.env`.
6. POSTs are sequential with 200ms delay; halt on 3 consecutive failures.

## Phases

### Phase 1 — Identify the right service & entity

For a user request "create X":

1. Search SAP API Hub or the tenant `/sap/opu/odata/sap/` for services whose name contains relevant keywords.
2. Common patterns:
   - `API__PROCESS_SRV` for process-driven entities (PR, contract, etc.)
   - `API_` for master data (e.g. `API_FIXEDASSET`, `API_PURCHASEREQ_PROCESS_SRV`)
   - Some entities use SOAP A2X instead of OData V2 — check the comm arrangement scenario in Fiori
3. If unsure which service, ask the user — don't guess.

### Phase 2 — Fetch metadata

```
GET /sap/opu/odata/sap//$metadata?sap-client=
```

Parse the EntityType definition for the target entity:

- Required fields (`Nullable=false` and not auto-generated)
- Field types (Edm.String / Edm.Decimal / Edm.DateTime — affects format)
- Navigation properties (for deep-insert candidates)
- Annotations like `sap:creatable=false` (creation blocked on this entity)

If `creatable=false` on the entity → STOP. Surface to user. Likely needs a different endpoint (SOAP A2X) or a different entity.

### Phase 3 — Build minimal payload

Start with ONLY the fields marked Required + the user's specified values. Skip optional fields. SAP error messages are descriptive — let SAP tell you what else is needed.

For dates: OData V2 uses `/Date()/` not ISO 8601.
For amounts: typically string-decimal in JSON.

### Phase 4 — Probe POST + iterate on errors

1. CSRF flow if writing via OData V2 (see `../s4hana-create-po/references/csrf-flow.md` for the verified pattern).
2. POST minimal payload.
3. Read error message:
   - "Fill in mandatory field 'X'" → add X, retry
   - "Field 'X' value 'Y' not allowed" → check valid values via `references/error-decoder.md` (sweep technique)
   - "Configuration settings need to be corrected" → tenant config gap. STOP and report. Do NOT bulk.
   - 403 / authorization errors → comm user lacks scope. STOP and report.
4. Repeat until success or unsolvable. Cap at ~10 iterations — beyond that, the entity needs research.

### Phase 5 — Confirm with user before bulk

Once probe succeeds:

- Show the user: target ID, key fields, response summary
- Ask: "Probe succeeded. Want me to also save the working envelope template to disk and run the full bulk batch?"
- Only proceed to bulk after explicit yes.
- If user requests bulk before probe-confirmation, refuse politely and explain why.

### Phase 6 — Bulk + log

Same idempotency pattern as the specific skills (`create-log.jsonl`).

### Phase 7 — Promote to specific skill (suggest)

After successfully posting ≥3 records of an entity type, suggest to the user:

> "This entity is now verified. Consider extracting a dedicated `s4hana-create-` skill so future runs skip the probe phase."

The user can then ask for skill extraction → see [`references/promote-checklist.md`](references/promote-checklist.md) for the steps.

## Output structure

```
/.s4hana-tmp/create--/
├── metadata-snippet.xml      # the EntityType definition
├── probe-attempts.jsonl      # iterations of minimal payloads + errors
├── working-envelope.json     # the successful payload shape
├── create-log.jsonl          # bulk run log
└── results.json              # final summary
```

## Reference files

- [`references/error-decoder.md`](references/error-decoder.md) — common SAP message classes and how to interpret them
- [`references/promote-checklist.md`](references/promote-checklist.md) — when and how to graduate an entity from generic to specific skill

## Current Phase 2 candidates (not yet promoted)

Track which generic-handled entities have been verified ≥3 times. Realistic candidates for future promotion (entities common in procurement / finance demos but not yet covered by a specific skill):

- `s4hana-create-purchase-requisition` (upstream of PO — `API_PURCHASEREQ_PROCESS_SRV`)
- `s4hana-create-purchase-contract` (outline agreements — `API_PURCHASECONTRACT_PROCESS_SRV`)
- `s4hana-create-inbound-delivery` (ASN — `API_INBOUND_DELIVERY_SRV`)
- `s4hana-create-product-description` (master-data overrides; `A_ProductDescription` PATCH — also covered by `s4hana-update-record`)
- `s4hana-create-asset-master` (fixed asset master)
- `s4hana-create-sales-order` (outbound side of order management)

Note: `s4hana-create-pricing-condition` is unlikely to need its own skill — PIRs auto-generate pricing condition records as a side-effect (documented in `s4hana-create-pir`).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ilia-inovaflow](https://github.com/ilia-inovaflow)
- **Source:** [ilia-inovaflow/s4hana-create-record-skills](https://github.com/ilia-inovaflow/s4hana-create-record-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ilia-inovaflow-s4hana-create-record-skills-s4hana-create-record
- Seller: https://agentstack.voostack.com/s/ilia-inovaflow
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.