Administration Guide

AlloyScan Synchronization

On this page

An AlloyScan synchronization job imports the devices that AlloyScan has audited into Alloy Navigator as Computer and Hardware records and, as its Import software option allows, the software detected on computers. The job is an Automation Server job and runs on a schedule.

You work with AlloyScan jobs in the Settings App and in the Admin Center. The records a run creates or updates are Computer and Hardware records, which the Web App lists under Configuration Management.

One job imports from one AlloyScan site. To import from several sites, create one job per site, each with its own credentials, its own service actions, and its own record of the audit date its runs have reached.

Before you begin

  • A new database contains no AlloyScan job: there is none until an administrator creates one (see Create or edit a job). An upgraded database may already have AlloyScan jobs, and an administrator may have created some.
  • You need the AlloyScan site's URL and the Client ID and Client Secret of an AlloyScan app registration. The job signs in with this app registration, not with a user account. A site-scoped Client ID is one created in the site's App registrations.

How the job connects to AlloyScan

A job carries three connection values: the site URL, the Client ID, and the Client Secret. All three are required: the job does not run while any of them is empty. You configure no separate sign-in address; the job finds it from the site. A site URL that starts with http:// is used as https://, and a trailing slash is removed.

Depending on the AlloyScan instance, a site URL names the site either as a subdomain, https://<site>.<instance>, or as a path, https://<instance>/<site>.

The job then resolves the site from the sites the credentials can reach:

  • When the credentials reach one site, the job uses that site.
  • When the credentials reach several sites, the site URL must name one of them. Otherwise the run fails with "Cannot determine the AlloyScan site because the provided Client Credentials are global and the specified URL is not a site URL. Specify either a Client ID created in the site's App registrations or a URL containing the site name."
  • When the site URL names a different site from the one the credentials authorize, the run logs a warning and continues against the authorized site. The log adds "Successfully connected to site '<site URL>', which matches the site authorized by the provided client credentials. To connect to a different site, provide the appropriate credentials (Client ID and Client Secret)". Test Connection stops at this point instead.

What one run does

A run works in this order:

  1. Signs in to AlloyScan.
  2. Loads the job's four service actions and checks them.
  3. Reads the audit date the previous run reached.
  4. Loads the conflict resolution rules.
  5. Deletes from AlloyScan the records of devices retired in Alloy Navigator, when the job is set to do so (see Retiring a device).
  6. Imports computers.
  7. Imports hardware.
  8. Deletes from the software catalog the software products that no device has detected and that are not tracked.

The first run reads the whole site. Each later run reads only the devices audited after the newest audit date of the previous run, provided the database already holds the audit data of a computer imported from AlloyScan; otherwise the run reads the whole site again. That date is saved only at the end of a run, so after a run that fails part-way, the next run reads the same devices again.

Device types

The job requests computers and hardware separately from the AlloyScan site. Devices returned in the computer list are imported as Computers; devices in the hardware list are imported as Hardware.

How devices are matched to existing records

  • A computer is matched by the AlloyScan key stored on the record from an earlier run or, for a computer migrated from Alloy Discovery, by its earlier audit ID. Such a match is logged as "Matched computer by integration key". When neither matches, the conflict resolution rules are tried (see Audit Conflict Policy).
  • A hardware device is matched by its AlloyScan key, then by serial number, then by name, ignoring case. The first match wins. No rules are used for hardware.
  • A matched device whose record already holds the same or a later audit date is skipped in this run. For a computer, this applies only when it was matched in one of the two ways above, by its AlloyScan key or by its earlier audit ID, not when a rule matched it.
  • A matched device that is retired is logged and left unchanged, computers and hardware alike.

Retired, on this page, means the platform status that marks a Computer or Hardware record as inactive, whatever its label. In a new database created with the Default Workflow (see Default Workflow Configuration), that status is labeled Retired.

AlloyScan synchronization uses only some conflict resolution rules: it skips manual rules, rules that add a new record, and rules that compare the audit ID. It takes the first record any rule returns and never raises an audit conflict (see Inventory Data and Audit Conflicts).

Placeholder serial numbers, such as To Be Filled By O.E.M., N/A, Default string, and 1111TEST1111, are treated as empty before a hardware device is matched by serial number or a rule is evaluated, and before the serial number is passed to a service action as data.serialNumber.

