Sequencer Service

This service provides a handle to send commands to a Sequencer which is registered in Location Service.

Creation of Sequencer Service

Pre-requisite

In order to use sequencer service client for a specific sequencer

  1. The Sequencer and Gateway Server should be running. GatewayException(InvalidComponent) will be thrown if the specified sequencer not found in the Location Service.
  2. Authorization token with correct access role. Documentation on how to fetch access token could be found here.

To create Sequencer Service

Typescript
sourceconst tokenFactory = () => auth.token

const sequencerService: SequencerService = await SequencerService(
  new ComponentId(new Prefix('ESW', 'darknight'), 'Sequencer'),
  { tokenFactory }
)

Creating SequenceCommands

Typescript
sourceconst eswTestPrefix = Prefix.fromString('TCS.darknight')

const setupCommand1 = new Setup(eswTestPrefix, 'setup-command1')
const setupCommand2 = new Setup(eswTestPrefix, 'setup-command2')

const observeCommand1 = new Observe(eswTestPrefix, 'observe-command1')
const observeCommand2 = new Observe(eswTestPrefix, 'observe-command2')

Creating a Sequence

A sequence is a list of sequence commands:

Typescript
source//sequence is a list of SequenceCommand
const sequence = new Sequence([setupCommand1, observeCommand1])

Usages of Sequencer Service

Async-Await

Note that the examples are using async/await which makes handling of promises more readable.

Type Definitions for Sequencer Service can be found here

Loading and Starting a Sequence into a Sequencer

To load a sequence into a Sequencer, SequencerService provides loadSequence method which takes a Sequence and returns a Promise<OkOrUnhandledResponse>. If Sequencer is in Idle state, provided sequence gets loaded into the Sequencer and an Ok response gets returned. Otherwise, an Unhandled response gets returned.

To start a loaded sequence, SequencerService provides startSequence method which starts the sequence (which is loaded by loadSequence method) in the Sequencer and returns a Promise<SubmitResponse>. If Sequencer is in Loaded state, loaded sequence’s execution gets started in the Sequencer and a Started response gets returned. Otherwise, a negative SubmitResponse gets returned.

Type definitions for methods used in the given example are :

  1. loadSequence
  2. startSequence
  3. query
  4. queryFinal
Typescript
sourceconst okOrUnhandledResponse: OkOrUnhandledResponse = await sequencerService.loadSequence(sequence)
const initialResponse: SubmitResponse = await sequencerService.startSequence()

const queryResponse: SubmitResponse = await sequencerService.query(initialResponse.runId)
const queryFinalResponse: SubmitResponse = await sequencerService.queryFinal(initialResponse.runId, 5)

Adding commands into the sequence after all the pending steps

To add commands into the sequence after all the pending steps, SequencerService provides add method which takes list of SequenceCommands and returns Promise<OkOrUnhandledResponses>. If Sequencer is still in execution, then given list of SequenceCommands gets added into the sequence after all the pending steps and a Ok response gets returned. Otherwise, an Unhandled response gets returned.

Type definitions for add method used can be found here

Typescript
sourceconst addResponse: OkOrUnhandledResponse = await sequencerService.add([observeCommand2, setupCommand2])

Prepending commands into the sequence before all the pending steps

To add commands into the sequence before all the pending steps, SequencerService provides add method which takes list of SequenceCommands and returns Promise<OkOrUnhandledResponses>. If Sequencer is still in execution, then given list of SequenceCommands gets added into the sequence before all the pending steps and a Ok response gets returned. Otherwise, an Unhandled response gets returned.

Type definitions for prepend method used can be found here

Typescript
sourceconst prependResponse: OkOrUnhandledResponse = await sequencerService.prepend([observeCommand2, setupCommand2])

Replacing a command with a list of commands

To replace a command with a list of commands, SequencerService provides replace method which takes the Id of the command which to be replaced and list of SequenceCommands and returns Promise<GenericResponse>. In case, if the command of the given Id is not present in sequence, then IdDoesNotExist response gets returned. Or if the command is already finished or in flight, then a CannotOperateOnAnInFlightOrFinishedStep response gets returned. In case, if the command is still pending, then it gets replaced with the given list of SequenceCommands. Otherwise, an Unhandled response gets returned.

Type definitions for replace method used can be found here

Typescript
sourceconst replaceResponse: GenericResponse = await sequencerService.replace('d99b6cf6-553c-49e9-9089-aaa494f116e9', [
  observeCommand2,
  setupCommand2
])

Inserting a list of commands after a command

To insert a list of commands after a command, SequencerService provides insertAfter method which takes the Id of the command after which commands to be inserted and list of SequenceCommands and returns Promise<GenericResponse>. In case, if the command of the given Id is not present in sequence, then IdDoesNotExist response gets returned. Or if the command is already finished or in flight, then a CannotOperateOnAnInFlightOrFinishedStep response gets returned. In case, if the command is still pending, then the given list of SequenceCommands gets inserted after it. Otherwise, an Unhandled response gets returned.

Type definitions for insertAfter method used can be found here

