1E 23.11 (SaaS)

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.

InstructionName

The name of the instruction to be scheduled.

TargetScope

The scope for the instruction.

Schedule

The schedule options. Valid schedules are:

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.

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.

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.

InstructionTtlMins

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

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)