RG017 – Automation Manager Tips & Tricks

By Max Ranzau

 

Updated Jan 8th 2012 – Annotations in red below

An article on all the neat stuff you can do behind the scenes with RES Automation Manager has been long overdue. This collection of tips and tricks for RES Automation Manager have been gathered from the product help files, administrative guide, release notes and other publicly available sources. There are several topics covered in this article, specifically:

  • How to enable debugging mode in RES Automation Manager
  • How to set the maximum connections on the Dispatcher
  • How to change the path of the Dispatcher’s resource cache.
  • How to change the port of the Dispatcher
  • How to setup Master Dispatchers
  • Using the $workspace tag in Automation Manager
  • Scheduling Automation Manager jobs from the commandline
  • Automation Manager Agent installation parameters
  • Configuring environment variables to remain untranslated
  • DB creation during an unattended installation of RES Automation Manager
  • The Automation Manager @REPLACE function
  • New input options for parameters
  • Prepared4Embedded: New method for using Agents in an image
  • Dealing with console lockout

Okay, here we go:

How to enable debugging mode in RES Automation Manager

To facilitate debugging on what’s going on in the Automation Manager environment, you can enable debugging mode on the agents. This is the procedure is the same for both the Dispatcher and the Agents. Note: This works for RES Automation Manager series 5 and up. Add the following registry values:

Registry key: HKEY_LOCAL_MACHINE\SOFTWARE\RES\Automation Manager
Value Name: Trace
Data Type: REG_SZ (String Value)
Value Data: (Yes = enabled, No = disabled)
Registry key: HKEY_LOCAL_MACHINE\SOFTWARE\RES\Automation Manager
Value Name: TraceDetailed
Data Type: REG_SZ (String Value)
Value Data: (Yes = enabled, No = disabled)
System Key: [HKEY_LOCAL_MACHINE\SOFTWARE\RES\Automation Manager]
Value Name: TraceFile
Data Type: REG_SZ (String Value)
Value Data: <path_to_logfile><filename>

Please note the following:

  • This reghack can be applied to both an Agent and a Dispatcher
  • The file will always be 2 MB. Older lines will be overwritten within the file. If the trace is running for a longer period the file should be copied on a regular basis.
  • A dispatcher that is moderately used can fill up the 2 MB in a matter of minutes.
  • The bottom line in the file is not necessarily the latest entry.

 

How to set the maximum connections on the Dispatcher

Notice: With Automation Manager 2012 this setting is obsolete, as the Dispatcher+ now supports 1500 concurrent Agent connections. Second, the need to use this option has been eliminated in Automation Manager 2009, because we no longer keep all connections open. In real life, it would take about 1000 agents to get to the hardcoded maximum. What needs to be mentioned is that the current maximum is 150 agents so this setting is only effective if you specify a value over 150. Recently, we have noticed that 150 concurrent connections is actually too much for a dispatcher machine, so in fact this setting is not really usable anymore.

The registry value will let you override the number of max connections that a given 2009 Dispatcher will accept. The key (which does not exist per default) is:

Key: HKLM\Software\RES\Automation ManagerValue: DispatcherMaxConnections Data Type: REG_DWORD

Careful with this one! Out of the box, the Automation Manager 2009 Dispatcher is pretty smart and will work out how many connections it safely can handle. If you for some reason disagree with this, it can be changed. This is at your own peril however. Don’t mess with it just because you can!

 

How to change the path of the Dispatcher’s resource cache.

This is necessary to do if you expectr your C: drive on the dispatcher won’t have enough space to store all cached resources. Stop the dispatcher service and create or edit the following registry entry:

Key: HKLM\SOFTWARE\RES\AutomationManager\Dispatcher
Value Name: ResourceCachePath
Data Type: REG_SZ (String Value)
Value Data: Local Path to Dispatcher resource folder

Afterwards, start the Dispatcher service again.

 

How to change the default port of the Dispatcher

This is a good best practice to implement if you are implementing Master Dispatchers. Changing the default port will prevent agents from attempting to attach to Master Dispatchers, which only other dispatchers should connect to.

HKLM\SOFTWARE\RES\AutomationManager\Dispatcher
ValueName: DispatcherPort
Data Type: REG_DWORD
Value Data: Port number

Remember to restart the Dispatcher service after implementing these settings. Be sure to also check article RG043 for more info on Master Dispatchers.

 

How to configure regular dispatchers to point to a Master Dispatcher

