1E PowerShell Toolkit management cmdlet reference
List of PowerShell Toolkit cmdlets used for 1E management.
These cmdlets allow you to perform a variety of tasks in the platform. Some of them are discussed in the parent page, in relation to dynamic scripting and cmdlet creation. However, there are other cmdlets which support interaction with the platform. These are discussed on this page.
Workflow management cmdlets
Workflow management cmdlets allow you to manage the workflow associated with Tachyon instructions which have been defined as actions, rather than questions.
Workflow tokens
The normal workflow process in Tachyon is as follows:-
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-instruction cmdlet.
Tachyon emails the action invoker with a one-time token. The token is valid for ten minutes.
Within the ten minute timeframe, the action invoker binds the token to the instruction Id using the Set-TachyonInstructionAuthToken cmdlet below. This verifies the authenticity of the invoker.
The action is now placed in a 'pending approval' state. The action approver then uses the Approve-Instruction or Deny-Instruction cmdlets below to accept or reject the action. There is no timeframe within which they need to do this.
If the action was approved, it will now execute. The invoke-tachyoninstruction cmdlet automatically loops, waiting for the instruction to be approved.
If the action was rejected, it transitions to the rejected state. The invoke-instruction cmdlet will throw an error at this point, indicating that the instruction was rejected.
If the action invoker and the action approver are the same person, they can use the Approve-TachyonInstruction or Deny-TachyonInstruction cmdlets to approve or reject an action in a single operation. They do this by also supplying the optional authentication token to these cmdlets.
Note
Normally an invoked action will cause the invoke-instruction 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-instruction cmdlet returns immediately. The instruction invoker can subsequently use the get-tachyoninstructionresult 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-TachyonInstruction -Id <id> | -ScheduleId <scheduleId> [-Token <token>] [-Comment <comment>]
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-TachyonInstructionAuthToken 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-TachyonInstructionAuthToken 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 Tachyon PowerShell Integration' is used.
Deny-TachyonInstruction -Id <id> | -ScheduleId <scheduleId> [-Token <token>] [-Comment <comment>]
Rejects the instruction or scheduled task creation reques 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-TachyonInstructionAuthToken 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-TachyonInstructionAuthToken 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 Tachyon PowerShell Integration' is used.
Note
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 Tachyon is somewhat misleading as it states that the approval request has already been actioned by the user '.' This appears to be a defect currently in the Tachyon response.
Set-TachyonInstructionAuthToken -Id <id>|-ScheduleId <ScheduleId> -Token <token>
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-TachyonInstruction or Deny-TachyonInstruction cmdlet without the token, to approve or reject the instruction accordingly.
Note
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-instruction 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-Tachyoninstructionresults cmdlet.
A workflow scenario in more detail
Using device tags with the Tachyon PowerShell Toolkit has a detailed workflow scenario using the above cmdlets.