Typescript
sourceconst insertAfterResponse: GenericResponse = await sequencerService.insertAfter(
  'd99b6cf6-553c-49e9-9089-aaa494f116e9',
  [observeCommand2, setupCommand2]
)

Deleting a command from the sequence

To delete a command from the sequence, SequencerService provides delete method which takes the Id of the command to be deleted and returns Promise<GenericResponse>. If sequencer is not in Running state, then Unhandled response gets returned. Or if the command of the given Id, is not present in sequence, then IdDoesNotExist response gets returned. Or if the command is still pending, then it gets deleted and Ok response gets returned. Otherwise, a CannotOperateOnAnInFlightOrFinishedStep response gets returned.

Type definitions for delete method used can be found here

Typescript
sourceconst deleteResponse: GenericResponse = await sequencerService.delete('d99b6cf6-553c-49e9-9089-aaa494f116e9')

Adding a breakpoint to a Step

To add a breakpoint to a Step, SequencerService provides addBreakpoint method which takes the Id of the command where breakpoint to be added and returns Promise<GenericResponse>. If sequencer is not in Running state, then Unhandled response gets returned. Or if the command of the given Id, is not present in sequence, then IdDoesNotExist response gets returned. Or if the command is still pending, then breakpoint gets added and Ok response gets returned. Otherwise, a CannotOperateOnAnInFlightOrFinishedStep response gets returned.

Type definitions for addBreakpoint method used can be found here

Typescript
sourceconst addBreakpointResponse: GenericResponse = await sequencerService.addBreakpoint(
  'd99b6cf6-553c-49e9-9089-aaa494f116e9'
)

Removing a breakpoint from a Step

To remove a breakpoint from a Step, SequencerService provides removeBreakpoint method which takes the Id of the command from where breakpoint to be removed and returns Promise<RemoveBreakpointResponse>. If sequencer is not in Running state, then Unhandled response gets returned. Or if the command of the given Id, is not present in sequence, then IdDoesNotExist response gets returned. Otherwise, breakpoint gets removed and Ok response gets returned.

Type definitions for removeBreakpoint method used can be found here

Typescript
sourceconst removeBreakpointResponse: RemoveBreakpointResponse = await sequencerService.removeBreakpoint(
  'd99b6cf6-553c-49e9-9089-aaa494f116e9'
)

Pausing the sequence

To pause the sequence, SequencerService provides pause method which returns Promise<PauseResponse>. If sequencer is in Running state, then an Ok response gets returned if there is a Step pending. Otherwise, a CannotOperateOnAnInFlightOrFinishedStep response gets returned. Or if sequencer is not in Running state, then Unhandled response gets returned.

Type definitions for pause method used can be found here

Typescript
sourceconst pauseResponse: PauseResponse = await sequencerService.pause()

Resuming a paused sequence

To resume a paused sequence, SequencerService provides resume method which returns Promise<PauseResponse>. If sequencer is in Running state, an Ok response gets returned. Otherwise, an Unhandled response gets returned.

Type definitions for resume method used can be found here

Typescript
sourceconst resumeResponse: OkOrUnhandledResponse = await sequencerService.resume()

Getting the sequence from the Sequencer

To get the sequence from the Sequencer, SequencerService provides getSequence method which returns the StepList (runtime representation of the sequence). if there is no sequence executing in the Sequencer, an undefined response gets returned.

Type definitions for getSequence method used can be found here

Typescript
sourceconst getSequenceRes: Option<StepList> = await sequencerService.getSequence()

Checking if Sequencer is available

To check if Sequencer is available, SequencerService provides isAvailable method which returns Promise<boolean>. If Sequencer is in Idle state, then a true gets returned. Otherwise, false response gets returned.

Type definitions for isAvailable method used can be found here

Typescript
sourceconst isAvailable: boolean = await sequencerService.isAvailable()

Checking if Sequencer is online

To check if Sequencer is online, SequencerService provides isOnline method which returns Promise<boolean>. If Sequencer is in Idle state, then a true gets returned. Otherwise, false gets returned.

Type definitions for isOnline method used can be found here

Typescript
sourceconst isOnline: boolean = await sequencerService.isOnline()

Discarding all the pending Steps

To discard all the pending Steps, SequencerService provides a reset method which returns Promise<OkOrUnhandledResponse>. If Sequencer is in Running state, then an Ok response gets returned. Otherwise, an Unhandled response gets returned.

Type definitions for reset method used can be found here

Typescript
sourceconst resetResponse: OkOrUnhandledResponse = await sequencerService.reset()

Discarding all the pending Steps and calling the onAbortSequence handler of the script

To discard all the pending Steps and call the onAbortSequence handler of the script, SequencerService provides a abortSequence method which returns Promise<OkOrUnhandledResponse>. If Sequencer is in Running state, then an Ok response gets returned. Otherwise, an Unhandled response gets returned.

Type definitions for abortSequence method used can be found here

Typescript
sourceconst abortResponse: OkOrUnhandledResponse = await sequencerService.abortSequence()

