en-US/about_JS7.help.txt
|
TOPIC
about_JS7 SHORT DESCRIPTION The JS7 Command Line Interface (CLI) can be used to control JS7 components and to perform bulk operations on job-related objects. DOWNLOAD The PowerShell Command Line Interface is available from GitHub at https://github.com/sos-berlin/js7-cli-powershell LONG DESCRIPTION The JS7 PowerShell Module can be used to control JS7 components and workflow-related objects. The module supports Windows PowerShell FullCLR 5.1 and PowerShell CoreCLR 6.x and 7.x for Windows, Linux and MacOS environments. It can be used with JS7 releases 2.x. The module is used for the following areas of operation: • provide bulk operations: o select orders and workflows o manage orders with operations to start, stop, suspend, resume • deploy workflows o deploy workflows and related objects o release calendars and schedules • manage Agents o add Agents to Controllers o check Agent status o retrieve Agent job execution reports GETTING STARTED Prerequisites Check Execution Policy • PS > Get-ExecutionPolicy o shows the current execution policy, see e.g. Microsoft Technet about_Execution_Policies o The required PowerShell execution policy for the JS7 CLI module is RemoteSigned or Unrestricted • PS > Set-ExecutionPolicy RemoteSigned o Modifying the execution policy might require administrative privileges • PS > Set-ExecutionPolicy bypass -Scope process o The recommended execution policy for use with jobs in JS7 workflows. Import Module • PS > Import-Module JS7 o loads the module from a location that is available with the PowerShell module path, o see $env:PSModulePath for predefined module locations. • PS > Import-Module C:\some_module_location\JS7 o loads the module from a specific location, absolute and relative paths for can be used on all platforms. Hint: You can add the command Import-Module JS7 to your PowerShell profile to have the module loaded on start of a PowerShell session, see PowerShell CLI - Use Cases - Credentials Management Use Web Service As a first operation after importing the module it is required to execute the Connect-JS7 cmdlet. • PS > Connect-JS7 -Url <Url> -AskForCredentials o specifies the URL for which the JOC Cockpit REST Web Service is available and asks interactively for credentials. The default account is root with the password root. • PS > Connect-JS7 <Url> <Credentials> <ControllerID> or PS C:\> Connect-JS7 -Url <Url> -Credentials <Credentials> -Id <ControllerID> o specifies the URL of JOC Cockpit which is the same URL that you would use when opening the JOC Cockpit GUI in your browser, e.g. http://localhost:4446. When omitting the protocol (HTTP/HTTPS) for the URL then HTTP is used. o specifies the credentials (user account and password) that are used to connect to the Web Service. A credential object can be created by keyboard input like this: Set-JS7Credentials -AskForCredentials A credential object can be created like this: $credentials = ( New-Object -typename System.Management.Automation.PSCredential -ArgumentList 'root', ( 'root' | ConvertTo-SecureString -AsPlainText -Force) ) The example makes use of the default account root and password root. A possible location for the above code is a user's PowerShell Profile that would be executed for a PowerShell session. Credentials can be forwarded with the Url parameter like this: Connect-JS7 -Url http://root:root@localhost:4446 Specifying account and password with a URL is considered insecure. o specifies the Controller ID that the Controller has been installed with. As JOC Cockpit can manage a number of Controller instances the -Id parameter can be used to select the respective Controller. o allows to execute cmdlets for the specified Controller independently from the server and operating system that the JS7 Controller is operated for, for example you can use PowerShell cmdlets on Windows to manage a JS7 Controller running on a Linux box and vice versa. As an exception to this rule you cannot start a remote JS7 Controller and you cannot start a remote JS7 Windows Service, however, you can restart, terminate, abort JS7 Controllers on any platform. Run Commands The JS7 CLI provides a number of cmdlets, see PowerShell CLI - Cmdlets • The complete list of cmdlets is available with the command: o PS > Get-Command -Module JS7 • Cmdlets come with a full name that includes the term JS7: o PS > Get-JS7ControllerStatus • The term JS7 can further be omitted if the resulting alias does not conflict with existing cmdlets: o PS > Get-Status • Should conflicts occur with existing cmdlets from other modules then no conflicting aliases will be created. Aliases can be forced by use of the cmdlet: o PS > . Use-JS7Alias EXAMPLES Find some typical use cases for the JS7 CLI. • PS > Get-JS7ControllerStatus -Display o shows the summary information for a JS7 Controller. • PS > (Get-JS7Workflow).count o shows the number of workflows that are available. • PS > (Get-JS7AgentInstances).count o shows the number of Agents that are available. • PS > $orders = (Get-JS7Order -Folder /my_orders -Recursive | Suspend-JS7Order) o retrieves orders from the my_orders folder and any sub-folders with orders found that will be suspended. The list of affected orders is returned. • PS > $orders | Stop-JS7Order o cancels orders based on a list that has previously been retrieved. MANAGE LOG OUTPUT JS7 Cmdlets consider verbosity and debug settings. • PS > $VerbosePreference = "Continue" o This will cause verbose output to be created from cmdlets. • PS > $VerbosePreference = "SilentlyContinue" o The verbosity level is reset. • PS > $DebugPreference = "Continue" o This will cause debug output to be created from cmdlets. • PS > $DebugPreference = "SilentlyContinue" o The debug level is reset. SEE ALSO • For an introduction see PowerShell CLI - Introduction, https://kb.sos-berlin.com/x/PpQwAw • For typical areas of operation see PowerShell CLI - Use Cases, https://kb.sos-berlin.com/x/95swAw • Full list of JS7 cmdlets: PowerShell CLI - Cmdlets, https://kb.sos-berlin.com/x/fpQwAw |