OpenApiImportModule Migration Guide

Overview

OpenApiImportModule is a retired workflow compatibility shell. Production version 1.0 exposed the module with no declared inputs or outputs, while workflow execution only logged that directory-based import was disabled. The class also contained a local Path parser helper that could not establish tenant ownership, retain the source artifact, or return a workflow-safe import receipt by itself.

Version 2.0 keeps the Java class and Spring bean loadable for saved workflows and for the existing authenticated controller helper, but hides the module from new Workflow Studio catalogs. Workflow execution now returns deterministic MODULE_RETIRED, performs no file, network, parser, persistence, or tenant-data work, and directs operators to the OpenAPI Design Center.

The supported path is POST /v1/openapi/import. That controller requires ADMIN or LOAD_OAS, stores the uploaded source in tenant-scoped artifact storage, parses a controller-managed temporary file, persists OasOpenAPISpec, and deletes the temporary file.

Usage

1. Find saved workflow tasks whose module type is OpenApiImportModule.
2. Remove worker-local paths, inline documents, remote URLs, overwrite flags, and any credentials embedded in those values.
3. Open the OpenAPI Design Center or call the authenticated multipart endpoint.
4. Upload one YAML or JSON document as the file form part.
5. Require the HTTP 201 Created response and persisted OasOpenAPISpec.id as the durable import receipt.
6. Use the stored spec from the Design Center for validation, editing, generation, or a later governed workflow.

Inputs

The retired workflow module ignores every legacy input.

Name	Type	Required	Description
path	string	no	Legacy worker-local path; never opened.
source	string	no	Legacy inline document or remote URL; never parsed or fetched.
overwrite	boolean	no	Legacy persistence option; never applied.

The replacement endpoint accepts exactly one multipart file containing an OpenAPI YAML or JSON document. The caller cannot choose a server-local path.

Outputs

The compatibility shell always returns:

Name	Type	Description
status	string	Always error.
error	object	Safe MODULE_RETIRED, retryable:false, and migration guidance.

The authenticated endpoint returns the persisted OasOpenAPISpec with its API-owned identifier on success.

IntegrationAccount Requirements

Neither the retired shell nor the supported controller uses an IntegrationAccount. Do not place API keys, bearer tokens, usernames, passwords, or signed URLs in a legacy path or source value.

The supported endpoint uses the authenticated ValkyrAI principal and generated RBAC. The principal must have ROLE_ADMIN or LOAD_OAS; tenant artifact ownership and persisted spec access remain subject to generated ACL behavior.

Configuration

The compatibility shell has no active configuration. Saved path, source, and overwrite values are ignored.

Use a multipart request for the supported import:

curl --fail-with-body \
  -H "Authorization: Bearer REDACTED" \
  -F "file=@openapi.yaml;type=application/yaml" \
  https://api-0.valkyrlabs.com/v1/openapi/import

Treat the credential above as illustrative only. Use the normal authenticated session and never place a token in workflow configuration, source control, logs, or documentation.

Operations

OpenApiImportModule supports only one workflow compatibility operation: reject execution and identify the migration target.

The OpenAPI Design Center supports importing, editing, validating, and launching stored specs. The import controller performs one bounded upload-to-persistence transaction:

1. validate a non-empty multipart file;
2. normalize the original filename;
3. write a controller-managed temporary parser file;
4. store the source artifact under tenant scope;
5. parse and persist OasOpenAPISpec with the stored source path;
6. delete the temporary file; and
7. delete the stored artifact if parsing or persistence fails.

Errors and Failure Modes

Failure	Behavior	Recovery
Any legacy workflow execution	Returns MODULE_RETIRED with retryable:false.	Migrate to the Design Center; retries cannot re-enable local paths.
Empty upload	Endpoint returns 400 Bad Request.	Supply one non-empty YAML or JSON file.
Caller lacks authority	Generated RBAC denies the request.	Use an authorized principal; do not bypass the guard.
Artifact storage fails	Import fails without a durable spec receipt.	Correct tenant storage health, then retry the known-idempotent upload intentionally.
Parsing or mapping fails	Endpoint returns 422 Unprocessable Entity and removes the stored artifact.	Correct the OpenAPI document and upload it again.
Persistence returns no ID	The helper treats the operation as failed.	Reconcile storage and database health before retrying.
Temporary-file cleanup fails	The controller logs a bounded cleanup warning.	Inspect the configured temporary directory and host policy.

Example

A saved workflow reaches the compatibility shell:

{
  "path": "/tmp/private-spec.yaml",
  "overwrite": true
}

Expected result:

{
  "status": "error",
  "error": {
    "code": "MODULE_RETIRED",
    "message": "OpenApiImportModule is retired; import through the authenticated OpenAPI Design Center",
    "retryable": false,
    "migrationTargets": ["OpenAPI Design Center", "POST /v1/openapi/import"]
  }
}

Notes

• Pagination: neither the compatibility shell nor the single-file import endpoint paginates.
• Limits: the shell returns immediately. Upload, parser, request, and tenant-storage limits are owned by the authenticated API deployment.
• Idempotency: the compatibility response is deterministic and side-effect free. The import endpoint persists an artifact and spec; reconcile an ambiguous response by the returned spec identifier or stored source record before retrying.
• API constraints: the supported endpoint accepts multipart YAML or JSON, not server-local paths or caller-controlled persistence destinations.
• Network behavior: the compatibility shell performs no network access. The replacement uses only the normal authenticated ValkyrAI API request.
• Destructive behavior: the shell performs none. On a failed import, the controller deletes only the new tenant artifact created for that attempt and its temporary parser file.
• Runtime deployment: source, tests, and documentation can be merged and published independently, but live Workflow Studio will continue to show version 1.0 until a normal backend deployment includes version 2.0.
• Unverified boundary: deterministic tests prove fail-closed workflow output, secret non-disclosure, repeatability, missing-file rejection, metadata discovery exclusion, and direct compatibility lookup. This run does not upload a production OpenAPI document or redeploy the backend.