PSIGEL - New-UMSAPICookie

To make requests to the UMS API you need to authenticate. This is done by getting a session ID and provide it as a cookie header for each of the API requests.
The New-UMSAPICookie functions creates a websession cookie for all API functions. To work it needs the computername of the UMS and the credential of an user able to make a API call.

In the following scenarios i show the usage of the New-UMSAPCookie function as well as basic principles for the usage of credentials and default parameters.

Basic scenario

Create a $WebSession variable for the use with API functions:

$WebSession = New-UMSAPICookie -Computername 'igelrmserver' -Credential (Get-Credential)

Credential handling scenario

If you dont want to provide the credential interactive, especially in automation sceanarios, you can write the credential in a secure way. The credential can only be used on the machine it was created and from the user which created it:

Get-Credential | Export-Clixml -Path ('{0}\igelums@igelrmserver.cred' -f ${env:\userprofile}) -Credential (Get-Credential)

Read the secure credential in to $Credential variable:

$Credential = Import-Clixml -Path ('{0}\igelums@igelrmserver.cred' -f ${env:\userprofile})

Use the $Credential variable:

$WebSession = New-UMSAPICookie -Computername 'igelrmserver' -Credential $Credential

Extended scenario

If you want to use multiple API functions in one script it is recommended to use $PSDefaultParameterValues. This way you can avoid to call recurrent parameter for each function:

$PSDefaultParameterValues = @{
  'New-UMSAPICookie:Credential' = (Import-Clixml -Path ('{0}\igelums@igelrmserver.cred' -f ${env:\userprofile}))
  '*-UMS*:Computername'           = 'igelrmserver'
}
$PSDefaultParameterValues += @{
  '*-UMS*:WebSession' = (New-UMSAPICookie)
}
$Site = 'Augsburg'
$DeviceDirectoryAugsburgId = ((Get-UMSDeviceDirectory).where{$.Name -eq $Site})[0].id
(Get-UMSDevice -Filter details).where{$.ParentId -eq $DeviceDirectoryAugsburgId} |
  Update-UMSDevice -Site $Site

The above script looks for the first occurrence of an device directory with the name “Augsburg” and updates the site property of the devices in this directory to “Augsburg”.

You can find the documentation for New-UMSAPICookie here.

In the next part of the series we will take a look at the Get-UMSDevice function.