RES Software is one of the key players in the User Environment Management world.

RESSoftware

One of the components in their RES Suite is RES Automation Manager (RESAM). This component of the suite is primarily used to automate day-to-day tasks in an IT environment.

The management of the RESAM component is done through a GUI. But the component also provides a REST interface. To provide an easy way to interact with RESAM from PowerShell, I decided to write a module that used this REST interface.

The reasoning behind the creation of this PowerShell module is that it will allow to interact with RES AM from other environments, more specifically Management and Monitoring tools. The module makes it easier to interact from for example SCCM with RES AM.

The module requires PowerShell v3 or higher.

The following links show how to work with the RESAM module. Note that this is just an introduction to the RESAM module and it’s cmdlets. In the future I plan to post some practical examples of the use of the RESAM module.

Installation

The module is stored on GitHub and is called RESAM.

github-resam

You can download the module from this link, or via the Download ZIP button on the GitHub page.

As an alternative I provide the following script. It will download the ZIP file and install the RESAM module in the user’s module folder.

Once the RESAM module is installed, you can import the module.

RESAM-Import

Each cmdlet in the RESAM module comes with a help page.

RESAM-Help

You can also get this help in a separate window, which makes it easier to refer to the help while editing a script.

RESAM-Help-Window

Connecting

The first cmdlet one would normally use when using the RESAM module is the Test-RESAM cmdlet. This cmdlet takes the hostname of a RES AM dispatcher and the credentials required to connect to the WebAPI interface, and returns a Boolean to indicate whether a connection was made or not.

In you script you can use this for example like this

Once you have tested that the connection to RES AM Dispatcher’s WebAPI is valid, you can start using the other RESAM module cmdlets.

Get Modules

The Get-ResAMModule, Get-ResAMProject and Get-ResAMRunBook cmdlets are quite obvious for what they are used. They allow you to retrieve RES AM Modules, Projects and RunBooks.

In this and the following examples, I will only show the relevant code. The complete code that would be required can be retrieved from the sample in the Connecting section.

This example will return an object for each Module that is defined in RES AM.

RESAM-Get-Module

This is the same list of Modules that you would see in the RES AM Console

RESAM-Gui-Modules

The Get-Module cmdlet also allows you to specify the Name of the Module you want to retrieve. And in the Name parameter value, you can use a RegEx expression to filter the Modules to be returned.

The previous example will return all Modules that have the word Query in their name.

RESAM-Get-Module-RegEx1

And the following example will return the Modules whose name starts with the word Query

RESAM-Get-Module-RegEx2

The Get-ResAMProject and Get-ResAMRunBook cmdlets work in a similar way.

Get Agents

The Get-ResAMAGent cmdlet retrieves the Agents that are present in RES AM.

RESAM-Get-Agent

Again, this corresponds with what you would see in the RES AM Console under Agents

RESAM-AGent

and Teams.

IRESAM-Team

If you would only like to see the Agents and not the Teams, you will have to filter on the Type property. To make it easier, the module comes with a number of enumerations. One of these is the RESAM.JobWhoType enumeration. The code would then become.

RESAM-Agent-Type

If you want to explore the available types that come with the RESAM module, the Intellisense feature comes in handy.

RESAM-Enum

And also to see the enumeration values for a specific type.

RESAM-Enum2

The Get-ResAMAgent cmdlet also supports RegEx expressions on the Agent and AgentName parameter value.

RESAM-Agent-RegEx

In this example, the script asked for all the Agents whose name ends with “1”.

And finally, the Get-ResAMAgent cmdlet provides two switches to filter the returned Agents, the OnlineOnly and the LicensedOnly switches.

RESAM-Agent-Online-Result

The offline Agent is not returned.

RESAM-Agent-Online

Get Jobs

The Get-ResAMJob allows you to get information about the RES AM jobs. In it’s simplest form

the cmdlet returns all the jobs in the RES AM environment for the past 24 hours.

This limitation that the cmdlet by default only returns the jobs for the last day is done because otherwise the cmdlet would return all jobs that ever ran, and then it could take quite some time before the cmdlet returns.

RESAM-Job

The returned object contains a wealth of information. You can for example retrieve all the jobs, when they ran, on which Agents and by whom they were submitted (if available).

The result

RESAM-Job-Result1

If you need more details on the job, specifically how it ran on each of the Agents, you can use the Get-ResAMJobByID cmdlet. See the following example.

RESAM-Job-Result2

Btw, the previous example uses splatting to place the parameters for Get-ResAMJob cmdlet in a hash table.

This section just uses a minimum of what can be done with the Get-ResAMJob and Get-ResAMJobByID cmdlets. Play around with cmdlets, check out the help and discover what information you can find in the returned objects.

Get Module Parameters

To make Modules more dynamic, RES AM has a feature called Module Parameters. These allow you to specify specific parameter values for the tasks in the Module (or Project, or RunBook) at the moment the Module is scheduled.

RESAM-InputParam-GUI

The following example shows how to find Module Parameters

The result

RESAM-InputParam

Note that the cmdlet will only return Module Parameters that are actually used in the Task(s) in the Module.

Schedule a Job

The New-ResAMJob cmdlet allows you to actually schedule Jobs. A simple example

The resulting object

RESAM-NewJob

And the resulting job in the RES AM GUI

RESAM-NewJob-GUI

Abort a Job

Sometimes a Job can be running forever, if you changed the default timeout value. In that case you can use the Stop-ResAMJob cmdlet to abort the Job.

This (artificial) example starts a Job, waits till the Job is Active and then aborts the Job.

RESAM-JobAbort

As you can also see in the GUI.

RESAM-JobAbort-GUI

Get Job Result

The Get-ResAMJobResult allows you to retrieve the output generated by a Task in a Module.

The result

RESAM-JobResult

And in the RES AM GUI

RESAM-JobResultGUI

Since you can now retrieve the result in a PowerShell script it allows you to process the returned information in the script.

 

If you have any feedback, suggestions or usage examples related to this RESAM module, please let me know.

Enjoy !