---
url: https://node-ts.github.io/bus/api/bus-core/classes/WorkflowMapper.md
---
[API reference](../../index.md) / [@node-ts/bus-core](../index.md) / WorkflowMapper

# Class: WorkflowMapper\<WorkflowStateType, WorkflowType>

Defined in: [packages/bus-core/src/workflow/workflow.ts:156](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/workflow/workflow.ts#L156)

A workflow configuration that describes how to map incoming messages to handlers within the workflow.

## Type Parameters

| Type Parameter |
| ------ |
| `WorkflowStateType` *extends* [`WorkflowState`](WorkflowState.md) |
| `WorkflowType` *extends* [`Workflow`](Workflow.md)<`WorkflowStateType`> |

## Constructors

### Constructor

```ts
new WorkflowMapper<WorkflowStateType, WorkflowType>(workflow): WorkflowMapper<WorkflowStateType, WorkflowType>;
```

Defined in: [packages/bus-core/src/workflow/workflow.ts:170](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/workflow/workflow.ts#L170)

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `workflow` | [`ClassConstructor`](../type-aliases/ClassConstructor.md)<[`Workflow`](Workflow.md)<[`WorkflowState`](WorkflowState.md)>> |

#### Returns

`WorkflowMapper`<`WorkflowStateType`, `WorkflowType`>

## Properties

| Property | Modifier | Type | Defined in |
| ------ | ------ | ------ | ------ |
| <a id="property-onstartedby"></a> `onStartedBy` | `readonly` | `Map`<[`MessageDeclaration`](../../bus-messages/type-aliases/MessageDeclaration.md)<[`Message`](../../bus-messages/classes/Message.md)>, { `workflowCtor`: [`ClassConstructor`](../type-aliases/ClassConstructor.md)<[`Workflow`](Workflow.md)<[`WorkflowState`](WorkflowState.md)>>; `workflowHandler`: `string`; }> | [packages/bus-core/src/workflow/workflow.ts:160](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/workflow/workflow.ts#L160) |
| <a id="property-onwhen"></a> `onWhen` | `readonly` | `Map`<[`MessageDeclaration`](../../bus-messages/type-aliases/MessageDeclaration.md)<[`Message`](../../bus-messages/classes/Message.md)>, [`OnWhenHandler`](../type-aliases/OnWhenHandler.md)> | [packages/bus-core/src/workflow/workflow.ts:167](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/workflow/workflow.ts#L167) |

## Accessors

### workflowStateCtor

#### Get Signature

```ts
get workflowStateCtor(): 
  | ClassConstructor<WorkflowStateType>
  | undefined;
```

Defined in: [packages/bus-core/src/workflow/workflow.ts:174](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/workflow/workflow.ts#L174)

##### Returns

| [`ClassConstructor`](../type-aliases/ClassConstructor.md)<`WorkflowStateType`>
| `undefined`

## Methods

### startedBy()

```ts
startedBy<MessageType, THandlerName>(message, workflowHandler): this;
```

Defined in: [packages/bus-core/src/workflow/workflow.ts:198](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/workflow/workflow.ts#L198)

Starts a new instance of the workflow each time `message` is handled.

Messages are delivered at least once and starts aren't deduplicated, so a `message` that's retried after the
new workflow state was saved (for example because another handler of the same message failed) starts a second
workflow instance. Make the handler idempotent, such as by returning `discardWorkflow()` when a workflow already
exists for the message, if that matters.

#### Type Parameters

| Type Parameter |
| ------ |
| `MessageType` *extends* [`Message`](../../bus-messages/classes/Message.md) |
| `THandlerName` *extends* `string` |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `message` | [`MessageDeclaration`](../../bus-messages/type-aliases/MessageDeclaration.md)<`MessageType`> | The message that starts the workflow: a message class, or a definition from `defineCommand` or `defineEvent` |
| `workflowHandler` | `WorkflowHandlerArgument`<`WorkflowType`, `THandlerName`, `MessageType`, `WorkflowStateType`> | The name of the workflow method that handles `message`. It must take `message` and return changes to the workflow state, or nothing, with no fields that aren't in the state. |

#### Returns

`this`

#### Throws

WorkflowAlreadyStartedByMessage if the workflow is already started by `message`

#### Example

```ts
mapper.withState(OrderState).startedBy(OrderPlaced, 'start')
```

***

### when()

```ts
when<MessageType, THandlerName>(
   message, 
   workflowHandler, 
   customLookup?
): this;
```

Defined in: [packages/bus-core/src/workflow/workflow.ts:231](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/workflow/workflow.ts#L231)

Dispatches `message` to the workflow instances it maps to

#### Type Parameters

| Type Parameter |
| ------ |
| `MessageType` *extends* [`Message`](../../bus-messages/classes/Message.md) |
| `THandlerName` *extends* `string` |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `message` | [`MessageDeclaration`](../../bus-messages/type-aliases/MessageDeclaration.md)<`MessageType`> | The message to handle: a message class, or a definition from `defineCommand` or `defineEvent` |
| `workflowHandler` | `WorkflowHandlerArgument`<`WorkflowType`, `THandlerName`, `MessageType`, `WorkflowStateType`> | The name of the workflow method that handles `message`. It must take `message` and return changes to the workflow state, or nothing, with no fields that aren't in the state. |
| `customLookup?` | [`MessageWorkflowMapping`](../interfaces/MessageWorkflowMapping.md)<`MessageType`, `WorkflowStateType`> | How to find the workflow instance for `message`. By default it's found by the `workflowId` sticky attribute that's added to messages sent from the workflow. |

#### Returns

`this`

#### Throws

WorkflowAlreadyHandlesMessage if the workflow already handles `message`

#### Example

```ts
mapper.when(CardCharged, 'charged', { lookup: message => message.orderId, mapsTo: 'orderId' })
```

***

### withState()

```ts
withState(workflowStateType): this;
```

Defined in: [packages/bus-core/src/workflow/workflow.ts:178](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/workflow/workflow.ts#L178)

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `workflowStateType` | [`ClassConstructor`](../type-aliases/ClassConstructor.md)<`WorkflowStateType`> |

#### Returns

`this`