Thisexampledemonstratesusingtheapostropheasanescapecharacter.TheLocationNameofSAGHCampus-'88 Bldg contains an apostrophe which is parsed by the REST API and so it must be escaped with an apostrophe (')sothesearchqueryexecutessuccessfully.
=======
.EXAMPLE
Search-ISMBusinessObject-BusinessObjectcis-Filter"name eq 'IL GEM 4000 2 SAGH'"-RawFilter
[switch]$RawFilter,#// Switch to pass the filter value literally. This accounts for scenarios where the default -filter parsing fails/doesn't work. Primary differences include no hyphen prefix for Operators and wrapping the value in single quotes for most values (but not all! If your query is failing, try wrapping the value in single quotes and try again without.)
[Parameter(HelpMessage="Optional hidden parameter that will output additional information useful for debugging the function.",
Mandatory=$false,
DontShow)]
[switch]$Testing,
[Parameter(HelpMessage="Optional hidden parameter that can be used to ouput additional information.",
#Trim any whitespace from the beginning and end of the submitted filter query.
$Filter=$Filter.trim()
#Split out the provided filter on the spaces.
$FilterSplit=($Filter-split'(?= )').trim()
#Parse the array. We can tell the Property Names and Operators apart from the values by querying for the metadata and comparing the operators to the supported operators.
$i=0
$SplitArray=@()
Foreach($Splitin$FilterSplit){
$SplitObj=[PSCustomObject]@{
Split=$Split
Type =$null
NextSplit=$null
SplitQuoted=$null
SplitOpenQuote=$null
SplitCloseQuote=$null
Count=$i
ValidBOProperty=$false
}
if($Split-in$ValidOperators){
$SplitObj.Split=$SplitObj.Split.Replace("-","")
$SplitObj.Type ="Operator"
$SplitObj.NextSplit="Value"
}elseif($SplitObj.Split-in$BOMetaDataProperties){
$SplitObj.ValidBOProperty=$true
$SplitObj.Type ="Property"
$SplitObj.NextSplit="Operator"
}else{
$SplitObj.Type ="Value"
$SplitObj.NextSplit="Unknown"
}
$SplitObj.SplitQuoted="'"+$SplitObj.Split+"'"
$SplitObj.SplitOpenQuote="'"+$SplitObj.Split
$SplitObj.SplitCloseQuote=$SplitObj.Split+"'"
$SplitArray+=$SplitObj
$i++
}
## Removed on 8/15/22 to ensure the fallback to the raw filter functionality works
# if ("Operator" -notin $SplitArray.Type){
# Write-host "Your filter query appears to have no valid operators. Operators must be formatted with a preceding hyphen and be in the list of valid operators: $($ValidOperators -join ", ")`n`nExample: ""LoginID -eq $($ENV:Username)""`nExample: ""CreatedDateTime -lt 2022-01-24T23:42:48Z""`n`nIf your filter query is correct as formatted, please use the -RawFilter switch to query the API with your literal query string." -ForegroundColor yellow
# $ValidSyntax = $false
# }
# Build the filter string based on the Type derived.
$FilterStringQuoted=@()
$FilterStringUnquoted=@()
$i=0
foreach($Splitin$SplitArray){
#Add the raw value of the Split to the unquoted filter string.
$PropertyHelperMsg="`nPerhaps one of these matching fields is what you're looking for:`n$($PropertyHelper.Name-join"`n")`n"
}
Write-Host"The ""$($FilterSplit[0])"" property provided does not appear to be a valid property name on the $BusinessObject BusinessObject!`n$PropertyHelperMsg`nTo see a list of ALL valid properties run the following command:`n`nGet-ISMBusinessObject -BusinessObject $BusinessObject -PropertyList"-ForegroundColoryellow
# if ($DetailedOutput){
# # Write-Host "The ""$($FilterSplit[0])"" property provided does not appear to be a valid property name on the $BusinessObject BusinessObject!`n`n$BusinessObject has the following properties available:
# Write-Host "The ""$($FilterSplit[0])"" property provided does not appear to be a valid property name on the $BusinessObject BusinessObject!`n`nTo see a list of valid properties run the following command:`n`nGet-ISMBusinessObject -BusinessObject $BusinessObject -PropertyList" -ForegroundColor yellow
# }
}
}#End Else-if No -RawFilter Switch
}#END BEGIN
PROCESS{
if($ValidSyntax){
#Initialize the results array.
$Results=@()
#Iterate through every encoded filter until we get results. This is to account for the various ways in which the API will fail to parse the filter query.
Foreach($FilterEncodein$FilterEncodes.Keys){
if($Testing){
Write-Host"Testing with $FilterEncode!"-foregroundcoloryellow
#If there's no SkipQuery but we have more results than the original queried @odata.count we won't bother with a warning. This can occur when looping through records when a new record is created during the loop.
Write-Warning"Failed query for $BusinessObject! (Skip: $Skip | Total: $($Query.'@odata.count'))"
