Skip to main content

1E 23.11 (SaaS)

Tachyon Server management cmdlets

The server management cmdlets allow you to:

  • Specify the Tachyon server to connect to, and verify its version

  • Manage device tags

  • Retrieve workflow notifications

  • Manage event subscriptions and assignments.

Event management is discussed on the child page here Tachyon event management cmdlets.

Set-TachyonServer <servername>

[-ApiKey <api key>] [-AppId <appId>] [-CertSubject <CertSubject>] [-CertThumbprint <CertThumbprint>] [-Principal <principal>] [-UseBasicAuth] [-BypassAuth] [-AsPlatform] [-KeyVaultUrl <KeyVaultUrl>] [-ManagedIdentity <ManagedIdentity>] [-CertName <CertName>]

Parameter

Description

servername

Specifies the Tachyon server to be used for all operations. A connectivity test is made when this cmdlet is executed. An error is thrown if the server does not respond appropriately.

If the server is determined to be a Tachyon Consumer Authentication Proxy server, then unless client certificate authentication or inbound NTLM authentication is configured on the proxy, the optional ApiKey parameter should specify a valid API access token. 

If using Windows authentication, the connection is made by default in the context of the current account in which the cmdlet is being run. You can override this by specifying a PSCredential object with alternate credentials. The connection will then be made in the context of those credentials, and all subsequent commands will also run in that context.

This can be very useful when connecting to external servers, for example SaaS-based environments, where the credentials are required to be valid in that environment.

To prompt securely for credentials when invoking this cmdlet, you can use the get-credential PowerShell cmdlet. For example -Credential (get-credentials).

Alternatively, you can store the credentials in a PowerShell variable and pass this as the value of the -Credential parameter, for example -Credential $myCreds.

-UseBasicAuth

Specifies that the connection will be made using basic authentication. In this case, you must supply credentials via the -Credential parameter.

-AppId

Specifies that connectivity is to be made by platform-neutral authentication, that is, through an external identity provider. The application Id should correspond to a registered application which has been set up on the identity provider to handle external authentication.

If the AppId parameter is specified, you must also specify a certificate subject (e.g, CN=MyCert) which is to be used to sign the token which is used to authenticate the PowerShell toolkit to the Tachyon Platform.

-CertSubject

Specifies the subject of the certificate to be used when authenticating using platform-neutral authentication.

-CertThumbprint

Specifies the thumbprint of the certificate to be used when authenticating using platform-neutral authentication. If both a CertSubject and CertThumbprint parameter are specified, the CertThumbprint value is used in preference.

The certificate must be in the local machine certificate store, and the account under which you are running the tool must have access to the private key. You can use the 'manage private key' option in the certlm.msc tool to add permissions if necessary.

-Principal

If specified, defines the user principal associated with the authentication token. This parameter is only valid if the certificate to principal mappings have been set up to allow principals to be overridden. Otherwise, the user principal associated with the authentication token will be automatically defined by the mapping table entries.

-BypassAuth

If specified, it simply causes the internal tachyon server variable to be set and then the cmdlet exits. After this, you can call any endpoint on the Tachyon platform that is not authenticated. This is useful for troubleshooting, because you can then use cmdlets such as Get-TachyonBearerToken to check identity provider configuration etc.

-AsPlatform

If specified, requests an internal platform token. You must specify a certificate subject or thumbprint, but you do not need to supply a principal or application Id, because platform tokens are not mediated via the external identity provider.

A platform token operates with extended privileges. The certificate you specify must have its private key accessible under the account context from which you are running the PowerShell toolkit. This option is useful if you want to interact with the Tachyon platform during commissioning, as it does not rely on the external identity provider.

-KeyVaultUrl

If specified, defines the Url of the Azure Key Vault from which the certificate is to be retrieved. The Url should not contain the https:// prefix, this is added automatically. You must specify -ManagedIdentity and -CertName when using this parameter.

-ManagedIdentity

If specified, defines the managed identity that the key vault access should be made under. Normally, the virtual machine on which the PS toolkit is running in the Azure environment will be assigned this managed identity and the managed identity needs to have the appropriate permissions to read the Azure Key Vault.

-CertName

If specified, defines the name of the certificate to be retrieved from the key vault. Note that certificate names and subjects are entirely independent of each other in the vault.

Caution

Azure Key Vault access capabilities are only available when the PowerShell toolkit is run under .NET Framework 6+ and not under legacy PowerShell. You need to provide additional DLLs in order for this capability to function. Please refer to Accessing Certificates from the Azure Key Vault.

Azure Key Vault access is also available on non-Windows (Linux) platforms. For more information on running the PS toolkit on non-Windows platforms, please refer to Using the Tachyon PowerShell Toolkit on non-Windows platforms.

Caution

The Tachyon Consumer Authentication Proxy server is a custom feature that can be provided on request, from the Tachyon Product Manager. Please ask your 1E Account Manager.

Set-TachyonProxyCredentials -ApiKey <api key> [-Credentials <credentials>]

Allows a set of credentials to be sent and stored on the Tachyon Consumer Authentication Proxy server. The proxy server will use these credentials when mapping incoming requests to outgoing Tachyon requests.

