OctoSAM housekeeping¶

OctoSAM services implement periodic housekeeping tasks.

Per import batch housekeepoing¶

A small housekeeping is performed after each import batch.

Nightly housekeeping¶

Every night, the main housekeeping process runs at a configurable time.

Software update housekeeping¶

The first housekeeping after a software update performs additional actions. This is to ensure that data is re-calculated with the newest version of the software.

Housekeeping settings¶

Housekeeping settings are stored in the ConfigurationInformation table in the database. They can be administrated via the Octopus2 GUI menu Setup - Database - Housekeeping.

Background delete¶

Delete operations can be very complex and use a lot of resources. UI operations usually only mark objects for deletion. The Import Service picks them up and performs deletion in the background. The following settings are available to control this background delete operation.

BackgroundDeleteChunkFullHousekeeping: Max number of delete operations that the import service should perform during a full housekeeping cycle.
BackgroundDeleteChunkInBetween: Max number of delete operations that the import service should perform between import cycles.

Healthcheck¶

OctoSAM periodically performs health check operations and logs the result to the configured logging sink.

HealthCheckErrorAfterDays: Healthcheck failures are logged as Warnings for the configured number of days. If the condition persists for more than the configured days, they are logged as Errors.

History data¶

Settings in this section control the retention time for various history items.

AuditLogHistoryDays: The audit log contains a record of all manual changes made to objects via the OctoSAM web interface.
ConnectedSystemHistoryDays: OctoSAM holds a history record for connections to other systems. This is used for monitoring and diagnostics.
HardwareHistoryDays: Number of days that scanned hardware information should be kept. Currently, only network configuration is historized. This allows to query the database for things such as dynamically assigned IP addresses.
InstallationHistoryDays: Number of days to keep software installation history. Can detect software package installs and uninstalls within this period.
MostFrequentUserHistoryDays: Number of days to calculate the most frequent users and most frequently used machines. If set too large, your user to machine affinity may not reflect the current situation.
ProcessHistoryDays: Number of days to keep the history of scanned processes. This feature generates a huge amount of data.
ScanHistoryDays: Number of days to keep the scan history of users and machines.
VirtualMachineScanHistoryDays: Number of days to keep the virtual machine to host relation history. This data is used to calculate virtual machine mobility which may affect software licensing for some products.

Inventory¶

ImportControlDays: ImportControl is used to detect duplicates and to generate basic statistics about processed scan files.
OrphanedDynamicSignaturesGraceDays: Number of days a Package stays installed after all signatures are removed if the installed status depends only on dynamic signatures.
UnassignedDynamicSignatureGraceDays: Unassigned dynamic signatures not scanned within the configured period will be removed from inventory. This removes one-time executables such as installers.

License¶

LicenseUsageWarningThreshold: Percentage threshold for license usage warning. If the license usage exceeds this percentage, a warning is shown in the user interface. The default value is 98%.

Log¶

LogTableDays: How long to keep log information. This affects multiple logging tables that do not directly influence the behaviour of OctoSAM. These tables are usually meant for monitoring and troubleshooting.

Mail¶

MailQueueErrorItemsRetentionDays: Number of days, mails with a delivery error status should be kept in the queue.
MailQueueSentItemsRetentionDays: Number of days that delivered mails should be kept in the queue.

Metering data¶

CloudLicensingHistoryDays: Retention time for software usage and license history from cloud providers.
ConsolidatedCalculateUsageDays: Number of days to calculate consolidated metering data, affects query performance. This data is calculated during housekeeping. Setting it to a shorter period than UsageMeteringDays does not delete any data, but restricts most usage queries on the specified period.
UsageMeteringDays: Number of days to keep usage metering information.

Printable names¶

PrintableNamesUseMachineDescription: A boolean flag if the PrintableName attribute of the Machine object should contain the Description attribute from Active Directory. Some sites use the Description property in AD to encode site-specific configuration information which should not be displayed.

Statistics¶

StatisticsDays: Number of days to keep statistics and project progress information in the database.

Housekeeping actions¶

The housekeeping process consists of a number of actions. Each action can be enabled or disabled in appsettings.json. However, the standard configuration is recommended. Do not disable housekeeping actions without consulting Octosoft first.

Housekeeping scripts¶

The import service provides several hooks to implement custom SQL and/or OctoUtil scripts. Such scripts can help integrate with other systems or to transform custom data within the database.

Support notice

The script and query engines in OctoSAM Inventory and the query definition format may change with future versions of OctoSAM Inventory. We try to keep the engines backward compatible with older versions, but that may not always be possible. Be prepared to adjust your site-specific scripts when updating to a newer versions of OctoSAM.

Administering scripts¶

The scripts can be modified using the OctoSAM GUI, menu: Setup - Database - Housekeeping - Scripts

