Observer Cmdlets

Reference for Governor Observer Cmdlets

New-ObservationResult

Synopsis Create a new ObservationResult to report back to the Governor Engine.

Syntax

New-ObservationResult
  [-Table] <string>
  [-PartitionKey] <string>
  [-Observation] <psobject>
  [-ItemId <string>]
  [-ObjectId <string>]
  [-ParentRefs <string[]>]
  [-RelatedRefs <string[]>]
  [-ChildRefs <string[]>]
  [-Message <string>]
  [-Reason <string>]
  [<CommonParameters>]

Examples

Report multiple results for a List Observation Action.

$observations = @[
  @{
    id = "ted.tester"
    username = "Ted Tester"
	}
  @{
    id = "ben.bravo"
    username = "Ben Bravo"
	}
  @{
    id = "cindy.catwalk"
    username = "Cindy Catwalk"
	}
]

foreach ($observation in $observations) {
  New-ObservationResult -Table 'MyObjects' -PartitionKey 'MyPartition' `
    -Observation $observation -ItemId $observation["id"] -Reason "Observed"
}

Report single result for Single-Object Observation Action.

$itemId = $order.Payload["__NativeId"][0]
$objectId = $order.Payload["__GovernedObjectId"]
$username = $order.Payload["username"]

# produce observation for requested user
$observation = @{
  id = "ted.tester"          # must be $itemId
  username = "Ted Tester"    # must be $username
}

New-ObservationResult -Table 'MyObjects' -PartitionKey 'MyPartition' `
    -Observation $observation -ItemId $itemId -ObjectId $objectId -Reason "Observed"

Report parent / child objects

Be aware: values for ParentRefs and ChildRefs must be valid Aliases for the referenced objects

$parentObjectType = "X"
$parentTable = @{ TableName = "MyObjects"; PartitionName = "X" }
$parentObject = @{
  id = "Parent.123"
}
$childObjectType = "Y"
$childTable = @{ TableName = "MyObjects"; PartitionName = "X" }
$childObject = @{
  id = "Child.1782"
}
$grandchildObjectType = "Z"
$grandchildTable = @{ TableName = "MyObjects"; PartitionName = "Z" }
$grandchildObject = @{
  id = "Grandchild.920982"
}

New-ObservationResult ... @parentTable -Observation $parentObject
New-ObservationResult ... @grandchildTable -Observation $grandchildObject
New-ObservationResult ... @childTable -Observation $childObject -ParentRefs "X:Parent.123" -ChildRefs "Z:Grandchild.920982"

New-ObservationError

Synopsis Create a new ObservationError to report back to the Governor Engine.

Syntax

New-ObservationError
	[-ObservationType] <string>
  [-Message] <string>
  [-Reason] <string>
  [[-ItemId] <string>]
  [[-ObjectId] <string>]
  [-Repeat]
  [-Cooldown <int>]
  [<CommonParameters>]

Examples

Report transient observation errors

New-ObservationError -ObservationType "AzureADUser/List" -Reason "AAD connection failed" `
    -Message "Cannot reach Azure Active Directory" -Repeat -Cooldown 300

Report non-transient observation errors

New-ObservationError -ObservationType "AzureADUser/List" -Reason "Login failed" `
    -Message "The credentials you provided are invalid"

Report object observation error

New-ObservationError -ObservationType "AzureADUser/Object" -Reason "AAD connection failed" `
    -Message "Cannot reach Azure Active Directory" -Repeat -Cooldown 300 `
    -ObjectId $Order.Payload["__GovernedObjectId"]