DurableOrchestrationClient class

Reference

Package:: durable-functions

Client for starting, querying, terminating and raising events to orchestration instances.

Constructors

DurableOrchestrationClient(OrchestrationClientInputData)

Properties

taskHubName

The name of the task hub configured on this orchestration client instance.

Methods

createCheckStatusResponse(IHttpRequest \| HttpRequest \| undefined, string)	Creates an HTTP response that is useful for checking the status of the specified instance.
createHttpManagementPayload(string)	Creates an [[HttpManagementPayload]] object that contains instance management HTTP endpoints.
getStatus(string, boolean, boolean, boolean)	Gets the status of the specified orchestration instance.
getStatusAll()	Gets the status of all orchestration instances.
getStatusBy(Date \| undefined, Date \| undefined, OrchestrationRuntimeStatus[])	Gets the status of all orchestration instances that match the specified conditions.
purgeInstanceHistory(string)	Purge the history for a specific orchestration instance.
purgeInstanceHistoryBy(Date, Date, OrchestrationRuntimeStatus[])	Purge the orchestration history for instances that match the conditions.
raiseEvent(string, string, unknown, string, string)	Sends an event notification message to a waiting orchestration instance.
readEntityState<T>(EntityId, string, string)	Tries to read the current state of an entity. Returnes undefined if the entity does not exist, or if the JSON-serialized state of the entity is larger than 16KB.
rewind(string, string, string, string)	Rewinds the specified failed orchestration instance with a reason.
signalEntity(EntityId, string, unknown, string, string)	Signals an entity to perform an operation.
startNew(string, string, unknown)	Starts a new instance of the specified orchestrator function. If an orchestration instance with the specified ID already exists, the existing instance will be silently replaced by this new instance.
terminate(string, string)	Terminates a running orchestration instance.
waitForCompletionOrCreateCheckStatusResponse(HttpRequest, string, number, number)	Creates an HTTP response which either contains a payload of management URLs for a non-completed instance or contains the payload containing the output of the completed orchestration. If the orchestration does not complete within the specified timeout, then the HTTP response will be identical to that of [[createCheckStatusResponse]].

Constructor Details

DurableOrchestrationClient(OrchestrationClientInputData)

new DurableOrchestrationClient(clientData: OrchestrationClientInputData)

Parameters

clientData: OrchestrationClientInputData

The object representing the orchestrationClient input binding of the Azure function that will use this client.

Property Details

taskHubName

The name of the task hub configured on this orchestration client instance.

taskHubName: string

Property Value

string

Method Details

createCheckStatusResponse(IHttpRequest | HttpRequest | undefined, string)

Creates an HTTP response that is useful for checking the status of the specified instance.

function createCheckStatusResponse(request: IHttpRequest | HttpRequest | undefined, instanceId: string): IHttpResponse

Parameters

request: IHttpRequest | HttpRequest | undefined

The HTTP request that triggered the current orchestration instance.

instanceId: string

The ID of the orchestration instance to check.

Returns

IHttpResponse

An HTTP 202 response with a Location header and a payload containing instance management URLs.

createHttpManagementPayload(string)

Creates an [[HttpManagementPayload]] object that contains instance management HTTP endpoints.

function createHttpManagementPayload(instanceId: string): HttpManagementPayload

Parameters

instanceId: string

The ID of the orchestration instance to check.

Returns

HttpManagementPayload

getStatus(string, boolean, boolean, boolean)

Gets the status of the specified orchestration instance.

function getStatus(instanceId: string, showHistory?: boolean, showHistoryOutput?: boolean, showInput?: boolean): Promise<DurableOrchestrationStatus>

Parameters

instanceId: string

The ID of the orchestration instance to query.

showHistory: boolean

Boolean marker for including execution history in the response.

showHistoryOutput: boolean

Boolean marker for including input and output in the execution history response.

showInput: boolean

Returns

Promise<DurableOrchestrationStatus>

getStatusAll()

Gets the status of all orchestration instances.

function getStatusAll(): Promise<DurableOrchestrationStatus[]>

Returns

Promise<DurableOrchestrationStatus[]>

getStatusBy(Date | undefined, Date | undefined, OrchestrationRuntimeStatus[])

Gets the status of all orchestration instances that match the specified conditions.

function getStatusBy(createdTimeFrom: Date | undefined, createdTimeTo: Date | undefined, runtimeStatus: OrchestrationRuntimeStatus[]): Promise<DurableOrchestrationStatus[]>

Parameters

createdTimeFrom: Date | undefined

Return orchestration instances which were created after this Date.

createdTimeTo: Date | undefined

Return orchestration instances which were created before this DateTime.

runtimeStatus: OrchestrationRuntimeStatus[]

Return orchestration instances which match any of the runtimeStatus values in this array.

Returns

Promise<DurableOrchestrationStatus[]>

purgeInstanceHistory(string)

Purge the history for a specific orchestration instance.

function purgeInstanceHistory(instanceId: string): Promise<PurgeHistoryResult>

Parameters

instanceId: string

The ID of the orchestration instance to purge.

