Package Creator

Home > Administration > ITOM > Package Creator

Index

Introduction The Package Creator allows for the creation of user-defined Packages for use on an instance. 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 uploading and organising resources. These files are used to provide or support a package's operations a can be a combination of one or more scripts, executables and other supported filetypes. In addition to uploading files, an interface is also provided to create and edit various file types via a browser-based editor that supports syntax highlighting.

Related Articles ITOM Package Creator Quick Guide ITOM Package Library

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 a Package Create an IT Automation Package

Delete Delete selected Package(s)

Package 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

Create a New Package

1. From the Package Creator list, click the button
2. Enter a new Package Name
3. Click Create

Open an Existing Package

1. Locate the Package in the Package Creator list
2. Click on the Package name

Delete a Package

1. From the Package Creator list
2. Click the tick box next to each package to delete
3. Click the button

Package Editor

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 is 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, administrators can upload binary files such as executables and windows installer files.

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

Baseline 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 switches the form editor to a text editor where an administrator can edit the file in its native XML format. This can be useful when making changes that can be quite tedious using the form view, such as generic modifications to packaging 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, executing a script. Other operations such as those that execute as a single command can be configured via the interface provided.

Creating an Operation

1. Click the Add Operation button, located on the Package Operations section
2. Enter a unique Operation name
3. Enter a Description of the operation
4. Select the Command Type
5. 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 within a Runbook, BPM or Autotask process.

To create a new parameter, from the Add Operation form:

1. Click the Add Parameter button
2. Select Optional or Required from the drop-down
3. Set the Data type from the drop-down
4. Enter the parameter Name
5. If required, enter a Default value
6. Enter the Hint text
7. 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

For values to be passed to an operation command, a parameter will be required to pass them via the Options / Args field. 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 all of the operation's input parameters are provided, and one can be selected from the list. Entering any further characters will filter the list based on whether any entries contain the entered character.

During the execution of the operation, if the parameter value is blank, nothing is output and may not be the desired effect, as detailed in the following scenarios:

1. The parameter is passed as a positional parameter and requires an empty string to be passed if blank.

   To ensure an empty string is passed when the value is blank, the parameter should be encapsulated within quotes. "{param.ParamA}"

2. The parameter value is paired with an option such as -option {param.ParamA}, if the value of {param.ParamA} is blank; then the -option is not removed.

   This can be remedied by encapsulating the option within the parameter definition such as: {-option param.ParamA}

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 output from the package operation to be accessed after an IT Automation has been executed. When executed within a BPM process or Runbook, the process can access the output parameters 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 parameter must be: 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

Output Parameters Syntax

Output parameters are processed after the execution of an IT Automation and are identified by the output using the following syntax:

{{SISJobOutputParameterStart:<param-name>}}<value>{{SISJobOutputParameterEnd}}

• <param-name> being the name of the configured output parameter
• <value> the actual value to store, and one entry will be required for each required parameter.

Providing the formatted output is relatively straightforward when the script or program is designed in-house; however, attempting to use a third-party script or program that is not modifiable can prove difficult. In these circumstances, there are still options available:

• Create a wrapper script and reformat the output to match the required syntax
• Use the scripts/programs return code to provide feedback

Utilising the return codes can be a quick, simple way to capture output parameter values that can be used logically within a process. The Options / Args field can specify input parameters for the command and contain the logic to deal with any return code. The following examples show what can be achieved for different command types:

Windows Commands

Command Type	Run Command
Command	cmd /c find
Options / Args	"{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 -Command
Options / Args	"& { 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!

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

1. Click the Upload button
2. Select the File to Upload

   The file appears in the file list

3. Select the File to View in the Editor pane

Create a New Folder

1. Click the Add New Folder button
2. Enter the Folder Name

Add New File

1. Click the Add New File button
2. Enter the file name

The following actions are executed on individual files and folders; ensure that the correct file or folder is selected first from the file list. The menu options are context-sensitive and will only display the options relevant to the selected item.

Delete a File or Folder

1. Select the File or Folder to Delete
2. Click the Delete button

Download a File

1. Select the File to Download
2. Click the Upload button

   The file will appear in the browsers download folder

Save a File

The Save button is enabled when a file is loaded into the editor and its contents have changed. Clicking on the Save will save the changes and reset the buttons state. Exiting from the editor also prompts to save the file, with the option to Save, Cancel or Ignore the changes.

Baselining and Publishing

A Baseline is a snapshot of a package's current state, only available once the package is in a state where it is ready to be published (at least one Package Operation exist).

The draft version of a package is the only version that can be updated. Once the Package is ready for release, the draft copy can be Baselined, creating a new version. This latest version is then available for packaging and installation on the Installed Packages list.

To enable the Baseline once the initial package has been created, the user must highlight the Package Info file in the file list. Once clicked, a confirmation pop appears, and the dropdown next to the Baseline Button will display a list of Baselined versions.

To publish and install or download a baselined version, select the relevant version from the list. The Baseline button will change to the Package and Installwhen clicked, two options are provided:

• Package and Install

Build the package and add to the Install Packages list, Overwriting any existing version

• Package and Download

Build the package and Download to the local computer

The package details will be read-only to change any details; The user must select the draft version by clicking the View Draft button.

Baseline and Publish a new version of a package

1. Select the ITOM Package Creator
2. From the list select a package
3. Click the Baseline button
4. Select the Baseline button drop-down
5. Select the last version
6. Click Package and Install, and select Package and Install
7. Use the Breadcrumbs to go back to the Package Creator list

The Package should now appear in the list with the latest version shown; all subsequent Jobs, including previously scheduled jobs, will now use the newly published version.