With the registry setting MasterCacheDispatcherList, you can specify on a Dispatcher to which Master Dispatcher(s) it should be redirected to, when downloading Resources. If you specify multiple Master Dispatchers, the next master Dispatcher in the list will be used if a certain master Dispatcher is offline or for other reasons unavailable. To redirect a Dispatcher to a master Dispatcher, set the following registry value on this Dispatcher:

Key: HKLM\SOFTWARE\RES\AutomationManager\Dispatcher
ValueName: MasterCacheDispatcherList
DataType: REG_SZ
ValueData: IP address or FQDN of the Master Dispatcher.

Be sure to also check article RG043 for more info on Master Dispatchers. Note: Separate multiple Dispatchers in the string above using a semicolon (;) If you have specified a different port on the Master Dispatcher, you also need to specify this port on each Dispatcher that is redirected to the Master Dispatcher. To redirect the other dispatchers, set the following registry setting on each slaved Dispatcher:

Key: HKLM\SOFTWARE\RES\AutomationManager\Dispatcher
Value Name: MasterCacheDispatcherPort
Data Type: REG_DWORD
Value Data: Port number of the master Dispatcher


Using the $workspace tag in Automation Manager

This one’s really a lifesaver. Imagine that you want to use some files in an Execute command task. Using what we know so far, we would probably create a Download Resource task first, so we are sure we have the stuff we need locally on the target machine before we begin. Instead it is possible to directly reference the Global Uniquie Identifier of the ressource in the commandline without worrying about downloading it and where it physically is downloaded to. Automation Manager will take care of it.

Let’s say we want to execute this command: sysocmgr.exe /open:datafile.dat

The important thing to note is that the sysocmgr.exe in this example is a local executable already in place in the OS. What we would do different in this example, is to:

  • go to the resource for the file datafile.dat
  • mark and copy the GUID. Lets assume it is {66A0E2A2-BCE2-475C-B988-BED6A1306657}
  • Create the task for executing the command. The command line would then look like this: sysocmgr.exe /open:$workspace{66A0E2A2-BCE2-475C-B988-BED6A1306657}

That way you avoid adding a download task to the module.

Another example would be that you need a specific exefile to run on the target machine. If you have already uploaded that .exe file as a Automation Manager ressource, you can just enter $workspace{GUID-OF-THE-APP} in the command line field of the task.

Remember, you don’t have to type the GUID’s. Just go to the properties of the object (module, agent, etc) and copy the guid from the dialog box. Also, you can just rightclick in the fields which supports using a resource tag. This will allow you to browse the ressource catalog and add the proper workspace tag.

Scheduling Automation Manager jobs from the commandline

You can make your own custom shortcuts into the Automation Manager environment by using parameters of the wmc.exe which is the console. So instead of giving certain low-access helpdesk users a Automation Manager console as such, you can just define an icon on their desktop to run a given runbook. You can schedule a job unattended by running the wmc.exe from the command line using the following parameters:

Parameter Value Functionality
/action= schedule Specifies the action, in this case schedule. (Another option is “importbb” to import a Building Block unattended.)
/module=or/project=or/runbook= <GUID> Identifies the Module, Project or Run Book.
/agent=or/team= <GUID> Identifies the Agent or Team.This parameter can be left out for Run Books for which all target Agents or Teams have already been configured.
/user=and/password= <user>and<password> Optional: the RES Automation Manager credentials to access the Console.
/silent   Optional: suppresses any messages.
/onlineagentsonly   Optional: restrict Job to online Agents in a Team only.

Example 1:

“%programfiles%res Automation Managerwmcwmc.exe” /action=schedule /Module={69A0BC21-41F6-46DC-B6DE-5574138EF03C} /team={26E7EB95-35A8-41D3-AED9-FCE71571D6BD} /user=jsmith /password=secret /onlineAgentsonly

The above commandline will run a specific module on the machines which are online in a specific team, authenticating against Automation Manager with credentials jsmith/secret. If windows authentication is being used, the /user and /password parameters are not necessary. A popup will show on the machine where the command is executed to show the module has been scheduled.

Example 2:

“%programfiles%res Automation Managerwmcwmc.exe” /action=schedule /Module={69A0BC21-41F6-46DC-B6DE-5574138EF03C} /agent={26E7EB95-35A8-41D3-AED9-FCE71571D6BD} /user=jsmith /password=secret /silent /onlineAgentsonly

This commandline will run a module on a specific agent, providing it is online. Authention is as before, however the module will run silent on the machine executing the command.

Automation Manager Agent installation parameters

The following public properties (MSI parameters) are available for RES Automation Manager Agent .msi files, to configure the newly installed component to connect to an existing environment:

SITELICENSE: Specifies the RES Automation Manager Site ID. You can find this in the Licensing node.

DISPATCHERLIST: By default, the Agent will autodetect Dispatchers. To use a fixed list of Dispatchers instead, use this optional property to specify the names or GUIDs of Dispatchers to use. Separate multiple entries with a semi-colon (;).

DISPATCHERAUTODETECTFIRST: If you are using the property DISPATCHERLIST (see above), set the property DISPATCHERAUTODETECTFIRST with the value:

“1” if the Agent should try autodetecting Dispatchers before using the Dispatcher list.

“0” if the Agent should only use the Dispatcher list.

DISPATCHERGETLIST: Specifies whether the Automation Manager Agent should extend its list of Dispatchers by getting lists of Dispatchers from the discovered Dispatcher. Set the value:

“1” if the Agent should try to retrieve more Dispatchers through the discovered Dispatcher.

“0” if the AAgent should not retrieve more Dispatchers through the discovered Dispatcher.

ADDTOTEAM: With this property, the newly installed Agent can be made member of an existing Team. This makes it possible to categorize the new Agent correctly right from the start.  To make the new Agent member of one or more Teams, use this optional Property to specify the names or GUIDs of the Teams. Separate multiple entries with a semi-colon (;). Another option for adding agents to teams is to use the Automation Manager 2009 Team Rules. These make it possible for an agent to automagically join a team depending on rules on that team. The memebership takes place immediatly.

INVOKEPROJECT: To run one or more Projects on the new Agent as soon as it comes online, use this optional Property to specify the GUIDs of the Projects. You can find these GUIDs in the Projects node. Separate multiple entries with a semi-colon (;).

Example:

The site license for your RES Automation Manager environment is “RES-AAAA-BBBB-CCCC-DDDD-EEEE-FFFF-1111-2222”. The Agent must connect to two Dispatchers after it has started, “qa-xptest01” and “qa-w2ktest10”. The Agent is not allowed to use other Dispatchers. After the Agent gets online, it must be member of the Team “Exchange Servers”, and it must run a Project with the following GUID: “{301620AE-B650-4B87-BA02-05B6114E1F83}”. The command line to install this Agent unattended would be:

Msiexec /i “c:res-Automation Manager-Agent-x.x.x.x.msi” SITELICENSE=”RES-AAAA-BBBB-CCCC-DDDD-EEEE-FFFF-1111-2222″ DISPATCHERLIST=”qa-xptest01;qa-w2ktest10″ DISPATCHERGETLIST=”0″ ADDTOTEAM=”Exchange Servers” INVOKEProject=”{301620AE-B650-4B87-BA02-05B6114E1F83}” /qn

Note:  Components (meaning Consoles, Dispatchers and Agents) can also be exported as a preconfigured MSI file. By going to the components node of the Automation Manager console, you can rightclick on either one and save it. A dialog box will prompt you for the parameters which you want to brand into the MSI file.

Configuring environment variables to remain untranslated

Sometimes environment variables should not be translated to their value on a specific Agent, but should remain as variables. If double percentage signs (%) are placed around a variable, the variable is not translated to a value but remains a variable. For example, with double percentage signs, %%WINDIR%% is translated to %WINDIR% and not to C:windows.

Here’s an example scenario: You want to set the userprofile path for all Active Directory users as a variable, like %profilepath%, so that this path can be defined depending on the Operating System: C:WindowsProfiles%username% on Windows 2003 machines, and C:WINNTProfiles%username% on Windows 2000 machines.

To achieve this, first use the Task Set Environment Variables to create the system environment variable %profilepath% with the correct values on Windows 2003 and 2000 machines. Then configure the Task Manage Active Directory User to set %%profilepath%% as the Active Directory Property user profile path for all users.

As a result, all user profile paths in Active Directory are: %profilepath%. Due to this variable, the user profile path is resolved depending on the Operating System under which a user logs on: C:WindowsProfiles%username% or C:WINNTProfiles%username%.

DB creation during an unattended installation of RES Automation Manager

It was previously possible to run an unattended installation of RES Automation Manager, but only if connecting to an existing database.  It is now possible to include the creation of a new MSSQL, ORACLE or MYSQL database in the unattended installation of RES Automation Manager. Furthermore, license files can also be imported during the unattended installation of RES Automation Manager.

Note: Because of the different characteristics of the DB2 database system, it is not possible to create a DB2 database during an unattended RES Automation Manager installation. However, it is possible to connect to an existing one. Public properties for installing RES Automation Manager unattended are as follows:

