Plug-in Documentation

Microsoft Windows System Tools

Overview

Overview

Use the Windows System Tools plug-in to automate various Windows system tasks as part of the deployment process.

Compatibility

This plug-in requires IBM UrbanCode Deploy version 6.0.1 or later.

This plug-in runs on all Windows versions that the IBM UrbanCode Deploy agent supports.

Installation

No special steps are required for installation. See Installing plug-ins in UrbanCode Deploy.

History

Version 23

Adding missing classpath to the Check File Contents step.

Version 22

Lowered the mandatory wait period for Windows 2012 machines using the Reboot step from 1 minute to 30 seconds.
Support property file encryption.

Version 21

This update adds the following functionality to the Create Windows Scheduled Task step:

  • /U, /P, /RU, and /RP parameters have been added as hidden properties.
  • An Additional Arguments parameter has been added as a hidden property.

Version 20

This update adds support for safely shutting down an agent before reboot. Implemented specifically for Windows 2012 machines.

Version 19

Fixed PI38873 WINDOWS SYSTEM TOOLS DOES NOT LOG OFF SESSIONS IN DISCONNECTED STATE

Version 18

Fixed PI32983 WINDOWS SYSTEM TOOLS PLUGIN HAS A SPELLING ERROR (REG_MUTLI_SZ INSTEAD OF REG_MULTI_SZ) IN PLUGIN.XML

Troubleshooting

Windows Server 2012 OS restarts using Reboot step, but fails.

This is a known issue with Windows Server 2012. When the reboot occurs, the agent does not shutdown in a recoverable state. In Version 20 of the Windows System Tools, a new property was added called Agent Service Name. This requires the root user to login to the Windows Server 2012 machine, find the UrbanCode Agent service, copy the Service name, and place it in this property. The default agent name is ibm-urbancode_deploy-agent. This will enable the agent to shutdown correctly and allow recovery on reboot.

Usage

Use the Windows System Tools plug-in to automate a number of systems tools for the Microsoft Windows operating system.

  • Manage Windows features
  • Update the Registry Key
  • Configure Distributed Component Object Model (CDOM) communication properties
  • Work with scheduled tasks
  • Log off notifications and sessions
  • Restart the computer

Step palette

To access this plug-in in the palette, click System Utility > Windows > WindowSystemTools.

Steps

Process steps in the Windows System Tools plug-in

Add Or Overwrite Registry Key

Adds or Overwrites a Key to the Registry

Input properties for the Add Or Overwrite Registry Key step
Name Type Description Required
Force Registry Overwrite Boolean This will overwrite the existing registry key No
Registry Key String Specify the Registry Key (ie HKLM\Software\MyCo) Yes
Registry Value Data String Specifies the Registry Value Data Yes
Registry Value Name String Specify the Registry Value Name Yes
Registry Value Type Enumeration:

  • REG_SZ
  • REG_MULTI_SZ
  • REG_BINARY
  • REG_DWORD_BIG_ENDIAN
  • REG_DWORD
  • REG_DWORD_LITTLE_ENDIAN
  • REG_NONE
  • REG_EXPAND_SZ
Select the data type for the Registry Value Name. Yes

Check File Contents

Check file contents against a regular expression.

Input properties for the Check File Contents step
Name Type Description Required
Directory Offset String The working directory to use when executing this command. This is relative to current
working directory.
No
Fail if a match was found Boolean Check this option to fail the step if a match was found. Default is to fail if a match
is not found.
No
File to scan String The name of the file to scan. Yes
Regular Expression String The regular expression used to scan the file contents. Yes

Configure DCOM Settings

Configure DCOM Settings

Input properties for the Configure DCOM Settings step
Name Type Description Required
Authentication Level Enumeration:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
Select the DCOM Authentication Level Yes
Enable Remote DCOM Boolean This will Enable Remote DCOM No
Impersonation Level Enumeration:

  • 1
  • 2
  • 3
  • 4
Select the DCOM Impersonation Level Yes

Create Message Queues

Create Message Queues

