OctoUtil is a command-line tool to execute commands against the OctoSAM Inventory Database.


OctoUtil.exe [options] [command] [arguments]

If no command is specified arguments are given, OctoUtil reads its commands from standard input.


--server servername --database databasename

These two options allow to override the configured database connection. Mainly useful for scripting in a multi-database environment. Only Windows integrated authentication is supported for these connections.

Commands can have various sub options


delete [machine|user|signature|package|publisher] id
deletes the specified object with the given id. For user objects you can also specify domain/user or domain\user or user principal name, for machine objects you can specify domain/machine or domain\machine.
delete [machines|users|signatures|packages|publishers] file
reads object ids from the given file (first column of a .csv file) and deletes the specified objects
execute planfile
executes the specified plan file
fix relations
checks common potential consistency problems in the software installation database fixes detected inconsistencies.
fix allrelations
checks additional potential consistency problems in the software installation database and fixes them.

The import service also fixes potential consistency problems in the housekeeping phase.

housekeeping options
performs all housekeeping tasks that rely on the database only. housekeeping tasks that connect to active directory or that import external data are not executed.
import codes codefile
import codes into the database. Do not use without consulting Octosoft first. Codes are usually updated with a software catalog update.
import groups groupfile
an alternative to import group definition. Do not use without consulting Octosoft first.
import repository repositoryfile
import zipped queries and reports repository
query guid file
runs the query identified by its guid and exports the visible files into a .csv file. This command supports additional options in the form column-:Column1,Column2... to suppress named columns in the output or column+:Column1,Column2... to include hidden columns in the output. Properties referenced in the query can also be supplied in the form propertyname=value on the command line. However, it is recommended to construct custom queries that report exactly the expected data. The command can also take the path to a query file (.qry.xml file) to run a query from a local file instead of the OctoSAM Repository.
update usage
updates package usage from signature usage details

The import service updates usage in the housekeeping phase.

wakeonlan machinename|machineid
sends wakeonlan network packages to the specified machine. OctoSAM WOL is powerful since it uses the collected networking information of the machine. The WOL packets are sent to all configured interfaces and also broadcast via detected router information.

Plan Files

A plan can contain multiple tasks that are executed in order. A task can either contain a simple script or it can contain a script that is executed for each row of a table. Tables can be initialized from a comma separated csv file or from an Excel file (.xlsx).

The plan processor uses the same engine as the query template language.

<?xml version="1.0" encoding="utf-8" ?>

        Loads edited Custom4 Field from native Excel File exported from Query "All Machines"        

    <property name="infile" value="c:\OctoSAMExports\machines.xlsx" />

    <task name="PurgeOldInfo">
        <!-- clean existing values -->
        <script language="sql">
            UPDATE Machine SET CustomField4 = ''

    <task name="ImportMachineCustom4">  
        <!-- load excel file and load Custom4 values into Machine table -->     
        <table name="in" file="${infile}" headers="true" trim="true" encoding="utf-8" />
        <foreach table="in" info="import ${in.MachineID} = ${in.Custom4} - ${in.Machine}">
            <script language="sql">
            UPDATE Machine SET CustomField4 = '${@sqlstr|${in.Custom4}}' WHERE ID = ${in.MachineID}     

This example plan imports Machine.CustomField4 from an .xlsx file generated by exporting the 'All Machines' query.


Scripts that only reference data within the OctoSAM database can also be run as housekeeping scripts from the import service directly.


table Element

<table name="in" file="c:/files/machines.xlsx" headers="true" trim="true" />

The <table> element loads a table of data from either a .csv or a Microsoft Excel .xlsx file.

Attribute Required Default Value Description
file Y Path to the file
headers N true if true, the first row contains the names of the columns
name Y Name of the table. Prefix for properties that refer to cells within the table
semicolon N false if true, .csv parser expects single semicolon as separator
skip N 0 Number of lines to skip before processing input data
trim N true if true, leading and trailing blanks of values are trimmed

foreach Element

<foreach table="in" info="import ${in.MachineID} = ${in.Custom4} - ${in.Machine}">

The <foreach> element iterates over a table and executes the enclosed script for each row. Within the body of the foreach element, a row of the data is loaded into properties prefixed with the table name. If the table did not contain a header row, the columns will be named 'column1' to 'column'

Attribute Required Default Value Description
table Y name of the table
info N a message to display per row

script Element

<script language="sql"">
Attribute Required Default Value Description
expectedrowcount N if set and not met by the sql statement, a log message is produced
loglevel N warn level for errors and warnings encountered by the script, can be set to info if errors/warnings are expected
name Y sql must be 'sql'
info N a message to display per script invocation

The element contains the SQL script as inner text, usually within a CDATA section.