PipelineModule Migration Guide

Overview

PipelineModule is a retired compatibility shell. Version 1.0 only incremented an in-memory counter, logged execution, and returned GOOD; it did not invoke another ExecModule, map data, persist workflow state, resolve an IntegrationAccount, or call a provider. That false-success behavior made an unusable module appear healthy in Workflow Studio.

Version 2.0 keeps the Java class and Spring bean loadable so saved workflows can be inspected and migrated, but hides the module from new Workflow Studio catalogs. Execution now fails closed with MODULE_RETIRED, performs no network or credential work, and returns explicit migration targets.

Use ValkyrAI's native pipeline model instead: a workflow contains ordered tasks, and each task contains an ordered ExecModule chain. Choose dedicated modules for each transformation or provider operation.

Usage

1. Find saved workflow tasks whose module type is PipelineModule.
2. Record the intended source, transformation, provider operation, and destination. Do not infer those steps from the legacy module's successful status; version 1.0 never executed them.
3. Replace the legacy task with ordered tasks and dedicated ExecModules.
4. Map only the required outputs into the next task and bind provider credentials through IntegrationAccount relationships.
5. Run the migrated workflow in a non-production environment and verify provider-side state before production activation.

Inputs

The retired module accepts no operational inputs. Any legacy moduleData, config, workflow state, OpenAPI specs, endpoints, headers, or credential-like values are ignored and never transmitted.

For replacement modules, use their canonical typed inputs:

Need	Replacement	Input guidance
Deterministic field mapping	MapModule	Supply source items and an explicit field map.
Bounded REST call	RestApiModule	Supply the HTTPS destination, method, path, bounded body, and confirmation for writes.
Bounded GraphQL operation	GraphQLModule	Supply endpoint, operation type, document, and typed variables.
Provider-specific action	Dedicated provider module	Prefer the provider module over a generic transport when one exists.

Outputs

The compatibility shell always returns:

Name	Type	Description
status	string	Always error.
error	object	Safe MODULE_RETIRED, a non-retryable flag, and migration targets.

It never emits a success result, pipeline counter, provider response, copied workflow state, or input content.

IntegrationAccount Requirements

PipelineModule never resolves or uses an IntegrationAccount. Do not attach credentials to it.

Bind credentials only to the replacement provider module. The account must be READY, scoped to the exact provider and destination, and limited to the permissions required by the migrated step. Never copy secrets into workflow inputs, mappings, logs, examples, or error branches.

Configuration

The retired module has no active configuration. A saved task may retain legacy fields for persistence compatibility, but they have no effect.

A migrated workflow should express each step independently. For example:

{
  "tasks": [
    {"name": "map-customer", "moduleType": "MapModule"},
    {"name": "create-ticket", "moduleType": "RestApiModule"}
  ]
}

This is a conceptual workflow excerpt, not a complete generated API payload. Configure each replacement module through its canonical Workflow Studio form or generated ExecModuleConfig contract.

Operations

PipelineModule supports only one compatibility operation: reject execution and identify migration targets. It does not transform, route, invoke, retry, branch, poll, deploy, or persist.

Replacement behavior belongs to the selected modules:

• MapModule performs deterministic local transformation.
• RestApiModule executes one bounded HTTPS request, retries only safe reads, and runs ambiguous writes once.
• GraphQLModule executes bounded queries, mutations, or introspection; mutations are single-attempt.
• Dedicated provider modules enforce provider-specific validation, pagination, authentication, idempotency, and destructive-action controls.

Errors and Failure Modes

Failure	Behavior	Recovery
Any legacy execution	Returns MODULE_RETIRED with retryable:false.	Replace the task; retrying cannot make the retired module operational.
Legacy workflow previously reported GOOD	Treat that status as non-evidence.	Reconcile the intended external or durable state before migration.
Credentials remain in legacy config	Values are ignored and not emitted.	Remove them and create a least-privilege IntegrationAccount for the replacement module.
Replacement write times out	Follow the replacement module's ambiguity policy.	Inspect provider state before a deliberate retry.
No dedicated provider module exists	Do not reactivate the legacy placeholder.	Use the bounded generic REST or GraphQL module, or add a native provider ExecModule.

Example

A saved legacy task reaches the compatibility shell:

{}

Expected result:

{
  "status": "error",
  "error": {
    "code": "MODULE_RETIRED",
    "message": "PipelineModule is retired; replace it with ordered workflow tasks and dedicated ExecModules",
    "retryable": false,
    "migrationTargets": ["MapModule", "RestApiModule", "GraphQLModule"]
  }
}

Notes

• Pagination: the retired module never paginates. Configure bounded pagination only in the replacement provider module.
• Limits: no payload, response, or timeout limit can make the legacy no-op safe or useful; it does not execute work.
• Idempotency: the compatibility response is deterministic and side-effect free. The old idempotent=true claim did not prove provider idempotency because no provider operation occurred.
• API constraints: PipelineModule does not parse OpenAPI, map two API schemas, or call IMAP/SMTP. Use the generated workflow model and current module contracts.
• Destructive behavior: the retired module performs none. Replacement modules may create, update, publish, or delete state; keep their confirmation and approval controls intact.
• Runtime deployment: source, tests, and documentation can be merged and published independently, but the live Workflow Studio catalog will continue to show version 1.0 until a normal backend deployment includes version 2.0.
• Unverified boundary: deterministic tests prove fail-closed output, secret non-disclosure, repeatability, metadata discovery exclusion, and direct compatibility lookup. No provider test is needed because the retired module intentionally performs no provider behavior.