Discarding all the pending Steps and calling the onStop handler of the script

To discard all the pending Steps and call the onStop handler of the script, SequencerService provides a stop method which returns Promise<OkOrUnhandledResponse>. If Sequencer is in Running state, then an Ok response gets returned. Otherwise, an Unhandled response gets returned.

Type definitions for stop method used can be found here

Typescript
sourceconst stopResponse: OkOrUnhandledResponse = await sequencerService.stop()

Changing Sequencer state to Online

To change Sequencer state to Online, SequencerService provides goOnline method which returns Promise<GoOnlineResponse>. If Sequencer is in any state but Running, then an Ok response gets returned (if goOnline handler gets executed successfully). Otherwise, a GoOnlineHookFailed response gets returned. Although, if Sequencer is in Running state, then an Unhandled response gets returned.

Type definitions for goOnline method used can be found here

Typescript
sourceconst goOnlineResponse: GoOnlineResponse = await sequencerService.goOnline()

Changing Sequencer state to Offline

To change Sequencer state to Offline, SequencerService provides goOffline method which returns Promise<GoOfflineResponse>. If Sequencer is in any State but Running, then an Ok response gets returned (if goOffline handler gets executed successfully). Otherwise, a GoOfflineHookFailed response gets returned. Although, if Sequencer is in Running state, then an Unhandled response gets returned.

Type definitions for goOffline method used can be found here

Typescript
sourceconst goOfflineResponse: GoOfflineResponse = await sequencerService.goOffline()

Running diagnosticMode

To run diagnosticMode handler, SequencerService provides diagnosticMode method which returns Promise<DiagnosticModeResponse>. If diagnosticMode handler of the script successfully executes, then an Ok response gets returned. Otherwise, a DiagnosticHookFailed gets returned.

Type definitions for diagnosticMode method used can be found here

Typescript
sourceconst diagnosticResponse: DiagnosticModeResponse = await sequencerService.diagnosticMode(new Date(), 'engineering')

Running operationsMode

To run operationsMode handler, SequencerService provides operationsMode method which returns Promise<OperationsModeResponse>. If operationsMode handler of the script successfully executes, then an Ok response gets returned. Otherwise, a OperationsHookFailed gets returned.

Type definitions for operationsMode method used can be found here

Typescript
sourceconst operationsModeResponse: OperationsModeResponse = await sequencerService.operationsMode()

Submitting Sequence to a Sequencer

To submit a Sequence to a Sequencer, SequencerCommandService provides a submit method which takes a Sequence and returns a Promise<SubmitResponse>.

If the Sequencer is idle, then provided sequence gets loaded in the Sequencer, execution of the sequence starts immediately and a Started response gets returned. If the sequencer is already running another sequence, then an Invalid response gets returned.

Typescript
sourceconst initialRes: SubmitResponse = await sequencerService.submit(sequence)

const queryRes: SubmitResponse = await sequencerService.query(initialRes.runId)

const queryFinalRes: SubmitResponse = await sequencerService.queryFinal('d99b6cf6-553c-49e9-9089-aaa494f116e9', 10)

The query or queryFinal methods, as shown above, could be used to query for the sequence result after the sequence is submitted. The query method returns a current response which could be either final response (eg. Completed) or intermediate response (eg. Started). Whereas queryFinal will wait for the final response of the sequence for the given timeout. This method will never return an intermediate response.

If you are not interested in initial/intermediate response but only in final response, you can use the submitAndWait method which submits the sequence and waits for the final response (if the sequence was successfully Started).

Typescript
sourceconst submitAndWaitResponse: SubmitResponse = await sequencerService.submitAndWait(sequence, 10)

Type definitions for APIs used in the given example are :

  1. submit
  2. submitAndWait
  3. query
  4. queryFinal

Getting Status of Sequencer

To get Sequencer’s State, SequenceService provides getSequencerState method. This method returns Promise<SequencerState> the state of sequencer can be Idle, Processing, Loaded, Offline, Running

Type definitions for getSequencerState method used can be found here

Typescript
sourceconst getSequencerState: SequencerState = await sequencerService.getSequencerState()

Subscribing to Sequencer State

To subscribe to state of Sequencer, subscribeSequencerState method can be used. This method invokes the given callback on every state change with newly received SequencerStateResponse. SequencerStateResponse contains the current SequencerState and StepList. This method returns a Subscription which can be used to unsubscribe, as shown in example.

Type definitions for subscribeSequencerState method used can be found here

Typescript
sourceconst callBack = (sequencerStateResponse: SequencerStateResponse) => {
  console.log(sequencerStateResponse)
}
//optional
const onErrorCallback = (error: ServiceError) => {
  // do something when error occurs
  // for ex : close connection / cleanup resources
  console.log(error)
}
//optional
const onCloseCallback = () => {
  // do something when connection is closed
  // for ex : reset client-side state
}
const subscription: Subscription = sequencerService.subscribeSequencerState()(
  callBack,
  onErrorCallback,
  onCloseCallback
)
//...
subscription.cancel() // to unsubscribe
0.4.1