Extensibility

Extensibility Guide

Custom object types belong to an activated direct subclass of ZCL_SAP_DEV_OBJECT_HDLR. Its lifecycle declaration supplies exact repository/native identities, supported operations, artifact aspects and routing. Use the supplied ABAP reference set that matches the installed runtime.

MCP tool	Purpose
sap_execute_ext_method	Executes an approved, activated extension method with structured JSON parameters.

Mechanism	Entry point	Use
Object lifecycle extension	ZCL_SAP_DEV_OBJECT_HDLR	Declare a custom type and implement its lifecycle or delegate supported operations to native ADT.
Backend routine	ZCL_SAP_DEV_RPC_EXT, sap_execute_ext_method	Execute a reviewed, activated ABAP routine with JSON parameters.
File classification	sap_register_file_extension	Classify an artifact extension as text or binary.

1. Discover One System and Type

Call sap_get_supported_capabilities for the target system. A compact summary page contains at most 20 entries by default; limit accepts 1–100. Filter by repository_type, exact adt_type, operation (template, create, fetch, push, activate) and aspect to retrieve the relevant declarations:

{
  "workspace_dir": "C:/work/sap-project",
  "system_alias": "DEV-100",
  "repository_type": "ZFOO",
  "adt_type": "ZFOO/A",
  "operation": "push",
  "aspect": "metadata",
  "limit": 20
}

Continue with next_cursor using the same system and filters. Restart without a cursor after a catalog change. Each operation reports supported, unsupported, unverified, or not_applicable and a technical reason when needed. A declaration identifies implemented behavior; the requested operation checks target-system applicability, permissions and prerequisites again. A reference-derived XML template alone establishes neither a writable lifecycle nor activation support.

Create and maintain packages manually in SAP. Select an existing package for object development; package browsing and package metadata used for authorization and transport checks remain available.

2. Implement a Backend Object Lifecycle

Create a concrete, publicly instantiable direct subclass of ZCL_SAP_DEV_OBJECT_HDLR, redefining describe_lifecycle and, for procedural behavior, execute_lifecycle. Inspect their typed signatures in the supplied backend reference. Activate the class before discovering or invoking it.

describe_lifecycle returns a table of contracts:

Field	Contract
repository_type, adt_type	Exact four-character owner and optional exact native variant with the same prefix. An owner with multiple variants requires selecting one variant explicitly.
provider	backend_handler for procedural execution, or native_adt for the generic native adapter.
extension, sub_type	Artifact extension (.abap, .xml, .json) and optional single staging directory. Metadata uses XML and translations use JSON.
operations	Explicit operation, aspect, state, and optional technical reason. Artifact operations identify source, metadata, or translations; activation applies to the object and has an empty aspect.
binding	Local object identity URI under /sap/bc/adt/ containing one {name}. Native delegation also supplies the exact XML root namespace/element, creation collection, optional advertised creation MIME type, same-type default reference and full-XML choice.

The framework assigns the handler identity and contract revision from the declaration and active class implementation. Discovery is scoped to the selected system and refreshed for each request. Each identity has one owner; duplicate claims fail. Bundled types retain their supplied workflows.

Keep describe_lifecycle read-only, deterministic and independent of the target object's current state. Mark a behavior supported only after implementing its complete lifecycle. Declare not_applicable for operations such as separate activation when saving already makes the object active. Preserve native SAP authorization checks; the framework also checks development authorization for the resolved target and activity.

For provider: "backend_handler", execute_lifecycle receives the exact identity, handler revision, operation, aspect, object name, payload, package, approved transport and expected_revision. Return the supplied typed lifecycle result:

Operation	Required result and behavior
template	success = abap_true, status = 'template', and XML content identifying the exact core name/type and existing package for the new metadata artifact. Prepare content without creating or changing an object.
fetch	success = abap_true, status = 'active' or 'inactive', exact content, and a nonempty opaque revision. Readback is required for saves and activation verification.
create	Require expected_revision = 'new' and fail if the object already exists.
push	Require a fetched expected_revision; compare it under the owned SAP lock before changing the object.
create, push	Use native CTS and authorization APIs, honor the approved transport, return saved_active or saved_inactive and the actual transport. Release every owned lock and connection on success, error and timeout.
activate	Run the native activation operation, return status = 'activated', and make the final active content observable through the declared fetch aspect.

Set success only after completion. Return technical error_code, return_code, and cleanup_error for failures. Save confirmation includes independent content/state readback; a failed confirmation reports an unverified outcome and requires inspection before retrying. Normal Object Guard and transport approval apply before mutation. A template carries the new-object precondition; editing an existing object starts with sap_fetch(for_editing: true).

For provider: "native_adt", declare only operations expressible by the generic metadata adapter. Reference templates must match the exact native type and XML root, and their collection and XML MIME format must be advertised by the selected system. Custom source and translation behavior use a procedural handler. Custom URI substitutions identify the declared object; caller-provided alternate targets are rejected. The native adapter requires a technical adtcore:version and a nonempty ETag on readback. Its save confirmation compares the substantive XML definition while excluding administrative version/author/timestamp attributes and navigation links. A full-XML creation sends the definition in the creation request; shell creation also requires the declared metadata push operation. Template staging preserves any existing draft. Native mutations recheck the declaration revision before acquiring locks and writing, and deterministically release owned locks.

SQLite object-type routing and external executable hooks are retired. Historical rows remain preserved for inspection and migration; the active extension contract resides in the backend handler. Use the regular fetch, template, push and activation tools after activation and discovery.

3. Backend ABAP RPC Extensions

Use ZCL_SAP_DEV_RPC_EXT for a custom RFC/BAPI routine or a reviewed operational procedure. Configure the SAP-Bridge SICF service to use this supplied extension class. Add a public instance method with the extension contract:

METHODS my_routine
  IMPORTING iv_params TYPE string
  RETURNING VALUE(rv_result) TYPE string.

The method receives JSON parameters in iv_params; return valid JSON in rv_result for a structured tool result. Edit, syntax-check, and activate the ABAP source through the normal developer workflow, then authorize the method in Execution Guard before calling sap_execute_ext_method.

The supplied EXECUTE_SCRATCHPAD method executes the activated scratchpad implementation. Its bundled greeting example accepts action and name:

{
  "workspace_dir": "C:/work/sap-project",
  "system_alias": "DEV-100",
  "method_name": "EXECUTE_SCRATCHPAD",
  "params": {
    "action": "HELLO_WORLD",
    "name": "Developer"
  }
}

Use the connected target system's alias in place of DEV-100. Implement and activate any additional scratchpad actions before invoking them; parameters are input to compiled ABAP routines. Execution Guard authorizes the selected method and can pin approval to its code version when configured. Review the routine's effects when approving it.