PowerShell

Using the SolarWinds Information Service from PowerShell

The Orion SDK includes a snapin for Windows PowerShell in SwisPowerShell.dll. The default location for this file is Installation Folder\SolarWinds\Orion SDK\SWQL Studio. The Orion SDK installer automatically registers this snapin for 32-bit PowerShell and, on 64-bit systems, 64-bit PowerShell.

Using SwisSnapin

After installing SwisPowerShell.dll, use the following steps to run a query from PowerShell:

1. Start Windows PowerShell.
2. Run the command, Add-PSSnapin SwisSnapin to load SwisSnapin into the current PowerShell runspace.
3. Run the command, $swis = Connect-Swis, and then provide your Orion credentials.
4. Run the command, Get-SwisData $swis 'SELECT NodeID, Caption FROM Orion.Nodes'. SWIS returns the results in PowerShell.

In PowerShell terms, the results from Step 4 are returned as a set of objects with two properties: NodeID and Caption. So you can manipulate them using the standard PowerShell syntax and commands. For example, use Get-SwisData $swis 'SELECT NodeID, Caption FROM Orion.Nodes' | Export-Csv nodes.csv to create a CSV file from the query results.

Cmdlets Provided by SwisSnapin

SwisSnapin provides the following PowerShell cmdlets.

Connect-Swis

Arguments:

• Hostname (optional, defaults to localhost)
• V2 (optional, opens a connection to SWISv2 instead of default SWISv3)
• An authentication option. One of:
  • Credential (a PSCredential object)
  • Username and Password (strings)
  • Trusted (uses the current Windows token for authentication)
  • Certificate (uses the local Orion server certificate. This will only work when running SwisSnapin on an Orion server)

This returns a SWIS connection object. For example:

$creds = Get-Credential  # display a window asking for credentials
$swis = Connect-Swis –Credential $creds –Hostname localhost  # create a SWIS connection object

Get-SwisData

Takes three arguments:

• SwisConnection (mandatory)
• Query (mandatory)
• Parameters (optional)

This returns a set of PowerShell objects representing the query results. The Parameters argument can be used to supply the values of query parameters. For example:

Get-SwisData $swis 'SELECT NodeID, Caption FROM Orion.Nodes WHERE Vendor=@v' @{v='Cisco'}

When building a PowerShell script that runs SWIS queries, it can be helpful to supply the values of filters and other things using query parameters, as this avoids the need to deal with encoding embedded quote characters and other syntactical issues.

Invoke-SwisVerb

Takes four arguments, all mandatory:

• SwisConnection
• EntityName
• Verb
• Arguments

For example:

$now=[DateTime]::UtcNow
$later=$now.AddDays(1)
Invoke-SwisVerb $swis Orion.Nodes Unmanage @("N:1",$now,$later,"false")

Returns an XmlElement object representing the complete response from the verb.

New-SwisObject

Invokes the Create operation from the CRUD Operations interface and takes three arguments:

• SwisConnection (mandatory)
• EntityType (mandatory)
• Properties (mandatory)

EntityType indicates the entity type to be created. The Properties argument accepts a hash table object containing property/value pairs with which to initialize the new entity’s properties. This returns a URI string for an entity that has been newly created and can be used as the Uri argument of the other CRUD operations. For example:

New-SwisObject $swis –EntityType 'Orion.Pollers' -Properties @{PollerType='N.Details.SNMP.Generic';NetObject='N:1';NetObjectType='N';NetObjectID=1}

Get-SwisObject

Invokes the Read operation from the CRUD Operations interface and takes two arguments:

• SwisConnection (mandatory)
• Uri (mandatory)

Uri identifies the entity of which you want to read the properties. This returns a hash table object containing property/value pairs corresponding to the current state of the entity property values. For example:

Get-SwisObject $swis –Uri 'swis://localhost/Orion/Orion.Nodes/NodeID=1/CustomProperties'

Note: The Read operation provides an alternative to the query operation.

Set-SwisObject

Invokes the Update operation of the CRUD Operations interface and takes three arguments:

• SwisConnection (mandatory)
• Uri (mandatory, but can be provided from the pipeline)
• Properties (mandatory)

Uri identifies the entity you are about to change. The Properties argument accepts a hash table object containing property/value pairs to set in the entity. For example:

Set-SwisObject $swis –Uri 'swis://localhost/Orion/Orion.Nodes/NodeID=1' -Properties @{Caption='New Name'}

To set properties to the same values on multiple objects at the same time, omit the Uri argument and instead, pass the Uri for each entity you want to modify through the PowerShell pipeline. These Uri values can come from a Get-SwisData query or just a list of strings:

# Example passing a list of strings
$uris = @('swis://localhost/Orion/Orion.Nodes/NodeID=3', 'swis://localhost/Orion/Orion.Nodes/NodeID=5', 'swis://localhost/Orion/Orion.Nodes/NodeID=7')
$uris | Set-SwisObject $swis -Properties @{PollInterval=300}

# Example passing Uris from a query
Get-SwisData $swis 'SELECT Uri FROM Orion.Nodes WHERE PollInterval=300' | Set-SwisObject $swis –Properties @{PollInterval=120}

Remove-SwisObject

Invokes the Delete operation of the CRUD Operations interface and takes two arguments:

• SwisConnection (mandatory)
• Uri (mandatory, but can be provided from the pipeline)

Uri identifies an entity to remove. For example:

Remove-SwisObject $swis –Uri 'swis://localhost/Orion/Orion.Pollers/PollerID=1'

Remove-SwisObject also supports deleting multiple objects in one operation by omitting the Uri argument and passing the Uri values through the PowerShell pipeline. See Set-SwisObject for some examples of how to do this.