Service actions

The job does not write record fields itself. For each device, it runs the service action set in the matching slot of the job: one for new computers, one for existing computers, one for new hardware, and one for existing hardware (see Workflow Overview). A slot left empty is logged as a warning at the start of the run. The job still runs while at least one slot holds a service action of the kind the slot expects; a job with only the two computer actions imports computers and no hardware. It stops only when none of its slots holds such an action. The service actions supplied with the Default Workflow for these slots, and what they set on a new computer, are listed in Inventory Data and Audit Conflicts.

For each imported computer, the run stores the device's audit data and a link to the device in AlloyScan. It stores neither for hardware.

Discovered software

The software a computer's audit reports arrives with that computer. The run adds unknown manufacturers, platforms, and products to the software catalog, then updates the computer's detected software: it updates changed entries, deletes entries no longer detected, and adds new ones. The computer's license allocations are then recalculated (see License Compliance). Product name, version, publisher, install key, and serial number are shortened to fit their fields. Hardware records get no detected software.

The job's Import software option decides which computers get software:

Choice Effect
For all platforms Software is imported for Windows, Linux, and macOS computers.
For selected platforms only Software is imported for the platforms you select; the detected software of computers on the other platforms is cleared.
Do not import software AlloyScan is asked not to return software, and the detected software of imported computers is cleared.

The platform is the device type's platform. Only AlloyScan's Windows, Linux, and Mac computer types match the three platforms. For a computer whose platform is excluded, the run deletes its detected software and logs that the platform is excluded or that software import is disabled. The dialog notes that only software from groups marked for tracking can be imported.

The software catalog's platform for Mac computers is named macOS. On a database upgraded from an earlier version, the platform named Macintosh is renamed macOS. If that platform had been given another name in your database, it keeps that name, and the first import of Mac software adds a second platform named macOS.

At the end of a run, software products that no device has detected and that are not tracked are deleted from the software catalog, including products that were added by hand.

Retiring a device

The job's retirement option decides what happens in AlloyScan when a Computer or Hardware record is retired in Alloy Navigator:

  • Keep its original record in AlloyScan: the run does nothing in AlloyScan.
  • Delete its original record from AlloyScan: each run finds the retired Computers and Hardware that carry an AlloyScan key, deletes their audit records in AlloyScan, and removes the key from the Alloy Navigator record once AlloyScan confirms.

This step runs before the import, so a device retired in Alloy Navigator is removed from AlloyScan in the same run that would otherwise import it again.

On a database upgraded from an earlier version, the AlloyScan jobs that existed before the upgrade are set to Keep its original record in AlloyScan.

AlloyScan synchronization in the Settings App

In the Settings App, Services > AlloyScan has two pages: Synchronization, the list of AlloyScan jobs, and Logs, the AlloyScan log. Logs > AlloyScan shows the same log, and Services > Automation Server > Job List shows AlloyScan jobs among all other jobs.

Create or edit a job

  1. Go to Services > AlloyScan > Synchronization.
  2. Click New, or select a job and click Open, or double-click it. The AlloyScan dialog opens; an existing job opens on its Settings tab. The dialog has the tabs Settings, Processing, and Sessions; Sessions is unavailable until the job is saved.
  3. On Settings, enter the job name and select or clear Enabled. A new job is named "AlloyScan Synchronization", or "AlloyScan Synchronization (1)", "AlloyScan Synchronization (2)", and so on when that name is taken, and is enabled.
  4. In the AlloyScan Authorization group, enter the Site URL, the Client ID, and the Client Secret. To check them, click Test Connection.
  5. On the same tab, set the schedule. A new job runs every 60 minutes.
  6. On Processing, in the Workflow group, choose the service action for new computers, existing computers, new hardware, and existing hardware.
  7. Under Other tasks, choose what happens when a Computer or Hardware is retired, in When a Computer or Hardware is retired in Alloy Navigator:.
  8. Under Import software, choose For all platforms, For selected platforms only and the platforms, or Do not import software.
  9. Save the job.

When you save, the dialog refuses a job whose site URL, Client ID, or Client Secret is empty. A job with all four service actions empty is saved only after you confirm it. When you changed the connection, the dialog offers to test it first.

