PowerShell CLI 2.0 - Cmdlets - Set-JS7JobResource

Name

Set-JS7JobResource

SYNOPSIS

Stores a variable to a Job Resource in the JOC Cockpit inventory.

SYNTAX

Set-JS7JobResource [-Path] <String> [-Key] <String> [[-Value] <String>] [[-File] <String>] [[-EnvVar] <String>] [-AsString] [-AsNumber] [-AsBoolean] [[-EncryptCertificate] <X509Certificate2>] [[-EncryptCertificatePath] <String>] [[-JavaHome] <String>] [[-JavaLib] <String>] [[-JavaOptions] <String>] [[-AuditComment] <String>] [[-AuditTimeSpent] <Int32>] [[-AuditTicketLink] <Uri>] [-WhatIf] [-Confirm] [<CommonParameters>]

DESCRIPTION

A variable is created/updated in a Job Resource. If the Job Resource does not exist, then it will be created.
Values of variables can hold strings, numbers and files. Optionally the values can be encrypted,
for details see https://kb.sos-berlin.com/display/JS7/JS7+-+Encryption+and+Decryption

The following REST Web Service API resources are used:

* /inventory/store

PARAMETERS

Path

-Path <String>
Specifies the folder, sub-folder and name of the Job Resource, this is the path to which the Job Resource will be stored in the inventory.

Key

-Key <String>
Specifies the name of the variable in the Job Resource that should be stored. Considder that names of variables are case-sensitive.

Value

-Value <String>
Specifies the value that should be stored for the given variable in the Job Resource.

Only one of the parameters -Value or -File can be used.

File

-File <String>
Specifies that the contents of a file should be added as the value of a variable to the Job Resource.

Only one of the parameters -Value or -File can be used.

EnvVar

-EnvVar <String>
Specifies the name of the environment variable in the Job Resource that holds a reference to the variable.

* Shell jobs access Job Resource variables from environment variables.
* JVM jobs access Job Resource variables directly.

AsString

-AsString <SwitchParameter>
The value specified for the -Value parameter is considered a string. This similarly applies to numeric values that will be quoted to preserve leading zeroas.

If none of the -AsString, -AsNumber or -AsBoolean parameters is specified then the cmdlet will guess the matching data type from the value specified with the -Value parameter.

AsNumber

-AsNumber <SwitchParameter>
The value specified for the -Value parameter is considered a number. This includes that leading zeros are removed.

If none of the -AsString, -AsNumber or -AsBoolean parameters is specified then the cmdlet will guess the matching data type from the value specified with the -Value parameter.

AsBoolean

-AsBoolean <SwitchParameter>
The value specified for the -Value parameter is considered a Boolean. The string values 'true' and 'false' can be specified and the $True and $False built-in PowerShell constants can be used.

If none of the -AsString, -AsNumber or -AsBoolean parameters is specified then the cmdlet will guess the matching data type from the value specified with the -Value parameter.

EncryptCertificate

-EncryptCertificate <X509Certificate2>
Specifies that the value of the Job Resource variable should be encrypted using a Certificate object.
Consider that the job that will decrypt the value requires access to the Private Key matching the Certificate.

Certificate objects can be retrieved from a Windows certificate store using the Certificate's thumbprint like this:
$cert = Get-ChildItem cert:\CurrentUser\my | Where { $_.Thumbprint -eq '2B03EA68F103E80D83228ABCF88A3B448CC8B257' }

Only one of the parameters -EncryptCertificate or -EncryptCertificatePath can be used.

Encryption requires use of the -JavaLib parameter that points to the location of JS7 encryption libraries.

EncryptCertificatePath

-EncryptCertificatePath <String>
Specifies that the value of the Job Resource variable should be encrypted using a Certificate or Public Key in PEM format from the indicated location.
Consider that the job that will decrypt the value requires access to the Private Key matching the Certificate/Public Key.

Encryption can be applied to values specified with the -Value parameter and to files specified with the -File parameter.
For file encryption the variable specified by the -Key parameter holds the to_file() function and the encrypted contents of the file.
The encrypted key to decrypt the file is made avaiable from a second variable with the same name as specified by the -Key parameter
and the extension _key.