<housekeeping>
  <!-- Site-specific housekeeping scripts; do not change without consulting Octosoft support first. -->
  <scripts>
    <script language="SQL" name="MyScript" run="before">
        .... SQL Commands ....
    </script>
    <script language="SQL" name="MyOtherScript" run="after">
         .... SQL Commands ....
    </script>
    <script language="OctoUtil" name="MyExportScript" run="export">
         .... OctoUtil Commands ....
    </script>

  </scripts>
</housekeeping>

Script elements¶

script¶

<script name="myscript" language="SQL" run="before" />

The <script> element defines a script

Attribute	Required	Default Value	Description
language	Y		either `SQL` or `OctoUtil`
run	Y		When to run the script - see table below
name	Y		Name of the script. Use the name to identify the script in log and error messages
markdelete	N		If set to either `user` or `machine` the script is expected to select the ID (primary key) of User or Machine records to mark for deletion.
updatehints	N	`false`	If set to `true` causes OctoSAM to update the hints fields before the script is run. Set this to true if your SQL references any hint fields.
days	N		Specify comma-separated list of days when the script can run one or more out of "Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday"
scalar	N	`false`	if true, the script returns a numeric value as ReturnValue.
conditional	N	`false`	if true, the script runs only if the script before is successful and returns a 0 ReturnValue. This allows for example to run OctoUtil commands only if the prior SQL script returned 0.

The run attribute defines when the script will be executed.

Run	Description
before	Run this script at the very beginning of a housekeeping cycle - run at the beginning of full and partial housekeeping cycles.
after	Run this script at the end of housekeeping but before Organization mapping - full and partial housekeeping cycles.
export	Run this script at the very end of a full housekeeping cycle. This is usually the best option for scripts that export data and should run once per day.
beforeImport	Run this script at the beginning of an import batch.
afterImport	Run this script at the end of an import batch. This is usually the best option for scripts that transform data that is used for organization mapping.

Multiple scripts with the same run attribute are executed in the order they are defined in the file.

SQL scripts¶

Can be used to execute arbitrary Transact SQL commands. Use extreme care not to destroy data. Typical use is to transform site-specific data within the database, often in the context of organization mapping or software installation approval.

OctoUtil script¶

Allows to execute OctoUtil commands - especially the execute and the query commands in sync with the import service. This guarantees that the database is in a consistent state when the commands are executed.

Script user context

Note that the housekeeping scripts execute in the context of the service account, which might have different permissions from your interactive user.

Consider the OctoUtil run command as an alternative to the Windows Task Scheduler

The octoutil run command can be used to start external programs from housekeeping scripts. This can be used as an alternative to scheduled tasks with the added benefit that actions get logged to the OctoSAM import service log.

Conditional scripts¶

The parameters scalar and conditional allow to run a script dependant on the result of a prior script.

  <!-- define scalar true and return a scalar numeric value from the query -->
  <script language="SQL" scalar="true" run="before">
      select count(*) from Machine
  </script>
  <!-- the next script depends on the return value of the query, if the return value is 0 then the OctoUtil script will be executed -->
  <script language="OctoUtil" conditional="true" run="before">
      mail message octoadmin@acme.com "There are no Machine records in the database"
  </script>

Mark delete scripts¶

Due to the complex relations of OctoSAM database entities, it is not advised to delete any records directly in the database using SQL. For Machine, User, SoftwareSignature entities, you can make use of the background delete mechanism. To schedule a background delete, set the entities ObjectStateID to "MARKED". The delete operation will be performed by the import service through its database access layer. Deletes are performed when there are no other updates happening. This helps to prevent locks in the database.

Delete operations are expensive not only because of database engine mechanics but also because of the high number of relations to other entities. Delete time also depends on the set history retention times in Housekeeping settings.

You can now set the markdelete attribute on SQL scripts. If set, the sql script is expected to be a query that returns the ID (primary key) of Machines or Users that should be marked for deletion. This allows for much simpler SQL code that is also easy to test.

<script language="SQL" markdelete="machine">

  select ID from Machine where ....

</script>

Adhere to defined script conventions

The select command must return the primary key of the Machine or User object in the first column and that column needs to be named 'ID'. If these conventions are not followed, the script will not run.

Plan reorganization scripts defensively

Do not rely solely on information replicated from connected systems such as ActiveDirectory, ServiceNow, or EntraID. A problem with the connected system might lead to invalid data in the database. It's highly recommended that you always add at least one condition that is based on the core OctoSAM functionality, such as LastScan of the object. Always add criteria that are time based, so that problems with connected systems or possibly bugs in OctoSAM do not lead to an immediate total loss of your inventory data.

Testing scripts¶

You can use the OctoUtil scripts command to execute defined scripts. But be aware that scripts running from the Import Service usually run in a Service Account security context.