Package Creator: Difference between revisions
Line 164: | Line 164: | ||
=====Adding Parameters to Options / Arguments===== | =====Adding Parameters to Options / Arguments===== | ||
In order for values to be passed to an operations command a parameter will is required to pass them via the Options / Args section. The ordering and format will depend on what is required by the target of the specified Command Type. | |||
[[File:PackageOperationParamSelector.png|right|350px|link=https://wiki.hornbill.com/images/9/9b/PackageOperationParamSelector.png]] | [[File:PackageOperationParamSelector.png|right|350px|link=https://wiki.hornbill.com/images/9/9b/PackageOperationParamSelector.png]] | ||
Input Parameters have the syntax of {param.<parameter name>} and is placed where the value is expected when the command is executed. Parameters are entered manually; however, if the letters ''pa'' are entered, a list of allowed parameters are provided and can be selected and added to the list. If the value of the parameter is blank at the time of execution, then nothing is output. In some cases, where the parameter value is paired with an option such as '''-option <value>''', if the value is blank, then the option is removed. This scenario is catered for by modifying the variable syntax to include the option, e.g. '''{-option param.name}''' | Input Parameters have the syntax of {param.<parameter name>} and is placed where the value is expected when the command is executed. Parameters are entered manually; however, if the letters ''pa'' are entered, a list of allowed parameters are provided and can be selected and added to the list. If the value of the parameter is blank at the time of execution, then nothing is output. In some cases, where the parameter value is paired with an option such as '''-option <value>''', if the value is blank, then the option is removed. This scenario is catered for by modifying the variable syntax to include the option, e.g. '''{-option param.name}''' |
Revision as of 08:26, 20 August 2021
Home > Administration > ITOM > Package Creator | Index |
IntroductionThe Package Creator allows a user to create Operations within Packages with the necessary programming background and ability. A Package consists of a single Package Info file and with additional resource files where required. The info file contains all the details regarding operations and all parameters that may be necessary. Although it is possible to create a Package manually, a form-based editor is provided to simplify the process to upload and organise resources. These files are used to provide or support a package's operations a can be a combination of; for example; one or more scripts and other filetypes. In addition to uploading files, an interface is also provided to allow various file types to be created via a browser-based editor. |
|
Toolbar
- Refresh
- Target OS
- Operating System that the package was designed for execution
- Windows 32/64-bit
- Apple macOS
- Generic Linux
- Purpose
- Dynamic list populated from the Purpose field of entriies in the list
- Filter by package
- Free text filter on Package
-
- Create an IT Automation Package
- Delete
- Delete selected Package(s)
List
- Package
- Unique name given to the Package
- Purpose
- Summary of the intended use of the package
- Target OS
- Operating System that the package was designed for execution
- Published
- Late Published version of the packacge
- Created On
- Date that the package was created
- Created By
- The account used to create the package
- Last Updated On
- Date the package was last updated
- Last Updated By
- The account last used to update the package
Working with Packages
The package editor displays a list of resources used, one of which is the Package Info file created by the system. This file contains the configuration details that define the packages operations and how any additional resources are used. Selecting the file displays a form used to edit the details, it also possible to edit the file in its raw XML format via the built-in editor. Additional resources such as scripts, data files can be created directly from within the interface via an editor, binary files such as executables and windows installer files can be uploaded.
Create a New Package
Open an Existing Package
- Locate the Package in the Package Creator list
- Click on the Package name
Delete a Package
Package Content Toolbar
- Upload
- Uploads files to the current folder
- New Folder
- Creates a new Folder
- New File
- Creates a new file in the current folder
-
- Creates a new baseline of the current package
- Save
- Saves amended package details
Package Information
The Package Info file is viewed and modified via a form, displayed by default when entering the editor or whenever the file is selected. The following details can be edited via the form excluding the Package ID and Name:
- Package ID
- A GUID which uniquely identifies the package) will be generated on creation
- Package
- The name of the package entered during creation
- Description
- Description of the packages content
- Purpose
- Summary of the intended use of the package
- Vendor ID
- Defined by the creator of the package (Hornbill packages will set to "Hornbill")
- Target OS
- Specifies the target operating system that the package is designed to run on
- Windows 32-bit
- Windows 64-bit
- Windows Universal
- Package can be invoked on either Windows 32 or 64-bit
- Apple macOS
- Generic Linux
Selecting the XML View button on the toolbar switces the form editor to a text editor where the file can be edited in its native XML format. This can be useful when it is required to make changes that can be quite tedious using the form view such as generic modifications to package operations.
Package Operations
A package must contain one or more operations; each will perform an action that can be defined using one of a number of the command types. The Comand Type selected will depend on the Operating System to target the package and the functionality required. Some operations will require files to be created or uploaded before they can be configured, in the case where a script is to be executed. Other operations such as those that execute as a single command can be configured via the interface provided.
Creating an Operation
- Click the Add Operation button, located on the Package Operations section
- Enter a unique Operation name
- Enter a Description of the operation
- Select the Command Type
- Click Add
- The selected Type determines whether a command is entered or a file is selected, where a file is required it must already have been created or uploaded to the package.
Operation Properties
- Operation
- Mandatory Name used to select the package when creating a Job
- Description
- Describes the functionality provided by the operation
- Command Type
- Provides a list of supported command types
- Run Command
- Used to run an executable program on the target device
- Windows
- Execute a program that is localy installed on the target device. If the program name is entered with no extension then .exe is assumed, for .com programs the extension must be included. If it is required to execute a cmd command then the command should be entered as follows: cmd.exe /c <command>
- Linux\Unix
- Commands are executed using Secure Shell (ssh)
- Windows Installer
- Executes an Installer(.msi) package, with one of four actions detailed below. In order to use this operation the installer package will need to be uploaded to the package
- Install Software
- Installs the .msi package
- Run Program
- Executes the .msi package
- Uninstall Software
- Uninstall an .msi package
- Update Software
- Reinstalls the entire .msi package
- Windows Executable
- Executes an uploaded windows executable, selected from the Run File list
- Batch Script
- Excutes an uploaded Windows batch script (.cmd or .bat), selected from the Run File list
- Windows PowerShell
- Executes an uploaded Windows PowerShell script, selected from the Script list
- PowerShell Core
- Execute an uploaded PowerShell Core script, selected from the Script list
- Linux Shell Script
- Executes an uploaded Linux / Unix shell script via SSH
- Timeout
- Number of seconds before the operation times out, and setting the status of the Job to Timed Out
- Options / Args
- Specifies arguments that are passed to the specified command at runtime. The format required is dependant on the Command Type being used, below are some typical examples:
- Powershell
- parameter1 ... parameterx -Arg1 <value> -Arg2
- Windows batch file
- /O /A <value> parameter1 ... parameterx
- Linux Script
- -arg1 <value> -arg2 --long-arg parameter1 ... parameterx
Input Parameters
Input parameters are only required if the operation requires data to be passed to it. They allow for values to be dynamically applied at execution for use by the operation. Each parameter can be identified as required (mandatory) and given a specific data type used for basic validation. Parameters can be manually assigned or populated via variables generated from within a Runbook, BPM or Autotask process.
To create a new parameter, from the Add Operation form:
- Click the Add Parameter button
- Select Optional or Required from the drop-down
- Set the Data type from the drop-down
- Enter the parameter Name
- If required, enter a Default value
- Enter the Hint text
- Specify if the parameter is sensitive
- Requirement
- Each parameter can be specified as Required or Optional
- Type
- Specifys one of the following data types that can be entered: String, Number or Boolean. This will be used for basic validation when parameter values are entered
- Parameter name
- Used to identify the parameter when adding it to the arguments/options list
- Default value
- Each parameter can be provided with default value
- Hint
- Describes the parameter and is visible during data entry
- Actions
- Action buttons
- Sensitivety
- A Toggle that marks a parameter as sensitive (struck out eye) and thus will not show its value during data entry
- Delete
- Removes the parameter
Adding Parameters to Options / Arguments
In order for values to be passed to an operations command a parameter will is required to pass them via the Options / Args section. The ordering and format will depend on what is required by the target of the specified Command Type.
Input Parameters have the syntax of {param.<parameter name>} and is placed where the value is expected when the command is executed. Parameters are entered manually; however, if the letters pa are entered, a list of allowed parameters are provided and can be selected and added to the list. If the value of the parameter is blank at the time of execution, then nothing is output. In some cases, where the parameter value is paired with an option such as -option <value>, if the value is blank, then the option is removed. This scenario is catered for by modifying the variable syntax to include the option, e.g. {-option param.name}
Possible supported combinations Format Parameter Value Output <option> {param.name} abcd -option abcd <option> {param.name} <empty string> -option {<option> param.name} abcd -option abcd {<option> param.name} <empty string> <blank>
- <option> can be any text and thus allow for all formats of options and arguments that may be required i.e. /O, -Output, --Out-file or even start. In order to specify this format just edit the parameter once it has been added or type itin manually.
Output Parameters
Output parameters allow for output from the package operation to be accessed after an IT Automation has executed. When executed within a BPM process or Runbook, the output parameters can be accessed via self-named variables enabling the values to be used as inputs to other nodes within the process. Similar to input parameters, each can be specified as required and are provided with a data type.
To create a new parameter, click the Add Parameter button on the Add Package Operation form.
- Requirement
- Each parameter can be specified as Required or Optional. If a required parameter is not returned in the operation's output the IT Automation will return a failure after the package has been executed.
- Type
- Specifys one of the following data types that can be entered: String, Number or Boolean. This will be used for basic validation when parameter values are entered
- Parameter name
- Used to identify output parameters returned by the operation
- Default value
- Each parameter can be provided with default value
For the output parameters to reference the values, they are required to be output using the following syntax:
- {{SISJobOutputParameterStart:<param-name>}}<value>{{SISJobOutputParameterEnd}}
<param-name> being the name of the configured output parameter and <value> the actual value to store, and one entry will be required for each required parameter.
Providing the formatted output is relatively straight forward when the script or program is designed in-house; however, when attempting to use a third-party script or program that cannot be modified can prove difficult. In these circumstances, there are still options that can be applied:
- Create a wrapper script and reformat the output to match required syntax
- Use the scripts/programs return code to provide feedback
Utilising the return codes can be a quick, simple way to return values that can be used logically within a process; the following are some examples of what can be achieved:
Windows Commands
Command Type Run Command Command cmd Options / Args /c find "{param.searchstring}" "C:\ProgramData\Hornbill\Site Integration Server\log\EspSisService.log" && echo {{SISJobOutputParameterStart:outcome}}OK{{SISJobOutputParameterEnd}} || echo {{SISJobOutputParameterStart:outcome}}FAIL{{SISJobOutputParameterEnd}}
Linux Commands
Command Type Run Command Command grep Options / Args /var/log/syslog -e "{param.searchstring}"; error=$?; if [ $error == 0 ]; then echo "{{SISJobOutputParameterStart:outcome}}OK{{SISJobOutputParameterEnd}}"; else echo "{{SISJobOutputParameterStart:outcome}}FAIL{{SISJobOutputParameterEnd}}"; echo "{{SISJobOutputParameterStart:errors}}$error{{SISJobOutputParameterEnd}}"; fi
Powershell Commands
Command Type Run Command Command powershell Options / Args -Command "& { if(Select-String -Path 'C:\ProgramData\Hornbill\Site Integration Server\log\EspSisService.log' -Pattern '{param.searchstring}' -Quiet) {Write-Host '{{SISJobOutputParameterStart:outcome}}OK{{SISJobOutputParameterEnd}}'} else {Write-Host '{{SISJobOutputParameterStart:outcome}}FAIL{{SISJobOutputParameterEnd}}' }" }
Managing Files
As well as being able to upload files for use by operations, it is also possible to create files directly via the interface. The editor supports the following file types and also provides enhanced usability with the use of syntax highlighting.
- .bat
- Command Prompt Batch process files
- .ps1
- Powershell and Powershell Core scripts
- .js
- Javascript
- .sh
- Unix/Linux and macOS Shell script
- .txt
- Text format file
- .json
- JavaScript Object Notation file
- .csv
- Comma Seperated Value file
The following will affect the entire instance so care should be taken!
Some of the above files are restricted by default; and can be allowed by disabling the System Setting: security.fileUploadRestriction.entity.fileAttachments.enable or alternatevly remove the relevant extensions from the System Setting: security.fileUploadRestriction.entity.fileAttachments.types.
Upload a File
- Click the Upload button
- Select the File to Upload
- The file appears in the file list
- Select the File to View in the Editor pane