DBTYPE: Specifies the database type. This can be either MSSQL, DB2, ORACLE or MYSQL.

DBSERVER: Specifies the database server that RES Automation Manager should connect to.

DBNAME: Specifies the database name that RES Automation Manager should connect to.

DBUSER: Specifies the database username that RES Automation Manager should use to connect to the database.

DBPASSWORD: Specifies the database password that RES Automation Manager should use to connect to the database.

DBPROTOCOLENCRYPTION: Specifies whether SQL protocol encryption should be used when connecting to Microsoft SQL Server. Values are “yes” or “no”. Default is “no”.

DBCREATE: Specifies whether a new database should be created using the values above. Values are “yes” or “no” (default is “no”). (Note that a DB2 database cannot be created during an unattended installation.)

DBCREATEUSER: Specifies the database username that should be used to create the new database, e.g. “sa”.

DBCREATEPASSWORD: Specifies the database password that should be used to create the new database.

DBIMPORTLICENSE: Specifies a license file (including full path) to be imported after creating a new database (optional).

Here’s a few examples.

To install RES Automation Manager unattended and to create a new datastore:

Msiexec /i “c:res-Automation Manager-2009.msi” DBSERVER=”SQLSERVER01″ DBNAME=”RESAutomation Manager” DBUSER=”RWUser” DBPASSWORD=”RWUserPassword” DBTYPE=”MSSQL” DBPROTOCOLENCRYPTION=”No” DBCREATE=”Yes” DBCREATEUSER=”SA” DBCREATEPASSWORD=”SAPassword” DBIMPORTLICENSE=”c:program filesres Automation Managerlicensefile.xml” /qn

To install RES Automation Manager unattended and to connect to an existing datastore:

Msiexec /i “c:res-Automation Manager-2009.msi” DBSERVER=”SQLSERVER01″ DBNAME=”RESAutomation Manager” DBUSER=”RWUser” DBPASSWORD=”RWUserPassword” DBTYPE=”MSSQL” DBPROTOCOLENCRYPTION=”No” /qn

The Automation Manager @REPLACE function

It is now possible to use the function @[REPLACE(<expression>, <find>, <replacewith>)] when configuring Tasks, to replace characters in a specific expression with another character. This is for example useful when you want to execute an Active Directory Task to add an e-mail address for a user based on Active Directory properties. Here’s a couple of examples:

Displayname in AD: James T Kirk

Function: @[REPLACE(%d@starfleet.org, ,)]

Result: JamesTKirk@starfleet.org

Displayname in AD: Harley-Davidson

