Package Creator

Home > Administration > ITOM > Package Creator

Index

Introduction The 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.

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)

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

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 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 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

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 allow for values to be dynamically applied at execution and used by the operation. They can be identified as required (mandatory) and given a specific data type used for basic validation. Parameters can either be manually assigned or populated via variables generated from within a BPM or Runbook process.

To Create a Parameter click the Add Parameter button

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

• 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 configuration

Adding Parameters to Options / Arguments

Input Parameters have the syntax of {param.<parameter name>} and is placed where the value is expected when the command is executed. Parameters can be 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 should also be 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

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