Input properties for the Create Message Queues step
Name Type Description Required
Non-Transactional Queues String A new line separated list of non-transactional message queues to create.
Ex: .\newQueue1 or .\Private$\newPrivateQueue1
No
Transactional Queues String A new line separated list of transactional message queues to create.
Ex: .\newQueue1 or .\Private$\newPrivateQueue1
No

Create Windows Event Log

Creates a new event log and a new event source.

Input properties for the Create Windows Event Log step
Name Type Description Required
Category Resource File String Specifies the path to the file that contains category strings for the source events.
This file is also known as the Category Message File.
No
Log Name String The Name of the event log. Yes
Message Resource File String Specifies the path to the file that contains message formatting strings for the
source events. This file is also known as the Event Message File.
No
Parameter Resource File String Specifies the path to the file that contains strings used for parameter substitutions
in event descriptions. This file is also known as the Parameter Message File.
No
Powershell executable location String The path including the powershell executable unless on the path. No
Sources String A comma separated list of the names of the event log sources, such as
application programs that write to the event log.
Yes

Create Windows Scheduled Task

Creates a new scheduled task for Windows.

Input properties for the Create Windows Scheduled Task step
Name Type Description Required
Day String Day of the week or month to run the task. The wildcard character (*) specifies all
days. Allowed values are MON, TUE, WEB, THU, FRI, SAT, SUN and for monthly schedules
1-31.
No
Duration(HH:mm) String The duration to run the task. This value will be ignored for schedule types that it
is invalid for.
No
End Date(mm/dd/yyyy) String The last date that this schedule should run on. This value will be ignored for schedule
types that it is invalid for.
No
Executable Location String The absolute path to the executable to be run for this task. Yes
Idle Time String Amount of idle time to wait before running the scheduled for ONIDLE type. Valid values
are 1 999 minutes. This value will be ignored for other schedule types.
No
Month String Month for the schedule. The wildcard character (*) specifies all months. No
Schedule Type Enumeration:

  • MINUTE
  • HOURLY
  • DAILY
  • WEEKLY
  • MONTHLY
  • ONCE
  • ONSTART
  • ONLOGON
  • ONIDLE
The type of the schedule to be created. Yes
Start Date(mm/dd/yyyy) String The first date that this schedule should run on. This value will be ignored for schedule
types that it is invalid for.
No
Start Time(HH:mm) String The start time to run the task. This value is required for Once schedule type. No
Task Name String The Name of the scheduled task. Yes
Type Modifier String The modifier to invoke schtasks with. Please refer to your Operating System documentation
for allowed values for the schedule type.
No

Delete Registry Key

Deletes a Key from the Registry

Input properties for the Delete Registry Key step
Name Type Description Required
Fail if not found Boolean Check this box if you want the process to fail if the registry key isnt found. No
Registry Key String Specify the Registry Key (ie HKLM\Software\MyCo). Yes
Registry Value String Specify a single value of a Registry key to delete. No

Delete Scheduled Task

Delete a scheduled task for Windows.

Input properties for the Delete Scheduled Task step
Name Type Description Required
Task Name String The Name of the scheduled task. Yes

Disable Windows Features

Disable specific Windows Features. This only works with Windows 7 family of Windows.

Input properties for the Disable Windows Features step
Name Type Description Required
Additional Options String A comma and/or new-line separated list of additional options to be supplied to
the dism command.
No
Directory Offset String Specify a sub-directory of the current working directory where you want the
command to execute
No
Dism executable location String The path including the dism executable unless on the path. No
Features String A comma and/or new-line separated list of features to disable. Do not include
/featurename:
Yes

Enable Windows Features

Enable specific Windows Features. This only works with Windows 7 family of Windows.

Input properties for the Enable Windows Features step
Name Type Description Required
Additional Options String A comma and/or new-line separated list of additional options to be supplied to
the dism command.
No
Directory Offset String Specify a sub-directory of the current working directory where you want the
command to execute
No
Dism executable location String The path including the dism executable unless on the path. No
Features String A comma and/or new-line separated list of features to enable. Do not include
/featurename:
Yes

End Scheduled Task

End a scheduled task.

Input properties for the End Scheduled Task step
Name Type Description Required
Task Name String The Name of the scheduled task. Yes

