Workflow management cmdlets

Workflow management cmdlets allow you to manage the workflow associated with 1E Platform instructions that have been defined as actions rather than questions.

Workflow management cmdlets

When you instantiate an action via invoke-instruction, or via a generated cmdlet, or the dynamic search cmdlet, the action will normally be queued in a workflow state indicating that the action is awaiting authentication.

There is a configurable timeout in the coordinator configuration file, which, by default, is set to 10 minutes as shown here.

Copy 
<add key="OTPExpirySeconds" value="600" />

An instruction that times out from the awaiting authentication state will transition to rejected. If you invoke an action and then it is not approved in this timeframe, the invoke-1Einstruction cmdlet will throw an exception when the instruction transitions to rejected.

Some other platform operations may also require workflow approval. For example, scheduling an instruction requires approval whether or not the scheduled instruction itself is a question or action.

You explicitly approve or deny an instruction via workflow by using the cmdlets below. Remember that you cannot self-approve your own actions, therefore you will need at least two accounts, one that is Actioner or Full Administrator, and another that is Approver or Full Administrator. Approval can be done using the platform UI or the PowerShell cmdlets to perform the approval or rejection process.

Workflow tokens

The normal workflow process in the 1E Platform is as follows:

  1. The action invoker requests that a specific action be invoked. If using PowerShell, this would be via any of the cmdlets that ultimately invokes instructions via the invoke-1Einstruction cmdlet.
  2. The platform emails the action invoker with a one-time token. The token is valid for ten minutes.
  3. Within the ten-minute timeframe, the action invoker binds the token to the instruction Id using the Set-1EInstructionAuthToken cmdlet below. This verifies the authenticity of the invoker.
  4. The action is now placed in a pending approval state. The action approver then uses the Approve-1EInstruction or Deny-1EInstruction cmdlets below to accept or reject the action. There is no timeframe within which they need to do this.
  5. If the action was approved, it will now execute. The invoke-1Einstruction cmdlet automatically loops, waiting for the instruction to be approved.
  6. If the action was rejected, it transitions to the rejected state. The invoke-1Einstruction cmdlet will throw an error at this point, indicating that the instruction was rejected.

In a test lab scenario, if the action invoker and the action approver are the same person, they can use the Approve-1EInstruction or Deny-1EInstruction cmdlets to approve or reject an action in a single operation. They do this by also supplying the optional authentication token to these cmdlets.

Normally, an invoked action will cause the invoke-1Einstruction cmdlet to wait until the instruction is either approved, and then the results become available, or until the instruction is rejected or enters an error state, at which point the cmdlet raises an error.

In some cases, the action invoker might want the invoke instruction cmdlet to return when the instruction is initially submitted. They can do this by specifying the -NoWait parameter when invoking the instruction. In this scenario, the invoke-1Einstruction cmdlet returns immediately. The instruction invoker can subsequently use the get-1Einstructionresult cmdlet to retrieve the instruction results at a future point when the instruction was approved and has executed. Note that results will only be available for the duration of the results time-to-live (TTL) value associated with the instruction when it was initially submitted.

Approve-1EInstruction -Id <id> | -ScheduleId <scheduleId> [-Token <token>] [-Comment <comment>]

This cmdlet approves the instruction or scheduled task creation request given by the specified Id, using the authentication token provided. 

If the token is not provided, it is assumed that the token was already set using the Set-1EInstructionAuthToken cmdlet. This is most probably because the approver is not the same person as the instruction invoker.

You cannot re-use an authentication token. Providing the token again in this cmdlet when it has already been supplied via Set-1EInstructionAuthToken will raise an error. Providing the token when it was issued to another user will also raise an error.

The optional comment will be used as the reason for approving the instruction. If not supplied, a default comment This instruction was approved by the PowerShell Integration Toolkit is used.

Deny-1EInstruction -Id <id> | -ScheduleId <scheduleId> [-Token <token>] [-Comment <comment>]

This cmdlet rejects the instruction or scheduled task creation request given by the specified Id, using the authentication token provided. 

If the token is not provided, it is assumed that the token was already set using the Set-1EInstructionAuthToken cmdlet. This is most probably because the approver is not the same person as the instruction invoker.

You cannot re-use an authentication token. Providing the token again in this cmdlet when it has already been supplied via Set-1EInstructionAuthToken will raise an error. Providing the token when it was issued to another user will also raise an error.

The optional comment will be used as the reason for rejecting the instruction. If not supplied, a default comment This instruction was rejected by the PowerShell Integration Toolkit is used.

For both of the above cmdlets, if the token is omitted but the instruction invoker did not already bind it to the instruction Id, then an error is thrown. However, the error returned from the platform states that the approval request has already been actioned by the user '.'. This appears to be an issue currently in the platform response.

Set-1EInstructionAuthToken -Id <id>|-ScheduleId <ScheduleId> -Token <token>

This cmdlet sets the authentication token for the instruction or scheduled task creation operation. This cmdlet is useful in scenarios where the approver is not the same individual as the instruction invoker. In that situation, the instruction invoker will receive the authentication token and will then use this cmdlet to bind it to the instruction they invoked.

The instruction approver will then use the Approve-1EInstruction or Deny-1EInstruction cmdlet without the token, to approve or reject the instruction accordingly.

The instruction invoker must bind the token to the instruction within ten minutes of invoking the instruction, otherwise, it will automatically transition to rejected. 

The token is only valid for the account associated with the instruction invoker. If it is supplied in the context of a different account, an error will be raised.

Instruction invocation and the -NoWait parameter

An action invoked from a PowerShell session will block that session until the action is approved. The instruction invoker must therefore use a second PowerShell session to bind the authentication token and optionally self-approve (where applicable) their action.

The instruction invoker may prefer that the action be queued and control returned immediately to their primary PowerShell session. In that scenario, the -NoWait parameter to the invoke-1Einstruction cmdlet allows the instruction invoker to queue the instruction and immediately regain control within a single PowerShell session.

They must still retrieve the authentication token and bind it to the instruction and/or self-approve before the action executes, but they can do so from within a single PowerShell session if preferred.

Instruction results can then be subsequently retrieved using the get-1Einstructionresults cmdlet.

A workflow scenario in more detail

For a detailed workflow scenario using the above cmdlets, refer to Device tags.