Only one of the parameters -EncryptCertificate or -EncryptCertificatePath can be used.

Encryption requires use of the -JavaLib parameter that points to the location of JS7 encryption libraries.

JavaHome

-JavaHome <String>
Specifies the location to which Java is installed. Java will be required if values should be encrypted using the -EncryptCertificate or -EncrypCertificatePath parameters.
If the parameter is not specified then Java will be used from the value of the JAVA_HOME or PATH environment variables.

JavaLib

-JavaLib <String>
Specifies the location of the JS7 encryption libraries. The parameter is required if values should be encrypted using the -EncryptCertificate or -EncrypCertificatePath parameter.

The libraries ship with Agents and are available from the Agent's <agent-home>/lib directory. For encryption outside of JS7 products the JS7 encryption libraries are available for download.

JavaOptions

-JavaOptions <String>
Specifies the Java options used when invoking Java for encryption using the -EncryptCertificate or -EncrypCertificatePath parameter.
Java options can be used for example to limit memory usage as with -JavaOptions "-Xmx32m".

AuditComment

-AuditComment <String>
Specifies a free text that indicates the reason for the current intervention, e.g. "business requirement", "maintenance window" etc.

The Audit Comment is visible from the Audit Log view of the JOC Cockpit.
This parameter is not mandatory. However, the JOC Cockpit can be configured to require Audit Log comments for all interventions.

AuditTimeSpent

-AuditTimeSpent <Int32>
Specifies the duration in minutes that the current intervention required.

This information is shown in the Audit Log view. It can be useful when integrated
with a ticket system that logs the time spent on interventions with JS7.

AuditTicketLink

-AuditTicketLink <Uri>
Specifies a URL to a ticket system that keeps track of any interventions performed for JS7.

This information is shown in the Audit Log view of JOC Cockpit.
It can be useful when integrated with a ticket system that logs interventions with JS7.

WhatIf

-WhatIf <SwitchParameter>

Confirm

-Confirm <SwitchParameter>

RELATED LINKS

about_JS7

EXAMPLES

-------------------------- EXAMPLE 1 --------------------------

PS > Set-JS7JobResource -Path /ProductDemo/Variables/pdBusinessDate -Key 'BusinessDate' -Value (Get-Date (Get-Date).ToUniversalTime() -Format 'yyyy-MM-dd') -EnvVar 'BUSINESS_DATE'

Stores a key/value pair to the inventory object of a Job Resource.

-------------------------- EXAMPLE 2 --------------------------

PS > Set-JS7JobResource -Path /ProductDemo/Variables/pdConfigurationData -Key 'configurationData' -File '/tmp/configuration.conf' -EnvVar 'CONFIGURATION_DATA'

Stores the key and contents of a file to the inventory object of a Job Resource.

-------------------------- EXAMPLE 3 --------------------------

PS > Set-JS7JobResource -Path /ProductDemo/Variables/pdBusinessSecret -Key 'BusinessSecret' -Value '12345678' -EnvVar 'BUSINESS_SECRET' -EncryptCertificatePath C:\js7\js7.encryption\agent.crt -JavaLib C:\js7\js7.encryption\lib

Stores a key and encrypted value to the inventory object of a Job Resource. The -EnryptCertificatePath argument specifies the location of the Certificate or Public Key file. The -JavaLib argument specifies the location of the JS7 encryption libraries.

-------------------------- EXAMPLE 4 --------------------------

PS > Set-JS7JobResource -Path /ProductDemo/Variables/pdConfigurationDataSecret -Key 'configurationDataSecret' -File /tmp/configuration.conf -EnvVar 'CONFIGURATION_DATA_SECRET' -EncryptCertificatePath C:\js7\js7.encryption\agent.crt -JavaLib C:\js7\js7.encryption\lib

Stores the key and contents of a file to the inventory object of a Job Resource. The -EncryptCertificatePath argument specifies the location of the Certificate or Public Key file. The -JavaLib argument specifies the location of the JS7 encryption libraries.