Export Registry Subkey to File

Exports registry subkey to a file

Input properties for the Export Registry Subkey to File step
Name Type Description Required
Destination File String Destination file for export (i.e. example.reg, c:/path/to/example.reg) Yes
Force File Overwrite Boolean When enabled, this step will overwrite the destination file if it exists No
Registry Key String Specify the Registry Key to export (ie HKLM\Software\MyCo) Yes

Import Registry Files

Imports a file containg registry keys

Input properties for the Import Registry Files step
Name Type Description Required
Exclude Files String Enter a new line separated set of file filters for the files to exclude from the execution. No
Include Files String Enter a new line separated set of file filters to import intothe registry. Yes
Source Directory String Specify the Source Directory Yes

Log off Notification

Sends a message warning to logged on users to log off

Input properties for the Log off Notification step
Name Type Description Required
Message Text String Specify the message that will be displayed to users logged on to the server Yes
Number of Times to Retry String This determines the amount times the plugin willcheck for logged on users before failing
the deploy
Yes
Server to Query String This specifies the server to query active sessions No
Wait Time Between Retries(Seconds) String This specifies the amout of time to wait between retries Yes
Windows Server Version Enumeration:

  • 2003
  • 2008
Select the server version the plugin will run on Yes

Log off Sessions

Logs off sessions on a server

Input properties for the Log off Sessions step
Name Type Description Required
Number of Times to Retry String This determines the amount times the plugin will check for logged on users before
forcing sessions to log off. Set to 0 if you dont want to
wait.
Yes
Server to Query String This specifies the server to query for sessions. No
Session name filter String Provide a regular expression if you want to filter the sessions affected by this step
by name. Leave blank for all sessions.
No
Session state filter String Provide a regular expression if you want to filter the sessions affected by this step
by their state. Leave blank for all session states.
No
Wait Time Between Retries (seconds) String This specifies the amount of time to wait between retries. Yes

Modify ACLs

Assign ACLs to files or folders.

Input properties for the Modify ACLs step
Name Type Description Required
CACLS Path String The path to the (X)CACLS executable. For example: C:\Windows\System32 No
CACLS Type Enumeration:

  • cacls
  • icacls
  • xcacls
Select whether to use cacls, xcacls, or icacls to modify permissions Yes
Continue on access denied errors Boolean Check this option to continue on access denied errors. Adds /C option. No
Deny user accesss String Deny specified user access. Uses /D option (/deny in ICACLS). If using XCACLS or CACLS,
specify the user. With ICACLS, this denies specified rights to the user, requiring
an input of the form, user:perm
No
Directory Offset String The working directory to use when executing this command. This is relative to current
working directory.
Yes
Edit ACLs instead of replacing Boolean Check this option to edit ACL instead of replacing it. Adds /E option. This option
cannot be used with ICACLS
No
File filter String A file filter to limit the files/folders to modify. Yes
Grant User Access Rights String A list of new line separated permissions in the form of user:perm;spec where
perm can be: R Read C Change (write)
F Full control P Change Permissions
(Special access) O Take Ownership
(Special access) X EXecute (Special
access) E REad (Special access)
W Write (Special access) D Delete
(Special access).
No
Include subdirectories Boolean Check this option to change ACLs of specified files in the current directory and all
subdirectories. Adds /T option.
No
Replace Users Access Rights String A list of new line separated permissions in the form of user:perm where
perm can be: N None R Read
C Change (write) F Full control.
No
Replace without verify Boolean Replace users rights without verify. Adds /Y option. Only valid with Use XCACLS
option.
No
Revoke users rights String Revoke specified users access rights (only valid with Edit ACLs instead of replacing
option unless using ICACLS). Uses /R option.
No

Reboot

Reboot the os

Input properties for the Reboot step
Name Type Description Required
Agent Service Name String If Windows machine restarts but the step is failing, enter the Agent Service Name here. No
Time String The time in seconds to wait to reboot. Yes

Run Scheduled Task

Run a scheduled task.

Input properties for the Run Scheduled Task step
Name Type Description Required
Immediately Boolean Check to run this task immediately. Yes
Task Name String The Name of the scheduled task. Yes