Skip to main content

0038: Onboarding Pipeline to Workflow Mapping

Date: 2025-11-08

Status: Proposed

Context​

As established in ADR-0037, the onboarding-service is a stateless adapter. Its API exposes the concept of a "pipeline" (e.g., StandardKYC, EmployeeInvite) to its clients. However, the underlying workflow-service operates on more generic workflowName identifiers (e.g., tenant-onboarding-v1).

We need a mechanism to translate the abstract pipeline name into a concrete, versioned workflow definition that the workflow-service can execute. Hardcoding this logic would make the system rigid and require a full service redeployment to add or change an onboarding process.

Decision​

We will implement a configuration-based mapping strategy within the onboarding-service.

  1. Configuration: A configuration source (e.g., a YAML file, environment variables, or a central config service) will hold a map of pipelineName to workflowName.

    Example (YAML):

    onboardingPipelines:
      StandardKYC: tenant-onboarding-v1
      EmployeeInvite: user-onboarding-v1

  2. Runtime Lookup: When the onboarding-service receives a request (e.g., POST /onboarding/start with pipelineName: "StandardKYC"), it will perform a lookup in its loaded configuration to find the corresponding workflowName (tenant-onboarding-v1).

  3. Dispatch: It will then use this resolved workflowName to start the correct process in the workflow-service.

Consequences​

Positive​

  • Flexibility: New onboarding processes or versions can be introduced by simply updating the configuration, without any code changes or service redeployment.
  • Decoupling: The public API contract (pipelineName) is cleanly decoupled from the implementation detail (workflowName), which can evolve independently.
  • Versioning: This pattern provides a simple way to version onboarding flows. We can introduce tenant-onboarding-v2 and update the configuration to point the StandardKYC pipeline to the new workflow.

Negative​

  • Configuration Management: The pipeline mapping becomes a critical configuration artifact that must be managed, versioned, and deployed carefully.
  • Runtime Errors: A request with an unknown pipelineName will result in a runtime error (e.g., a 404 Not Found or 400 Bad Request), which the service must handle gracefully.