sap-smartform-generator

name	sap-smartform-generator
description	Generate, edit, reconstruct, validate, preview, and safely deploy SAP Smart Forms (SSFO) from PDF, DOCX, XLSX, HTML, or an existing SAP form. Use for AI-assisted document-to-FormSpec extraction, native Smart Forms XML round-trips, ABAP driver generation, abapGit packaging, layout-parity review, activation checks, and governed DEV deployment.

SAP Smart Form AI Generator

Create or edit Smart Forms through a fail-closed, evidence-based workflow. Treat generated XML, previews, mocks, and passing local tests as candidates—not proof that SAP can import, activate, or render the form.

Required references

• Read repository-implementation-patterns.md before generating, importing, or deploying SSFO XML.
• Read formspec-guide.md when creating or repairing a FormSpec.
• Read smartform-node-mapping.md before mapping visual elements to a native SAP export.

Non-negotiable rules

1. Use one canonical form name everywhere: FormSpec, native XML, ABAP driver, package metadata, tests, and transport.
2. Prefer editing a native XML export produced by SAP or abapGit from the target SAP release. Do not invent a generic <abapGit><SF> or <SSFO> schema and call it importable.
3. Require the Smart Forms namespace urn:sap-com:SmartForms:2000:internal-structure and a SMARTFORM root for a native candidate.
4. Preserve release-specific topology, node IDs/references, namespaces, language, and code sections. Normalize volatile metadata only with the abapGit pattern.
5. Keep AI extraction schema-constrained. Send every uncertain field mapping (confidence < 0.95 or requires_review) to human review.
6. Use ARC-1 for supported ADT reads/writes, ABAP driver work, and transport evidence. Do not claim ARC-1 imports SSFO unless a reviewed custom tool proves that capability.
7. Never report deployment success from a mock, dry-run, local XML parse, or HTML preview.
8. Never deploy or release transports to QAS or PRD. Default to dry-run and require explicit approval for DEV mutation.

Workflow

1. Analyze the source: Run analyze_document for PDF, DOCX, XLSX, or HTML. Extract page geometry, text, images, tables, headers, footers, and repeated regions.
2. Inventory the layout: List every visible section and classify it as static text, dynamic field, table/loop, graphic, condition, page command, or unresolved element.
3. Acquire a native baseline: Inspect the existing form and export it from the target SAP release through SAP/abapGit. If no same-form export exists, use a minimal active form exported from the same system/release as the structural baseline.
4. Create FormSpec: Run create_formspec. Preserve source coordinates and review flags in the analysis evidence; use FormSpec only for supported semantic fields.
5. Review and validate: Resolve ambiguous mappings, then run validate_formspec and the offline validator. Stop on schema, DDIC, naming, or MAIN-window errors.
6. Generate by native transformation: Apply the approved FormSpec to the native baseline. Preserve SAP-owned structure and use the abapGit SSFO serializer behavior for round-trip compatibility.
7. Validate the artifact: Run validate_native_ssfo.py. Reject custom wrappers, inconsistent names, missing MAIN window, forbidden template residue, placeholders, or mojibake requiring review.
8. Generate and lint the driver: Use ABAP 7.40-compatible code, SSF_FUNCTION_MODULE_NAME, explicit interface mapping, BAPI return handling, and deterministic exception reporting.
9. Inspect and deploy in DEV: Keep dry_run=True until package, transport, approval token, zero review flags, and a real import adapter are proven. Import with the SAP/abapGit XML_UPLOAD and active STORE lifecycle or an equivalent reviewed adapter.
10. Prove activation: Verify existence and active status in SAP, resolve the generated function module, execute with representative data, and capture the spool/PDF.
11. Prove visual parity: Compare rendered pages, geometry, fonts, borders, colors, logos, images, line wrapping, pagination, and dynamic overflow. A table-count or HTML-only score is insufficient.

Capability contracts

Use these tools only when they are actually registered and healthy:

• analyze_document(path, extract_images, ocr)
• create_formspec(document_analysis, form_name, target_package)
• validate_formspec(formspec_dict)
• generate_smartform_package(formspec_dict, native_baseline)
• inspect_existing_smartform(form_name)
• deploy_smartform(form_name, ssfo_xml, package, transport, target_system, dry_run, confirmed)
• compare_preview(document_analysis, formspec_dict, rendered_pdf)

If a tool is planned, mocked, missing a persistent MCP transport, or lacks a real SAP adapter, stop at artifact generation and report the limitation.

Fail-closed deployment gate

Require all of the following before a DEV mutation:

• confirmed=True, target_system="DEV", valid package, and valid CTS transport;
• approval token for capability sap.smartform.deploy;
• zero unresolved field, placeholder, encoding, DDIC, naming, or template-residue findings;
• native XML preflight success and a reviewed real import adapter;
• SAP lock/enqueue handling, import result, activation status, and rollback plan;
• rendered-PDF comparison accepted by a human reviewer.

Offline validation

python .agents/skills/sap-smartform-generator/scripts/validate_formspec.py --input path/to/formspec.json
python .agents/skills/sap-smartform-generator/scripts/validate_native_ssfo.py --input path/to/form.xml --form-name Z_FORM --forbid-token W_HEADER