An existing job's dialog shows its name in the caption, as "AlloyScan [<name>]".

Process JSON audit data in a service action

Some audit attributes contain JSON collections. To use their contents in workflow operations, map the attribute to a virtual field, then parse its value on the service action's Programming tab. This example uses Monitors (data.monitors) in a Computer service action. Configure the field mapping in the Settings App.

Open the Computer service action selected in the job for new or existing computers. For the action's location and controls, see Service Actions and Field Mappings. Configure both actions if you need to process monitor data when computers are created and when they are updated.

In a new database created with the Default Workflow, these actions are New Computer (AlloyScan) and Update Computer (AlloyScan). An upgraded database need not have these actions, and an administrator may have changed them.

Map the monitor collection

  1. On Field Mapping, click New.
  2. In the Field Mapping window, select Virtual Field.
  3. Enter MonitorCollection as the field name and select String as its type.
  4. Under Service attribute, select Monitors (data.monitors).
  5. Click OK.

The path data.monitors identifies the attribute in the audit JSON. The virtual field receives only the array, starting with [ and ending with ], without the enclosing {"monitors": ...} object.

Convert the JSON array into a collection

  1. On Programming, add a Declare Variable operation.
  2. Name the variable monitorItems and select Script Object as its type.
  3. Set its value using the PowerShell expression below.
$Result = ConvertFrom-Json "%[VIR MonitorCollection]%"

The expression converts the mapped array into a collection of monitor objects stored in monitorItems.

Process each monitor

  1. After Declare Variable, add an Iterate Collection operation.
  2. Under Script object, select monitorItems. The variable holds the array itself, so leave the Collection property box empty.
  3. Keep the proposed iterator name, shown as $monitorItems_Iterator. The operation creates this separate variable for the current monitor; monitorItems remains the collection.
  4. Add operations inside the loop to use the current monitor's properties.

The loop is shown as:

FOREACH $monitorItems_Iterator in $monitorItems

Use the iterator's name followed by a dot and a property name in each placeholder in an operation inside the loop:

Placeholder Value in the current iteration
%[VAR $monitorItems_Iterator.name]% Monitor name
%[VAR $monitorItems_Iterator.resolution]% Monitor resolution
%[VAR $monitorItems_Iterator.serialNumber]% Monitor serial number

If you use a different iterator name, use that name in the placeholders. The iterator is available only inside the loop. See Iterate Collection and Placeholder syntax.

The loop makes each monitor's properties available but does not save monitor information by itself. Use workflow operations inside it to store or otherwise process the values.

Sample audit data

This audit fragment contains two monitors:

{
  "monitors": [
    {
      "displayType": "Unknown",
      "videoInputType": "Analog",
      "name": "Generic Non-PnP Monitor",
      "resolution": "0 x 0",
      "horizontalResolutionPx": 0,
      "verticalResolutionPx": 0,
      "maxHorizontalResolutionPx": 0,
      "maxVerticalResolutionPx": 0,
      "refreshRateHz": null,
      "gamma": 0,
      "diagonal": null,
      "manufacturer": "(Standard monitor types)",
      "serialNumber": null,
      "productCode": "",
      "manufactured": "0, week 0"
    },
    {
      "displayType": "Unknown",
      "videoInputType": "Digital",
      "name": "Digital Flat Panel (640x480 60Hz)",
      "resolution": "1920 x 1080",
      "horizontalResolutionPx": 1920,
      "verticalResolutionPx": 1080,
      "maxHorizontalResolutionPx": 0,
      "maxVerticalResolutionPx": 0,
      "refreshRateHz": null,
      "gamma": 3.55,
      "diagonal": null,
      "manufacturer": "(Standard monitor types)",
      "serialNumber": "1",
      "productCode": "MS_0001",
      "manufactured": "2002, week 0"
    }
  ]
}

The two monitor objects have these name and resolution values:

Monitor Resolution
Generic Non-PnP Monitor 0 x 0
Digital Flat Panel (640x480 60Hz) 1920 x 1080

Run and manage jobs

