How to Use Archer Web Services API with Windows PowerShell

[KB-Sync1]

Article Number

000032488

Applies To

Product(s): Archer
Version(s): All Versions
Primary Deployment: On Premises/AWS Hosted/AWS SaaS

---

Description

Windows PowerShell makes it easy to use the Archer Web Services API when compared to tools like Visual Studio.  Depending on the PowerShell version, it will include common functions, or cmdlets, to perform an action and return a Microsoft.NET object to process further. For more details, check out the Task-Based Guide to PowerShell Cmdlets.

At the bottom of the script, update the Archer Instance variables for Base URL, Instance Name, User Domain, User Name, and Password.
Note: Instance Name is case sensitive.

To login and create a session token, the following code snippet saves the session token to a variable. The User Domain will determine which Web Service method to call.

Function Get-ArcherLogin {
    param( 
        [string] $BaseUrl,
        [string] $InstanceName,
        [string] $UserDomain,
        [string] $Username,
        [string] $Password,
        [string] $CredentialFile 
    )
    $SessionToken = ""
    if ($BaseUrl.EndsWith("/") -eq $false) {
        $BaseUrl += "/"
    }

    try {
        # Prompt user for password.  This helps if user doesn't want to save password in file.
        if (($username -eq "" -or $password -eq "") -and $credentialFile -eq "") {  
            $msg = "Please enter Archer username and password.`r`nIf using a domain user, the format is CORP\username.`r`n`r`n" + 
            "     Base Url: $baseUrl`r`n" + 
            "    Instance: $instanceName"
            $credential = Get-Credential -UserName $username -Message $msg
            if (!$credential) {
                "Credential cancelled"
            }
            $userDomain = $credential.GetNetworkCredential().Domain
            $username = $credential.GetNetworkCredential().UserName
            $password = $credential.GetNetworkCredential().Password
        }
        if ($credentialFile -ne "") {
            # Read password from file.
            $credential = Import-CliXml -Path $credentialFile
            $userDomain = $credential.GetNetworkCredential().Domain
            $username = $credential.GetNetworkCredential().UserName
            $password = $credential.GetNetworkCredential().Password
        }
    }
    catch { 
        #Write-Warning "Unknown exception processing credential file. " $_.Exception.Message
        Write-Host "Unknown exception processing credential file. " $_.Exception.Message -ForegroundColor Red -BackgroundColor Black
    }
    try {
        # Login using Web Services API and create session token.  
        Write-Host "Connecting to $instanceName at $baseUrl"
        $apiUrl = $baseUrl + "/ws/general.asmx"

        $apiUrl = $baseUrl + "/ws/general.asmx?wsdl"
        $ws = New-WebServiceProxy -Uri $apiUrl #-Class General -Namespace webservice -ErrorAction Stop
        #$ws.Timeout = 60000 # milliseconds

        $autoGenNamespace = $ws.GetType().Namespace + '.General'
        $req = New-Object ($autoGenNamespace)  
        $req.Url = $apiUrl + "&ArcherName=$($my.ScriptName)&RunId=$($my.RunId)"
        $req.AllowAutoRedirect = $true
        $req.Timeout = 60000
        $req.UserAgent = $my.ScriptName

        if ($userDomain -eq "") {
            $SessionToken = $req.CreateUserSessionFromInstance($username, $instanceName, $password)
        }
        else {
            $SessionToken = $req.CreateDomainUserSessionFromInstance($username, $instanceName, $password, $userDomain)
        }
        write-host "Session Token  : $SessionToken" -ForegroundColor Yellow

        # Create Archer object to share across all runspaces/threads.
        $archer = [PSCustomObject]@{
            InstanceName   = $instanceName
            Version        = ""
            BaseUrl        = $baseUrl
            ApiBaseUrl     = "/api"
            SessionToken   = $SessionToken
            HeadersAWF     = @{"dsn" = $instanceName; "sectok" = $SessionToken }
            Headers        = @{"Authorization" = "Archer session-id=$SessionToken" }
            OverrideGet    = @{"Authorization" = "Archer session-id=$SessionToken"; "X-Http-Method-Override" = "GET" }
            OverrideDelete = @{"Authorization" = "Archer session-id=$SessionToken"; "X-Http-Method-Override" = "DELETE" }
            # WebSession     = $null
            # Cookies        = $null
            # UserAgent      = ""
        }

        # Get Archer version. Try the /api path first and then /platformapi.
        $apiUrl = $archer.BaseUrl + "api/core/system/applicationinfo/version"
        $ver = ""; $ver = Invoke-RestMethod -UserAgent $my.UserAgent -Method POST -Uri $apiUrl -Headers $archer.OverrideGet -ContentType "application/json"
        if ($ver.IsSuccessful -ne $true) {
            $apiUrl = $archer.BaseUrl + "/platformapi/core/system/applicationinfo/version"
            $ver = Invoke-RestMethod -UserAgent $my.UserAgent -Method POST -Uri $apiUrl -Headers $archer.OverrideGet -ContentType "application/json"
        }
        $archer.version = $ver.RequestedObject.Version
        Write-Host "Archer Version : $($archer.Version)" -ForegroundColor Yellow

        if ([version]$archer.version -ge [version]6.6) { $archer.ApiBaseUrl = "/platformapi" }
    }
    catch {
        if ($_.Exception.Message -Match "Server was unable to process request. --->") {
            $ex = ($_.Exception.Message.split(">")[1]).replace('"', '').Trim() 
            #Write-Warning $ex
            Write-Host $ex -ForegroundColor Red -BackgroundColor Black
        }
        else {
            $ex = "Unknown exception " + 
            $_.ScriptStackTrace + "`n" + 
            $_.Exception.Message + "`n" + 
            $_.Exception.StackTrace
            #Write-Warning "Login failed with unknown exception`n$ex"
            Write-Host "Login failed with unknown exception`n$ex" -ForegroundColor Red -BackgroundColor Black
        }
        $credential = $null; $sessionToken = ""; $userDomain = ""; $username = ""; $password = ""
    }

    # Exit if session token is invalid/blank for one of the instances.
    #if ($null -eq $archer.SessionToken) { if ($Host.Name -eq 'ConsoleHost') { pause }; exit }

    return $archer
}

$archer = Get-ArcherLogin -BaseUrl 'https://web/Archer' -InstanceName 'Archer' -UserDomain 'xxx' -Username 'apiuser' -Password 'ArcherPassword' -CredentialFile "" 


$archer.SessionToken

Here's the code snippet to search for certain fields in a certain application. 

$searchXml = 
    '<SearchReport>
      <PageSize>250</PageSize>
      <DisplayFields>
        <DisplayField name="Name">531</DisplayField>
        <DisplayField name="Company">7471</DisplayField>
      </DisplayFields>
      <Criteria>
        <Keywords></Keywords>
        <ModuleCriteria>
          <Module name="My App">84</Module>
          <IsKeywordModule>false</IsKeywordModule>
        </ModuleCriteria>
      </Criteria>
    </SearchReport>'

$api_url = $archer.baseurl + "/ws/search.asmx"
$ws = New-WebServiceProxy -Uri $api_url -Class Search -Namespace webservice

$page = 1

Do {
    "Page " + $page
    [xml] $xdoc = $ws.ExecuteSearch($archer.sessiontoken, $searchXml, $page)
    $xdoc.InnerXml
    $page++
} While ($xdoc.Records.Record.Count -gt 0)