Package API

This page documents the install.xml file, that must reside as a manifest file in the root of .sigmapackage files.

Manifest format

The manifest is an XML file with a root element named sigma.package.manifest.
The root node can contain the following child elements:

Name Value Description
id string, optional A unique ID; Either a script ID or a GUID.
name string, optional Name of the package.
For display in the user interface.
version string, optional Installer package version.
For display in the user interface.
description string, optional Longer description of the package content.
For display in the user interface.
productURL string, optional URL of product homepage.
For display in the user interface.
productId string, optional Id of the product.
type integer, optional 0: Unknown
1: Script add-in
2: Addendum (i.e. pretty much anything else)
authorID string, optional Author ID.
Public API key of author.
authorName string, optional Name of author.
For display in the user interface.
authorURL string, optional URL of author homepage.
For display in the user interface.
destination string, optional Name of the destination folder.
Environment variables are supported, and special path variables (see bottom of article)
If “id” or “productId” is specified, the application will search for an already installed add-in then the package is considered an update of that add-in and the installation folder of the add-in is used.If that is not the case, the destination is determined by:

  • If the “destination” is specified, then the destination folder is set to the value
  • Else, if the manifest specifies a ProductID the destination folder is set to %SigmaScriptPath%\<ProductID>.
  • Else, if the manifest specifies a ProductName and an AuthorID then the destination folder is set to %SigmaScriptPath%\<AuthorID>.<ProductName>.
  • Otherwise the destination folder is set to %SigmaScriptPath%\<GUID> where <GUID> is a random GUID.
backup boolean, optional true: Overwrite and delete operations will save a backup of the file being replaced.
false: No backup is saved.
The value can be overridden on individual actions.
actions required List of actions to perform.
See Actions section.

Actions

Generally:

  • Relative source path: Source is a file in the package file.
  • Absolute source path: Source is local file system.
  • Source filename support wildcards.
  • Source and target filenames support environment variables.
  • If target specifies an absolute folder but no filename then the target folder and source filename is used.
  • If target specifies a relative path then the target is relative to the destination folder.

COPY action

  • Copies from local file system or package to local file system.
  • The operation fails if the source file does not exist.
  • If the operation overwrites a file and backup is enabled then the original file is copied to the backup folder and can be restored by an uninstall or rollback.

Properties

Name Value  
source Filename Required.
The file to copy from.
target Filename Optional.
The file to copy to.
Environment variables are supported, and special path variables (see bottom of article)
replace yes | no | newer | only | fail yes: Unconditional overwrite if file exists.
no: Skip copy if file exists.
newer: Skip copy if existing file time stamp newer.
only: Skip copy if file does not exist.
fail: Fail if file exists.
backup true | false Optional.
Enable or disable backup for action.

MOVE action

Moves or renames file in local file system.
The operation fails if the source file does not exist or if the destination file already exist.

Properties

Name Value  
source Filename Required.
The file to move or rename.
Path must be absolute.
target Filename Required.
The new filename.

DELETE action

Delete file from local file system.
If the file does not exist the operation does nothing.
If backup is enabled then the original file is copied to the backup folder and can be restored by an uninstall or rollback.

Properties

backup true | false Optional.

Name Value  
source Filename Required.
The file to delete.
Path must be absolute.
backup true | false Optional
Enable or disable backup for action.

EXECUTE action

Execute script from package or local file system.
The operation fails if the source file does not exist.

Properties

Name Value  
source Filename Required.

EULA action

Show an End User License Agreement, that the user must accept to continue. The source file is expected to be Rich Text Format (.rtf) which can be created with Microsoft Word. Add required=”true” as property on the action node if the user has to accept the terms.

Properties

Name Value  
source Filename Required.
title String  
description String  

 

RESTART action

Request a restart of Sigma after the installation has been completed.

Properties

None

Path variables

The following list is the path variables that can be used to reference folders on the destination computer, and refers to the file locations that Sigma is aware of:

  • %sigma_projectspath%
  • %sigma_userlibpath%
  • %sigma_userpricelistspath%
  • %sigma_sharedlibpath%
  • %sigma_quicklibpath%
  • %sigma_datapath%
  • %sigma_reportsoutputpath%
  • %sigma_toolspath%
  • %sigma_reportspath%
  • %sigma_sharedreportspath%
  • %sigma_userreportspath%
  • %sigma_usertemplatespath%
  • %sigma_sharedtemplatespath%