If you do not pass a PSCredential object on the command line, you are securely prompted for credentials instead.

Note

The value of the API key for this cmdlet is configured on the proxy server separately from the API key used in the Set-TachyonServer cmdlet. You must obtain a value for both keys from the proxy administrator

Caution

Azure Key Vault access capabilities are only available when the PowerShell toolkit is run under .NET Framework 6+ and not under legacy PowerShell. You need to provide additional DLLs in order for this capability to function. Please refer to Accessing Certificates from the Azure Key Vault.

Azure Key Vault access is also available on non-Windows (Linux) platforms. For more information on running the PS toolkit on non-Windows platforms, please refer to Using the Tachyon PowerShell Toolkit on non-Windows platforms.

Get-TachyonServer

Returns the currently configured Tachyon server. An error is thrown if no server is configured

Get-TachyonVersion

Returns the version of the currently configured Tachyon server. An error is thrown if no server is configured

Get-TachyonToolkitVersion

Returns the version of the PowerShell toolkit

Get-TachyonDefaultConsumer

Returns the Tachyon consumer that is used when communicating via the API. The default is 'Explorer'

Set-TachyonDefaultConsumer -Name <name>

Sets the default Tachyon consumer that is used when communicating via the API. An error is thrown if an invalid consumer is specified and the current default remains unchanged

Get-TachyonComponentHealth

Returns information about the status of each Tachyon subsystem.

Note

This cmdlet requires Tachyon 5.1 or later. It will throw an error if invoked against earlier releases because the API was not implemented in those releases.

Get-TachyonConsumer [-Id <id>] [-Name <name>]

Returns the available Tachyon Consumers and their properties. Currently the PowerShell toolkit uses the Explorer consumer, so that instructions and results invoked from the toolkit are also visible in the Explorer UI

If either the optional Id or Name parameters are supplied, then only the consumer whose Id or name matches the parameter value is returned.

Get-TachyonDeviceTag

Returns the available device tags (also referred to as custom properties or coverage tags) that have been defined on the Tachyon server

Note

Device tags can be used in scope expressions to determine the target set of devices for instructions. For more information on scope expressions, see Using scope and filter expressions with the Tachyon PowerShell Toolkit

Get-TachyonDeviceTagValue -Id <id>|-Name <name>

Returns the available values for a specified device tag Id or name

Add-TachyonDeviceTag -Name <name> -Values <values>

Adds a device tag with the specified name and an initial value set <values>. You can specify a single string for 'value' or an array e.g @('value1','value2'....)

Note

Once you have added a tag and an initial value, you use the Add-TachyonDeviceTagValue cmdlet to add further values, or the Remove-TachyonDeviceTagValue cmdlet to remove values. A tag must have at least one associated value at any time.

Add-TachyonDeviceTagValue -Id <id>|-Name <name> -Value <value>

Adds a new property value to the device tag whose Id is specified in the -Id parameter or whose name is specified in the -Name parameter

Note

An error is thrown if the device tag does not exist. Use add-tachyondevicetag to create a tag

Remove-TachyonDeviceTag -Id <id>|-Name <name>

Remove the device tag specified by the -Id or -name parameter, along with all it values

Remove-TachyonDeviceTagValue -Id <id>|-Name <name> -Value <value>

Removes the specified value from the list of device tag values. An error is thrown if the value does not exist or if it would be the last remaining value associated with the device tag.

Note

The API actually permits all tag values to be deleted without removing the tag itself. However this is not supported by the Explorer UI, which does not expect to find a tag with zero values. Therefore this cmdlet enforces that limitation by preventing you from deleting the last remaining value without deleting the tag itself

Get-TachyonDeviceTagId -Name <name>

Gets the tag id for the specified tag name

Get-TachyonDeviceTagName -Id <id>

Gets the tag name for the specified tag id

Get-TachyonNotification [-Id <id>]

Returns any notifications that are available for the current user. The optional Id parameter allows you to retrieve only notifications associated with a specific instruction

Note

Use the Get-TachyonApprovalNotification cmdlet to retrieve instruction approval notifications (that would be displayed in the Tachyon Explorer UI on the 'notifications' page.)

Get-TachyonApprovalNotification

Return any notifications regarding instruction approval. This cmdlet returns notifications that are visible in the Tachyon Explorer UI

Get-TachyonSystemTopography

Returns information about the physical Tachyon system topography, i.e, switches, cores etc.

Get-TachyonSystemStatistics

Returns a summary of information about the system, as shown below

233276850.png
Get-TachyonSLAComponentHealth

Returns health status for the SLA subsystem, including component status and database connectivity checks.

Publish-TachyonSchedule -InstructionName <instruction name> ...

-TargetScope <scope>

-Schedule <schedule>

[-EvaluationCondition <condition>]

[-Task <task>]

[-StartDate <start date>]

[-EndDate <end date>]

[-StartTime <Start time>]

[-EndTime <end time>]

[-InstructionTtlMins <mins>]

[-ResponseTtlMins <mins>]

[-ConsumerCustomData <string>]

