CreateUpdateDevices

Requirements

For ease of use, you need to import the Console-API-Module.

All documentation can also be seen in the API Module.

Included in version 4.4.20

Parameters

Parameter:	Description:
uri	string, optional the address for the web service to be called e.g.: http://coreservername/five9sWS/five9sWS.asmx
pat	string, mandatory the Personal Access Token is a credential used to authenticate with our service
computerData	PSCustomObject arrray, mandatory a list of target devices with Hostname, SerialNumber, MAC, and Custom Inventory
apiConfiguration	PSCustomObject, mandatory allows to change the validation to identify new / existing devices. Here you can set the property that will be the primary identifier this helps you prevent creating duplicate devices an identify devices that you want to update

Device Validators Explanation

Existing Device Validators (EDV) determine how the API searches for an existing device to update. The system checks these identifiers in the order specified. Once a match is found, the device is updated instead of creating a new one.

New Device Validators (NDV) define which fields are required and validated when creating a new device. All specified validations must pass before device creation.

Available Validator Options

Validator	Description	Notes
CiKey	Match by Custom Inventory field	Requires mappedValue to be configured
Mac	Match by MAC address	Must be valid MAC format (e.g., 00:1A:2B:3C:4D:5E)
Hostname	Match by device hostname	Validates Windows hostname format
SerialNumber	Match by hardware serial number	Accepts any non-empty string

PowerShell Examples

Validation Example #1: Update by Serial Number

Use case: Devices tracked primarily by hardware serial numbers

$apiConfiguration = [PSCustomObject]@{
	ExistingDeviceValidations = @("SerialNumber")
	NewDeviceValidations      = @("SerialNumber")
}

Validation Example #2: Update by CI Key (Default)

Use case: Asset management systems where devices have unique CI IDs

$apiConfiguration = [PSCustomObject]@{
	ExistingDeviceValidations = @("CiKey")
	NewDeviceValidations      = @("Hostname", "Mac")
}

Validation Example #3: Fallback Chain (Default)

Use case: Handles recreated/reimaged devices that may have lost CI key assignment

$apiConfiguration = [PSCustomObject]@{
	ExistingDeviceValidations = @("CiKey", "Mac", "Hostname")
	NewDeviceValidations      = @("Hostname", "Mac")
}

Validation Example #4: Strict MAC-based Identification

Use case: Network-based inventory systems

$apiConfiguration = [PSCustomObject]@{
	ExistingDeviceValidations = @("Mac")
	NewDeviceValidations      = @("Mac")
}

Key Points:
• Order matters: Validators are checked in the order specified. First match wins.
• Default behavior: If apiConfiguration is null, the system uses CiKey, Mac, Hostname for existing devices and Hostname, Mac for new devices.
• Field requirement: For new devices, unspecified optional fields are set to empty string; hostname falls back to SerialNumber or MAC if empty.

 

Creating devices with unique SerialNumbers

Import-Module $PSScriptRoot\Console-API-Module.psm1 -Verbose #you need to execute this line once, so that powershell can offer intelliSense support

# Arrange the parameters
$wsdlUrl = "http://coreserver/five9sWS.asmx?wsdl" # web service URL, you need to replace the 'coreserver' with your actual value
$pat = "879067F0F16_YourPatHere_024214A4"
[PSCustomObject[]] $computerData = @(
    [PSCustomObject]@{
        Hostname      = ""
        SerialNumber  = "SNA009"
        MAC           = ""
        CI            = @(
            [PSCustomObject]@{
                Name  = "CI ID"
                Value = "302458"
            }
        )
    }
)
$apiConfiguration = [PSCustomObject]@{
    ExistingDeviceValidations = @("SerialNumber")
    NewDeviceValidations      = @("SerialNumber")
}

# Action
Invoke-CreateUpdateDevices  -uri $wsdlUrl -pat $pat -computerData $computerData2 -apiConfiguration $apiConfiguration

The result from the request will look like this: 

Thank you for using this service

Update Advanced Patch settings

CI = @(
	[PSCustomObject]@{
		Name  = "PatchGroup"
		Value = "Sharepoint Server"
	},
	[PSCustomObject]@{
		Name  = "PatchStep"
		Value = "IT Test"
	},
	[PSCustomObject]@{
		Name  = "User to notify"
		Value = "user@company.com"
	},
	[PSCustomObject]@{
		Name  = "PatchStepFastTrack"
		Value = "IT Test"
	})

Please note that "Pilot Group" and "Pilot Group FastTrack" referred in API as "PatchStep" and "PatchStepFastTrack"