000032488 - How to use the RSA Archer Web Services API with Windows PowerShell

Document created by RSA Customer Support Employee on Jun 14, 2016Last modified by RSA Customer Support Employee on Apr 21, 2017
Version 5Show Document
  • View in full screen mode

Article Content

Article Number000032488
Applies ToRSA Product Set: Archer

RSA Version/Condition: 5.3.x and higher

Platform: Windows
ResolutionWindows 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.
PowerShell 4.0 (Windows Management Framework 4.0) includes cmdlets for REST and Web Service API calls that simplify these tasks and process the results.  This article focuses on the Web Services API.  PowerShell 4.0 or higher needs to be installed on the computer running the scripts.
Download Windows Management Framework 4.0 here.  NOTE: PowerShell 4.0 can be installed on an Archer Admin's workstation and does not have to be installed on the Archer servers.
After installing PowerShell 4.0 or higher, open the attached script in the Windows PowerShell ISE application.  At the top 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.
$base_url = "http://localhost/Archer"
$instance_name = "Archer"
$user_domain = ""
$username = "apiuser"
$password = "Archer"

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.
try

    $api_url = $base_url + "/ws/general.asmx"
    if ($user_domain -eq "") {
        $ws = New-WebServiceProxy -Uri $api_url -Class General -Namespace webservice -ErrorAction Stop
        $session_token = $ws.CreateUserSessionFromInstance($username, $instance_name, $password)
    }
    else {
        $ws = New-WebServiceProxy -Uri $api_url -Class General -Namespace webservice -ErrorAction Stop
        $session_token = $ws.CreateDomainUserSessionFromInstance($username, $instance_name, $password, $user_domain)
    }
    $session_token
}
catch {
    $session_token = $null
    $_.Exception|Format-List -Force
    exit
}

For any other API calls, the session token is required.  The attached PowerShell script contains sample code using the following Web Service methods: CreateUserSessionFromInstance, CreateDomainUserSessionFromInstance, and ExecuteSearch.  Depending on the Archer version, some methods may not be available.  Please download the Web Services API Guide.
The following code snippet performs a very basic search and pages through the results.
$searchXml = 
    '<SearchReport>
      <PageSize>250</PageSize>
      <DisplayFields>
        <DisplayField name="Name">13867</DisplayField>
        <DisplayField name="Description">13868</DisplayField>
      </DisplayFields>
      <Criteria>
        <Keywords></Keywords>
        <ModuleCriteria>
          <Module name="My App">397</Module>
          <IsKeywordModule>false</IsKeywordModule>
        </ModuleCriteria>
      </Criteria>
    </SearchReport>'
$api_url = $base_url + "/ws/search.asmx"
$ws = New-WebServiceProxy -Uri $api_url -Class Search -Namespace webservice
$page = 1
Do {
    "Page " + $page
    [xml] $xdoc = $ws.ExecuteSearch($session_token, $searchXml, $page)
    $xdoc.InnerXml
    $page++
} While ($xdoc.Records.Record.Count -gt 0)

For more examples of <SearchReport> for the ExecuteSearch method, check out KB 32489: How to search for records using the RSA Archer Web Services API method called ExecuteSearch.
Some of the code snippets in the attached script are commented out using the pound symbol (#) for a single line or comment blocks using <# ... #>.  Deleting the "<" after the section's description will uncomment the whole block for testing.  
NOTE: Some sections contain variables that rely on previous sections.

Outcomes