Creates a new schedule. Optionally you can specify a server-side task script to be run each time the schedule triggers, after the associated instruction has executed.

Note

An instruction schedule creation operation requires workflow approval, whether or not the scheduled instruction is a question or an action. For more information on Tachyon workflow, please refer to Workflow management cmdlets.

Please refer to Using the Tachyon PowerShell Toolkit to manage Tachyon schedules for a scenario walking you through the creation of a schedule and approving it can be found.

Parameter

Description

InstructionName

The name of the instruction to be scheduled.

TargetScope

The scope for the instruction.

Note

TargetScope is evaluated as dynamic scope. That is, unlike the default scope for an instruction invoked directly from the PowerShell toolkit, which evaluates to a set of currently-active devices, the scope is left as a target expression and evaluated when the scheduled instruction is actually invoked each time. This is equivalent to specifying dynamic scope when invoking a normal instruction from the PowerShell toolkit.

Schedule

The schedule options. Valid schedules are:

  • Hourly

  • Daily

  • Weekly [on day n]

  • Monthly [on day nn]

  • [Every] nn mins|minutes

  • Once

Note

If the day is not specified for weekly or monthly schedules, it defaults to day 1 which is Sunday for weekly schedules or the first day of the month for monthly schedules.

EvaluationCondition

An optional evaluation condition which, if true, will cause the optional Task script to be run server-side.

This parameter directly accepts an evaluation condition as an expression. e.g -EvaluationCondition "NumberOfRows > 20"

Task

The name of a task script to be run server-side. If an evaluation condition is specified, the task script is only run once the instruction specified in the schedule has returned all results and the condition is evaluated to true.

If no evaluation condition is specified, the task script is run once the instruction specified in the schedule has returned all results.

For example, the evaluation condition specified above will cause the conditional action task script to be run if more than 20 rows were returned from the instruction when it is invoked.

Note

See the publish-conditionalaction cmdlet below for more information on task scripts

When you specify an evaluation condition the appropriate API model parameters (discussed in the link above) are set for you automatically.

StartDate

The date on which the schedule first becomes active. If not specified, today's date is used.

EndDate

The date on which the schedule ceases to be active. If not specified, the start date plus one day is used as the default.

Note

For scheduling periods longer than daily, these defaults will cause the schedule to be rejected with the error that no scheduled events would occur in the specified time period. Ensure that the end date is sufficiently later than the start date to accommodate the chosen schedule period.

Both start and end dates are specified in the format YYYY-MM-DD. If a datetime is passed, the time period is ignored.

StartTime

For a schedule which triggers at most once in any day, specifies the time of day when the schedule will trigger.

For a schedule which triggers multiple times in a day, specifies the time of day when the first trigger event will occur.

EndTime

For a schedule which triggers multiple times in a day, specifies the time of day after which trigger events will no longer occur.

Note

When a one-time schedule is defined, if the start date is today, and the start time is not specified, it is set to one minute later than the current time

Start and end times are integer values. They are interpreted as HHMMSS so the maximum value is 235959 which corresponds to 23:59:59

InstructionTtlMins

The length of time the instruction will gather data for. The default is 60 minutes.

Note

Defining a schedule period less than the instructionttlmins value will cause an error.

ResponseTtlMins

The length of time the instruction results will remain available after the data collection phase has ended. The default is 60 minutes.

ConsumerCustomData

an arbitrary string (which could be encoded JSON) which will be available via the get-tachyoninstructionstatus cmdlet when the instruction becomes active.

Alternatively you can directly pass an object which is serialisable to JSON and it will be automatically serialised and stored as a JSON-encoded string.

For example, you can pass the object @{Property1="Value1" , Property2 = "Value2"}.

You can use this as a parameter-passing mechanism for conditional action tasks (see discussion below)

233276849.png
Get-TachyonSchedule [-Id <id>]

Returns all defined schedules or the schedule whose Id is specified.

Remove-TachyonSchedule -Id <id>

Removes (deletes) the specified schedule.

Note

This has no impact on any conditional action script (if any) associated with the schedule, which will remain on the server until deleted.

Get-TachyonScheduleActivation -Id <id>

Returns all activations of the specified schedule (if any).

Get-TachyonScheduleParam -Schedule <schedule>

Returns the scheduling API parameters which would be required to implement the schedule defined.

233276848.png
Publish-TachyonConditionalAction -Path <script> [-Force]

Publishes(uploads) the specified script. This script can be associated with one or more scheduled tasks. It is written in PowerShell and must be signed, with the code signing certificate being available on the Tachyon server to verify the script. Please refer to Requirements for using the Tachyon PowerShell Toolkit: Signing PowerShell scripts.

To overwrite an existing script, use the -Force option.

Note

This cmdlet does not verify that the script is signed or, if signed, that the signature is valid. The script will be uploaded to the server regardless.

Remove-TachyonConditionalAction -Name <name>

Removes (deletes) the conditional action script whose name is specified. Note that if any scheduled tasks have been associated with this conditional action script, an error is thrown. These scheduled tasks will need to be removed, or updated to remove the script reference before the conditional action can be removed.