On the Synchronization page, the toolbar holds Open, New, Delete, Run, Terminate, and Refresh. The right-click menu also has New, Run, Terminate, Enable, Disable, Copy Job ID (GUID) to Clipboard, and Export Selected Settings....

  • Run starts the one selected job at once, whether or not it is enabled, unless the job is already executing or locked. It is available only while the Settings App last read the Automation Server as running. If Run is still unavailable after the Automation Server has started, press F5; it also returns by itself within a minute. A disabled job runs once on Run and stays out of the schedule.
  • When the Settings App cannot reach the Automation Server directly, Run leaves the request for the Automation Server to pick up and says that it may take some time because the Settings App and the Automation Server are on separate computers, and to check the session log once the job has completed. Any other failure shows "Cannot send request to the Automation Server. Make sure the Automation Server is configured and started."
  • Enable and Disable act on every selected job. The Automation Server runs only enabled jobs on their schedule, and a disabled job has no next run date.
  • Delete deletes every selected job after "Are you sure you want to delete the selected item?"
  • Refresh, also F5, reloads the list and reads the Automation Server's status again. While the list is on screen, it also reloads changed rows every ten seconds by default.

The same Run is on Services > Automation Server > Job List for the job selected there.

Check the results

The AlloyScan log, under Services > AlloyScan > Logs or Logs

AlloyScan, lists the runs of all AlloyScan jobs. The job dialog's Sessions tab lists the job's own runs. For each run, the log shows the run date, the job name, the comments, the duration, and the numbers of created computers, created hardware, updated computers, updated hardware, and errors.

In a new database created with the Default Workflow, the AlloyScan log and the Sessions tab offer the views All Time, Last 7 days, Errors, and by Job Name. Each lists the newest run first, so the top row of the Sessions tab is the job's most recent run; by Job Name also groups the runs by job name.

  • View Log opens the run's text.
  • Delete deletes the selected runs. It is shown unless the log is read-only.
  • Clear All deletes all runs of the AlloyScan log, or only the job's runs on its Sessions tab.
  • Settings... sets how many days the AlloyScan log's records are kept; this does not change the other logs. Without the permission to manage logs, it shows "You do not have enough permissions to use this function." The Sessions tab has no Settings....
  • Refresh, also F5, reloads the log. While the log is on screen, it also reloads on the same interval as the job list.

For logs in general, see Logs.

AlloyScan synchronization in the Admin Center

In the Admin Center, go to Services and Integrations > AlloyScan. The page is available to users who hold its permission (see Permissions Reference). It has the tabs Synchronization, which opens by default, and Logs. The Logs group of the Admin Center also has its own AlloyScan entry.

The Synchronization tab lists the AlloyScan jobs, with Edit, Delete, Enable, Disable, Run, and Terminate on its toolbar.

  • Run needs one selected job and an active Automation Server. It queues the job, enabled or not, and shows "Your job will be started as soon as possible, typically within a few minutes. Please check the job status later." If the job is already waiting to run, Run shows "Please wait until the job has completed, and then check the session log to make sure that it runs as expected." and refreshes the list.
  • Terminate needs one selected job, an active Automation Server, and a job whose last run is executing. If the job is already being terminated, it shows "Please wait, the job will be terminated soon." and refreshes the list.
  • Enable and Disable act on the selected jobs.
  • Edit needs one selected job.
  • While the list is loading, these actions are unavailable.
  • To open a job, double-click its row, click Edit, or click the job's name. The job opens in a drawer on its Settings tab, followed by Processing and Sessions. A new job's form is titled "New Synchronization" and has no Sessions tab.

The Next Run column shows whether a job is waiting to run as soon as possible, being terminated, disabled, or not yet started, before it shows a date.

Imported records in the Web App

In the Web App, imported computers and hardware are listed under Configuration Management > Computers and Hardware. For these records in the Web App, see Inventory Data and Audit Conflicts.

On the default Computer form, the Configuration tab holds the Operating System, CPU, HDD & RAM, Virtualization, Network, User Activity, Audit Information, Display, and IP Addresses groups. Audit Information holds the audit date and the Show audit information button. For a computer imported from AlloyScan, the button opens the device's audit data in AlloyScan's audit viewer, in a new browser tab. The Software tab holds Discovered Installations and Allocated Licenses.

On the default Hardware form, the Configuration tab holds the network, the audit date, and the IP Addresses list.