Returns

Promise<PurgeHistoryResult>

purgeInstanceHistoryBy(Date, Date, OrchestrationRuntimeStatus[])

Purge the orchestration history for instances that match the conditions.

function purgeInstanceHistoryBy(createdTimeFrom: Date, createdTimeTo?: Date, runtimeStatus?: OrchestrationRuntimeStatus[]): Promise<PurgeHistoryResult>

Parameters

createdTimeFrom: Date

Start creation time for querying instances for purging.

createdTimeTo: Date

End creation time for querying instances for purging.

runtimeStatus: OrchestrationRuntimeStatus[]

List of runtime statuses for querying instances for purging. Only Completed, Terminated or Failed will be processed.

Returns

Promise<PurgeHistoryResult>

raiseEvent(string, string, unknown, string, string)

Sends an event notification message to a waiting orchestration instance.

function raiseEvent(instanceId: string, eventName: string, eventData: unknown, taskHubName?: string, connectionName?: string): Promise<void>

Parameters

instanceId: string

The ID of the orchestration instance that will handle the event.

eventName: string

The name of the event.

eventData: unknown

The JSON-serializable data associated with the event.

taskHubName: string

The TaskHubName of the orchestration that will handle the event.

connectionName: string

The name of the connection string associated with taskHubName.

Returns

Promise<void>

A promise that resolves when the event notification message has been enqueued.

In order to handle the event, the target orchestration instance must be waiting for an event named eventName using [[waitForExternalEvent]].

If the specified instance is not found or not running, this operation will have no effect.

readEntityState<T>(EntityId, string, string)

Tries to read the current state of an entity. Returnes undefined if the entity does not exist, or if the JSON-serialized state of the entity is larger than 16KB.

function readEntityState<T>(entityId: EntityId, taskHubName?: string, connectionName?: string): Promise<EntityStateResponse<T>>

Parameters

entityId: EntityId

The target entity.

taskHubName: string

The TaskHubName of the target entity.

connectionName: string

The name of the connection string associated with [taskHubName].

Returns

Promise<EntityStateResponse<T>>

A response containing the current state of the entity.

rewind(string, string, string, string)

Rewinds the specified failed orchestration instance with a reason.

function rewind(instanceId: string, reason: string, taskHubName?: string, connectionName?: string): Promise<void>

Parameters

instanceId: string

The ID of the orchestration instance to rewind.

reason: string

The reason for rewinding the orchestration instance.

taskHubName: string

connectionName: string

Returns

Promise<void>

A promise that resolves when the rewind message is enqueued.

This feature is currently in preview.

signalEntity(EntityId, string, unknown, string, string)

Signals an entity to perform an operation.

function signalEntity(entityId: EntityId, operationName?: string, operationContent?: unknown, taskHubName?: string, connectionName?: string): Promise<void>

Parameters

entityId: EntityId

The target entity.

operationName: string

The name of the operation.

operationContent: unknown

The content for the operation.

taskHubName: string

The TaskHubName of the target entity.

connectionName: string

The name of the connection string associated with [taskHubName].

Returns

Promise<void>

startNew(string, string, unknown)

Starts a new instance of the specified orchestrator function. If an orchestration instance with the specified ID already exists, the existing instance will be silently replaced by this new instance.

function startNew(orchestratorFunctionName: string, instanceId?: string, input?: unknown): Promise<string>

Parameters

orchestratorFunctionName: string

The name of the orchestrator function to start.

instanceId: string

The ID to use for the new orchestration instance. If no instanceId is specified, the Durable Functions extension will generate a random GUID (recommended).

input: unknown

JSON-serializable input value for the orchestrator function.

Returns

Promise<string>

The ID of the new orchestration instance.

terminate(string, string)

Terminates a running orchestration instance.

function terminate(instanceId: string, reason: string): Promise<void>

Parameters

instanceId: string

The ID of the orchestration instance to terminate.

reason: string

The reason for terminating the orchestration instance.

Returns

Promise<void>

A promise that resolves when the terminate message is enqueued.

Terminating an orchestration instance has no effect on any in-flight activity function executions or sub-orchestrations that were started by the current orchestration instance.

waitForCompletionOrCreateCheckStatusResponse(HttpRequest, string, number, number)

Creates an HTTP response which either contains a payload of management URLs for a non-completed instance or contains the payload containing the output of the completed orchestration. If the orchestration does not complete within the specified timeout, then the HTTP response will be identical to that of [[createCheckStatusResponse]].

function waitForCompletionOrCreateCheckStatusResponse(request: HttpRequest, instanceId: string, timeoutInMilliseconds?: number, retryIntervalInMilliseconds?: number): Promise<IHttpResponse>

Parameters

request: HttpRequest

The HTTP request that triggered the current function.

instanceId: string

The unique ID of the instance to check.

timeoutInMilliseconds: number

Total allowed timeout for output from the durable function. The default value is 10 seconds.

retryIntervalInMilliseconds: number

The timeout between checks for output from the durable function. The default value is 1 second.

Returns

Promise<IHttpResponse>