Function: @[REPLACE(%d@yourcompany.com,-,.)

Result: Harley.Davidson@yourcompany.com

New input options for parameters

In Automation Manager 2009, additional input settings are now available for parameters:

  • Request input confirmation: If you select this option, you will be asked an extra time for the parameter, when you schedule the job. This can be usefull for verifying information which you want to be absolutely sure has been entered correctly.
  • Always request input (even if parameter is not used directly) : shows the parameter at the input moment of the parameter, even if it is not used directly in any modules.
  • Parameter value is required (may not be empty): The value of the parameter must  not be empty.
  • Use input mask: creates a restrictive field for text entry. The values that you can enter at the input moment of the parameter are restricted to the specified mask. For example, if you want to show a prompt for a telephone number that is restricted to numeric values only, but the area code should be in between parentheses, you could define your mask as Phone No: (000) 000-0000. This results in the following prompt: Phone No: (___) ___-____, in which only numeric values can be entered.

The following characters are available when defining a mask:

    • 0 – Numeric (0-9)
    • 9 –  Numeric (0-9) or space ( )
    • # – Numeric (0-9) or space ( ) or (+) or (-)
    • L – Alpha (a-Z)
    • ? – Alpha (a-Z) or space ( )
    • A– Alpha numeric (0-9 and a-Z)
    • a – Alpha numeric (0-9 and a-Z) or space ( )
    • H – Hex digit (0-9 and A-F)
    • X – Hex digit (0-9 and A-F) and space ( )
    • & – Any character

Note: The selected input options will be ignored if either

  1. the parameter is a Module parameter and linked to a Project parameter or Run Book parameter, or
  2. the parameter is a Project parameter and linked to a Run Book parameter.

Prepared4Embedded: New method for using Agents in an image

In previous versions of RES Automation Manager, you could use “Prepare Agent for Image” to roll out new Agents that are identical copies of the original Agent. When you install a new Agent by using the image, the new Agent will start automatically and register itself in the Datastore with its new computer name. A drawback of this method is that the Agent in the image must be preconfigured to connect to a specific RES Automation Manager environment. (This is done by the Wizard using the GUID of the RES Automation Manager environment.)

A more generic method is now available to preconfigure the correct RES Automation Manager environment. Instead of relying on the environment identifier of a RES Automation Manager environment, you can now use the name of the RES Automation Manager environment.

This is done by setting the REG_SZ value HKEY_LOCAL_MACHINE\SOFTWARE\RES\Automation Manager\AgentPrepared4Embedded to the RES Automation Manager environment name in the image. Then, when you install a new Agent using the image, the new Agent will automatically start and will look for a RES Automation Manager environment of the given name. If it finds the RES Automation Manager environment, it will register itself in the Datastore and start executing scheduled Jobs. The Automation Manager environment name is configured in the console under Infrastructure | Datastore | Settings | Global Settings. Look for the setting called Environment name

Again one of the support guys at RES has offered some valuable insight for us to share:

“The GUID of the Automation Manager environment is not configured in the Wizard but is already present in the Agent Registry. The only GUID you specify in the Wizard is the one of the Project to be run when the agent comes online. Prepared4Embedded was implemented specifically for the Cranberry Smart Clientdevices, which have the name of the environment to connect to embedded in the image. You can however use this entry to alter the environment to connect it to your database.”

Dealing with console lockout

If access to the RES Automation Manager Console is protected by RES Automation Manager credentials, users can potentially lock themselves  out of the console if they forget their RES Automation Manager credentials.  You can now start the Console using a command line with the parameter /lockedout (e.g. “%programfiles%\RES Automation Manager\WMC\wmc.exe” /lockedout).

If the user can provide the correct database credentials (dbuser and dbpassword), the user’s Windows credentials are added to the default Security Role “Full Access”, so that the legitimate user can get access to the Console again.

Use of the /lockedout method, including failed attempts, is logged in the Audit Trail.

This concludes the first round of Tips and Tricks for Automation Manager. Thanks to all contributers for your input. As soon as a suficcient number of new and interesting things have been collected a new article will be posted. Stay tuned.

7 Comments

  • By Domino1270, February 9, 2009 @ 23:16

    Great info!!! Very nice list of “Easter Eggs”. Has anyone stumbled across the current method of grabbing parts of variables? If, for example, I wish to create a username based on the first initial of the first name and the first five letters of the last name. I think that info would be a nice add to this list.

  • By RESguru, February 10, 2009 @ 21:56

    Hi Domino1270.
    You should be able to do this using the function
    @substring(%variable%,1,1) in Wisdom 2009.

    /TRG

  • By Rene de Goeij, April 26, 2010 @ 12:13

    i was trying to create user in ad with login name i would like to do the following

    cg@substring($[firstname],1,1)@substring($[lastname],1,6)

    to get bv cgjlinsse for Jan Linssen

    but then i get message that i reached 20 characters limit

  • By RESguru, April 27, 2010 @ 15:14

    That sound really odd. If I were you, I would make sure I can replicate the issue, then contact RES Support.

    Cheers,
    Max

  • By Rene de Goeij, April 28, 2010 @ 06:44

    i forgot some brackets
    cg@substring($[firstname],1,1)@substring($[lastname],1,6)

    should be

    cg@[substring]($[firstname],1,1)@[substring]($[lastname],1,6)

  • By Rene de Goeij, April 28, 2010 @ 06:46

    sorry

    cg@[substring($[firstname],1,1)]@[substring($[lastname],1,6)]

  • By Jorgen de Gier, October 14, 2013 @ 14:11

    Powershell tip:
    How to determine if the script is running within RES AM. Handy when debugging in the normal Powershell IDE, without modifying the script.

    if( $host.Name -eq “RESPSHost” )
    {
    $pmFirstName = $[FirstName]
    $pmLastName = $[LastName]
    $pmMiddleName = $[MiddleName]
    }
    else
    {
    $pmFirstName = “Jorgen”
    $pmLastName = “Gier”
    $pmMiddleName = “de”
    }

    $pmFirstName = $pmFirstName.substring(0,1).toupper()+$pmFirstName.substring(1).tolower()
    $pmLastName = $pmLastName.substring(0,1).toupper()+$pmLastName.substring(1).tolower()

Other Links to this Post

RSS feed for comments on this post.

Leave a comment

Comments are welcome as always. Just do the math below. * Time limit is exhausted. Please reload the CAPTCHA.