xia automation server - it-administrator...page 9 of 291 xia automation server prerequisites...

Copyright © 2017, CENTREL Solutions

XIA Automation Server

Administrator's Guide

Version: 3.1

of 291 XIA Automation Server

Table of contents

About XIA Automation Server ............................................................................................................................... 6 Installation ............................................................................................................................................................ 7

Installation Requirements (Server) .................................................................................................................. 8

Prerequisites (Windows 2016 / 2012) ....................................................................................................... 9 Prerequisites (Windows 2008) ................................................................................................................. 10 Prerequisites (Windows 2003) ................................................................................................................. 12

Installation Requirements (Client) ................................................................................................................. 16 Installation Process ........................................................................................................................................ 17

Authentication .................................................................................................................................................... 24

Using Integrated Authentication with Firefox ............................................................................................... 25 Logging Out .................................................................................................................................................... 27

Client Tools .......................................................................................................................................................... 28

Connecting to XIA Automation Server ........................................................................................................... 29 Server Configuration ...................................................................................................................................... 31

Branding ................................................................................................................................................... 32 Server Configuration Dialog ..................................................................................................................... 33

Security Tab ........................................................................................................................................ 34 Branding Tab ....................................................................................................................................... 35 Default Branding Tab .......................................................................................................................... 37 Mobile Branding Tab .......................................................................................................................... 38 SMTP Settings Tab .............................................................................................................................. 39 Import Tab .......................................................................................................................................... 40

Licensing ................................................................................................................................................... 41

Install a license file .............................................................................................................................. 42

Account Browser ........................................................................................................................................... 43

Object Types Dialog .................................................................................................................................. 45 Locations Dialog ....................................................................................................................................... 46

Automation Profiles ............................................................................................................................................ 47

Creating an Automation Profile ..................................................................................................................... 48 Automation Profile Properties ...................................................................................................................... 49

General Tab .............................................................................................................................................. 50 Help Text Tab ........................................................................................................................................... 51

Access Control ............................................................................................................................................... 52 Variables ........................................................................................................................................................ 55

General Tab .............................................................................................................................................. 57 Instance Locator ....................................................................................................................................... 59 System Variables ...................................................................................................................................... 60 Standard Variables ................................................................................................................................... 61

Boolean Variable ................................................................................................................................. 62 DateTime Variable .............................................................................................................................. 64 Numeric Variable ................................................................................................................................ 66 List Variable ........................................................................................................................................ 68 Text Variable ....................................................................................................................................... 75

Dynamic Variables .................................................................................................................................... 79

Active Directory Search Variable ........................................................................................................ 80 Dynamic Plugin Variable ..................................................................................................................... 85 SQL Server Dynamic Variable ............................................................................................................. 93


Automation Tasks ............................................................................................................................................. 100

General Tab (Common) ............................................................................................................................... 102 Input and Using Variables ............................................................................................................................ 104 Active Directory Tasks ................................................................................................................................. 106

Account Unlock Task .............................................................................................................................. 107

Task Settings Tab .............................................................................................................................. 108

Account Creation Task ........................................................................................................................... 109

Account Naming ............................................................................................................................... 110 Settings Tab ...................................................................................................................................... 114 Contact Tab ....................................................................................................................................... 115 Address Tab ...................................................................................................................................... 116 Account Name Tab ........................................................................................................................... 117 Account Tab ...................................................................................................................................... 123 Profile Tab ......................................................................................................................................... 125 Behaviour .......................................................................................................................................... 126 Output Variables Tab ........................................................................................................................ 127 Remote Desktop Services Profile Tab ............................................................................................... 128 Member of Tab ................................................................................................................................. 129 Telephones Tab ................................................................................................................................. 130 Organization Tab ............................................................................................................................... 131 Remote Control Tab .......................................................................................................................... 132 Custom Attributes Tab ...................................................................................................................... 133 Directory Tab .................................................................................................................................... 134

Group Creation Task............................................................................................................................... 135

Requirements ................................................................................................................................... 136 Group Tab ......................................................................................................................................... 137 Scope Tab .......................................................................................................................................... 138 Members Tab .................................................................................................................................... 139 Behaviour Tab ................................................................................................................................... 140 Custom Attributes Tab ...................................................................................................................... 141 Directory Tab .................................................................................................................................... 142 Troubleshooting ................................................................................................................................ 143

Password Reset Task .............................................................................................................................. 145


Organizational Unit Creation Task ......................................................................................................... 147

Settings Tab ...................................................................................................................................... 148 Address Tab ...................................................................................................................................... 149 Custom Attributes Tab ...................................................................................................................... 151 Directory Tab .................................................................................................................................... 152

Troubleshooting Active Directory Tasks ................................................................................................ 153

A constraint violation occurred. (exception from hresult: 0x8007202f) .......................................... 154 An invalid dn syntax has been specified ........................................................................................... 155 Could not find the name or insufficient right to see name .............................................................. 156 Exception from HRESULT: 0x80005008 ............................................................................................ 157 Failed to modify the group membership of the user. The object already exists.............................. 158 The attribute syntax specified to the directory service is invalid ..................................................... 159 The requested operation did not satisfy one or more constraints .................................................. 160

Custom Attributes .................................................................................................................................. 161 Directory Settings ................................................................................................................................... 164 Special Characters .................................................................................................................................. 165

Development Tasks ..................................................................................................................................... 166

Execute a Plugin Task ............................................................................................................................. 167


Task Settings Tab .............................................................................................................................. 168 Create a Plugin .................................................................................................................................. 169

Execute Custom Code Task .................................................................................................................... 173

Task Settings Tab .............................................................................................................................. 174 Custom Code Editor .......................................................................................................................... 175

Google Account Tasks .................................................................................................................................. 181

Preparing for automation (Part 1 - Developers Console) ...................................................................... 182 Preparing for automation (Part 2 - Admin Console) .............................................................................. 186 Google Connection Settings ................................................................................................................... 188 Create or Update Google Account Task ................................................................................................. 189

Task Settings Tab .............................................................................................................................. 190 Behaviour Tab ................................................................................................................................... 191 Connection Settings Tab ................................................................................................................... 192

Delete Google Account Task .................................................................................................................. 193

Task Settings Tab .............................................................................................................................. 194 Connection Settings Tab ................................................................................................................... 195

Troubleshooting ..................................................................................................................................... 196

Error connecting to Google online services. Bad request. ............................................................... 197 Error connecting to Google online services. Could not find file ....................................................... 198 Error connecting to Google online services. Not a valid email. ........................................................ 199 Error connecting to Google online services. The specified network password is not correct. ........ 200

Exchange Tasks ............................................................................................................................................ 201

Mailbox Enable Task ............................................................................................................................... 202

Exchange Version Tab ....................................................................................................................... 203 Settings Tab (Exchange 2003) ........................................................................................................... 204 Settings Tab (Exchange 2007) ........................................................................................................... 207 Settings Tab (Exchange 2010) ........................................................................................................... 208 Settings Tab (Exchange 2013) ........................................................................................................... 209 Troubleshooting ................................................................................................................................ 210

File and Directory Tasks ............................................................................................................................... 213

Directory Creation Task .......................................................................................................................... 214

Directory Settings Tab ...................................................................................................................... 215 Sharing Tab ....................................................................................................................................... 216 Security Tab ...................................................................................................................................... 219 Output Variables Tab ........................................................................................................................ 224

Directory Copy and Move Tasks ............................................................................................................. 225

Directory Settings Tab ...................................................................................................................... 226

File Writer Task ...................................................................................................................................... 228

File Settings Tab ................................................................................................................................ 229

Office 365 Tasks ........................................................................................................................................... 230

Requirements ......................................................................................................................................... 231 Office 365 Connection Settings .............................................................................................................. 234 Create or Update Office 365 Account Task ............................................................................................ 235

Task Settings Tab .............................................................................................................................. 236 Licenses and Location Tab ................................................................................................................ 237 Behaviour Tab ................................................................................................................................... 238

Troubleshooting ..................................................................................................................................... 239

Could not load the "Azure Active Directory Module for Windows PowerShell" .............................. 240

Utility Tasks .................................................................................................................................................. 241

Pause Task .............................................................................................................................................. 242



Send Email Task ...................................................................................................................................... 244

Task Settings Tab .............................................................................................................................. 245 CC Addresses Tab .............................................................................................................................. 246

Start Application Task ............................................................................................................................ 247


Variable Tasks .............................................................................................................................................. 250

Copy Variable Task ................................................................................................................................. 251

Copy Settings Tab ............................................................................................................................. 252

Password Generator Task ...................................................................................................................... 253

Password Settings Tab ...................................................................................................................... 254 Minimum Characters Tab ................................................................................................................. 256 Allowed Characters Tab .................................................................................................................... 257

Date Modification Task .......................................................................................................................... 258

DateTime Settings Tab ...................................................................................................................... 259

Modify a String Task ............................................................................................................................... 260


Variable Substring Task .......................................................................................................................... 262


Variable Task Example - Determine First Initial ..................................................................................... 264

Reference .......................................................................................................................................................... 266

Changing the service account password ..................................................................................................... 267 Task Orchestrator ........................................................................................................................................ 269

Scheduler Service .............................................................................................................................................. 270

Automatically Importing Files ...................................................................................................................... 271 Polling Interval ............................................................................................................................................. 273 Diagnostics Logs........................................................................................................................................... 274 Server URL Configuration ............................................................................................................................ 275

Troubleshooting ................................................................................................................................................ 276

Diagnostics ................................................................................................................................................... 277

Enable Diagnostics Manually ................................................................................................................. 278

HTTP Error 401 - Unauthorized access ........................................................................................................ 279 HTTP Error 401.2 - Unauthorized ................................................................................................................ 280 Only system administrators can perform this action ................................................................................. 282 You are prompted for a password when you attempt to access the XIA Automation Server Web Interface. ..................................................................................................................................................................... 283

Web Interface ................................................................................................................................................... 285

Form Input ................................................................................................................................................... 286 CSV Input ..................................................................................................................................................... 289


About XIA Automation Server

XIA Automation Server (www.centrel-solutions.com/xiaautomation) is a network task automation tool with the power and flexibility to automate away most common IT management and network infrastructure tasks. Automation Profiles group together the Automation Tasks that are to be executed either by authorised users or by calling XIA Automation Server's Web Services API.

When an Automation Profile is executed, the user can be prompted for input in the form of Automation Variables. These variables can be validated, minimizing the risk of human error and allowing greater control over the management of the network whilst still allowing the execution of these tasks to be delegated to other users. XIA Automation Server is capable of automating actions such as the following:

• Active Directory users/groups/OUs creation and modification

• Windows directory creation and modification

• Modification of NTFS Permissions

• Exchange Server mailbox provisioning

• Google and Office 365 user provisioning

https://www.centrel-solutions.com/xiaautomation/

https://www.centrel-solutions.com/xiaautomation/


Installation

This section describes the installation process of XIA Automation Server.

• Download the latest installation package: https://www.centrel-solutions.com/xiaautomation/download.aspx

• Ensure you have an appropriate license file, or request a trial license.

• Check that the system you are installing on meets the requirements. Note: the prerequisites differ between the various server operating systems.

https://www.centrel-solutions.com/xiaautomation/download.aspx

https://www.centrel-solutions.com/xiaautomation/download.aspx

https://www.centrel-solutions.com/xiaautomation/request-free-trial.aspx


Installation Requirements (Server)

This section describes the requirements for the installation of XIA Automation Server. XIA Automation Server Requirements The following operating systems are supported for the installation of the XIA Automation Server:

• Windows Server 2016

• Windows Server 2012 and 2012 R2

• Windows Server 2008 and 2008 R2

• Windows Server 2003 (requires a DNS A record to be created)

• Windows XP/Vista/7/8/10 are supported but for evaluation purposes only Prerequisites The following prerequisites must be installed:

• Microsoft .NET 3.5

• IIS

• ASP.NET installed into IIS with the ASP.NET v2.0.50727 Web Service Extension Enabled

• For use with Exchange 2000 or Exchange 2003, the appropriate Exchange Management Tools must be installed on the server

• For use with Exchange 2007/2010, the server must be 64-bit and the Exchange 2007/2010 Management Tools must be installed

XIA Automation Server Browser Requirements The following web browsers are supported for accessing the XIA Automation Server:

• Chrome

• Firefox

• Microsoft Edge

• Internet Explorer 11, 10, 9, 8

• Safari

• Android


Prerequisites (Windows 2016 / 2012)

• In Server Manager, ensure that the Microsoft .NET Framework 3.5.1 Feature is installed

• In Server Roles, ensure that the IIS Server role is installed with at a minimum the role features listed below. Additional role services may be installed. Common HTTP Features Default Document Static Content Application Development .NET Extensibility 3.5 ASP.NET 3.5 ISAPI Extensions ISAPI Filters Security Request Filtering Windows Authentication Management Tools IIS Management Console IIS Management Scripts and Tools (required for upgrades)


Prerequisites (Windows 2008)

• For Windows 2008 (not R2), download and install the Microsoft .NET Framework 3.5.1 if not already installed http://www.microsoft.com/en-us/download/details.aspx?id=22.

• For Windows 2008 R2, In Server Manager, ensure that the Microsoft .NET Framework 3.5.1 Feature is installed:

http://www.microsoft.com/en-us/download/details.aspx?id=22



• In Server Roles, ensure that the IIS Server role is installed with at a minimum the role features listed below. Additional role services may be installed.

Common HTTP Features Static Content Default Document Application Development ASP.NET .NET Extensibility ISAPI Extensions ISAPI Filters Security Request Filtering Windows Authentication Management Tools IIS Management Console IIS Management Scripts and Tools (required for upgrades)


Prerequisites (Windows 2003)

• Start the DNS management console

• Right click within your domain and select "New Host (A)" to create a new DNS A record.

• Enter the name from which you wish to access the XIA Automation Server. In the example, xiaserver is used however any valid value can be used.


• Enter the IP address of the XIA Automation Server

• Click "Add Host"

• Close the DNS management console

• Ensure that Microsoft Internet Information Server is installed in Control Panel > Add / Remove Programs > Windows Components > Application Server


• Under Internet Information Services (IIS), ensure that the following components are installed: Common Files Internet Information Services Manager World Wide Web Service

• Under the World Wide Web Service, ensure that the following components are installed: World Wide Web Service

• If the .NET Framework 3.5 is not installed, please download and install this from the Microsoft web site.


• In the IIS Management Console, ensure that the ASP.NET v2.0.50727 extension is installed and set to Allowed:

More information can be found in the following Microsoft support article http://support.microsoft.com/kb/871179 - please note that the steps to execute setspn.exe are automatically performed by the XIA Automation Server installer.

http://support.microsoft.com/kb/871179


Installation Requirements (Client)

Note: The XIA Automation Client tools are only required for Administrators to design and configure automation profiles. The following operating systems are supported for the installation of the XIA Automation Client tools:


• Windows Server 2012 R2





• Windows XP / Vista / 7 / 8 / 10

• Microsoft .NET 3.5


Installation Process

• Ensure that all of the prerequisites have been completed for the target operating system.

• Download and execute the XIA Automation Server installer (this installs on both 32bit and 64bit):

• You must agree to the End User License Agreement (EULA) to continue:


• Select the production or trial license file. If you do not have a license file, click Download Trial License to be taken to the CENTREL Solutions web site where you may request a trial license.


• Enter the instance name, this will form part of the URL from which users will access the XIA Automation Server web interface. The default is "XIAAutomation" however a more descriptive name such as "UserProvisioning" may be used. The name should contain letters and numbers only. For Windows 2003 this will be http://instancename For Windows 2008 and above this will be http://servername/instancename


• Enter the credentials required to run the XIA Automation Server. This account must have sufficient access rights to perform the tasks configured on the XIA Automation Server. Note: When installing on a computer not connected to an Active Directory domain or when using a local account, enter the computer name in the domain field.


• Click Validate to validate the credentials.

• Select the installation folder

• Click Install when ready.


• When the installer has completed click to start the client tools or the web server interface.

• When accessing the XIA Automation Client Tools for the first time, ensure the URL is entered correctly and click connect.


• Ensure that the web interface loads correctly. If you are prompted for credentials when using Internet Explorer, ensure that the XIA Automation Server URL is configured within the Local Intranet zone.


Authentication

XIA Automation Server utilises the authentication methods built into Windows Internet Information Services (IIS) and supported web browsers. The following methods are supported: Windows Integrated Authentication (default) This authentication method can utilise either NTLM or Kerberos and allows the user to be authenticated automatically without being prompted for a username or password. To enable this for use with the FireFox web browser, please see Using Integrated Authentication with FireFox. Basic Authentication This authentication method is useful when hosting XIA Automation Server for external access. Users are prompted for credentials when they access the XIA Automation Server site.

An SSL certificate should be installed to ensure that the password is encrypted before being sent to the server. Access Requirements To access the system users must be a member of the "XIA Automation Server Users" local or domain group.


Using Integrated Authentication with Firefox

By default, FireFox does not permit automatic logon using Integrated Authentication. This means even when IIS is configured to permit Integrated Authentication, Firefox users are prompted for a username and password. The following describes how to configure FireFox to use Integrated Authentication (NTLM). 1. Open the FireFox browser and enter about:config in the address bar 2. Carefully read any warnings and disclaimers and only proceed if you agree to them

3. Enter ntlm into the filter window


4. Double click the network.automatic-ntlm.auth.trusted-uris field and enter the XIA Automation Server URL. Note: If there are existing values in this field you can add additional values separated by a semicolon - for example http://intranet;http://xiaserver Note: Do not enter the full URL - for example for the XIA Automation Server URL "http://DEMO-SRV01/xiaautomation" enter only "http://DEMO-SRV01"

5. Restart the browser when ready


Logging Out

XIA Automation Server does not handle authentication directly - the ability to log out of the system is handled by Internet Information Services (IIS) and your web browser. Integrated Authentication When using Integrated Authentication, it is not possible to log out of a session as opening the browser and connecting to XIA Automation Server will again perform an NTLM / Kerberos secure login automatically. Basic Authentication When using Basic Authentication, it is possible to log out by:

• Ensuring that you do not allow the web browser to save any passwords if prompted

• Close all browser windows Attempting to access the XIA Automation Server again will prompt for credentials. In a secure environment, it is recommended to ensure that users check that they are again being prompted for credentials before assuming their session is finished.


Client Tools

The XIA Automation Client tools are used for the configuration of XIA Automation Server including designing the automation profiles that are executed by the user. The Client Tools can be opened from the start menu


Connecting to XIA Automation Server

To connect the XIA Automation Server, enter the address in the server field and click connect.


For more options, click the options action point to display all connection options

Server The base address of the XIA Automation Server. Use Default Credentials The system will connect to the XIA Automation Server using the currently logged on user credentials. Use Specific Credentials Connects using the specified username, domain and password. Save Password When using specific credentials, stores the password in the configuration file on the computer running the XIA Automation Client tools. Authentication Determines the authentication method to use between Negotiate, NTLM, Kerberos and BASIC. The default authentication method is Negotiate.


Server Configuration

This section describes the server configuration settings. To access the server configuration:

• Connect to the XIA Automation Server using the client tools

• Select the server configuration navigation bar item

• Click the Server Configuration action point to display the Server Configuration Dialog.


Branding

The branding settings section allows the configuration of the branding settings for XIA Automation Server, allowing you to configure logos and text that represent your company or organization.

Clicking the Branding Properties link displays the Branding Tab of the Server Configuration Dialog.


Server Configuration Dialog

This section describes the options available on the server configuration dialog window.


Security Tab

The security tab allows the configuration of the administrators of this XIA Automation Server.

XIA Admins Determines the names of the users or groups which are to be permitted full control over this XIA Automation Server, one per line.

Administrators of the server running XIA Automation Server are automatically given XIA Admin rights. Resolve Account Names Resolves the account names specified and ensures they are valid. Scheduler Account Name Determines the account name (or group) which has permissions to act as the Scheduler service. By default, this is "NT AUTHORITY\NETWORK SERVICE".


Branding Tab

The branding tab allows the configuration of the title to display in the user's web browser.

Browser Title The title to display in the user's web browser and in the title bar of the home page.


Description The description to display on the home page


Default Branding Tab

The default branding tab allows the configuration of the image to display on the home page for non-mobile devices. This allows your company or organization's logo to be displayed on the XIA Automation Server web interface to users.

Replace Image Displays the file browser to select a replacement image on the home page for non-mobile devices. Set to Default Replaces any custom branding image to the default image for non-mobile devices.


Mobile Branding Tab

The default branding tab allows the configuration of the image to display on the home page for mobile devices. This allows your company or organization's logo to be displayed on the XIA Automation Server web interface to users of mobile devices.

Replace Image Displays the file browser to select a replacement image on the home page for mobile devices. Set to Default Replaces any custom branding image to the default image for mobile devices.


SMTP Settings Tab

The SMTP settings tab configures the global SMTP settings to use when sending email messages via SMTP.

SMTP Server Enter the name or IP address of the SMTP server to use to send messages. Port Enter the TCP port on which the SMTP server is listening. By default, this is port 25. From Address Enter a valid email address from which messages are sent. Use Default Credentials Connections to the SMTP server use the current credentials of the XIA Automation Server service account. Use Specific Credentials Uses the specified credentials when making a connection to the SMTP server.


Import Tab

The Import tab configures whether files should be imported automatically by the Scheduler service.

Enable Import Determines whether files should be imported automatically. Continue on validation failure Determines whether import should continue when lines within the data file contains validation failures. Delete empty directories Determines whether following the import any empty directories should be deleted.


Licensing

XIA Automation Server must be provided with a valid trial or production license. To obtain a trial license please visit http://www.centrel-solutions.com/XIAAutomation/download.aspx To view the current license information, select the licensing node

The licenses are displayed in the tree view.

When using a trial license, you will see licenses for the other CENTREL Solutions products as our trial licenses permit the evaluation of all products in the range.

Product Name The name of the product for which the license is intended. Generated The date on which the license was generated. Type The type of license file - which determines whether this is a full or trial license. Coverage Type The coverage type determines whether the license is bound to a specific Active Directory domain, a specific computer or any. Trial licenses are not bound to any specific computer or domain. Coverage When the coverage type is domain or computer determines the name of the computer or domain to which the license is bound. Expiry Date The date on which the license expires. Max Version The maximum version of the software for which the license may be used. Status The status of the specified license file.

http://www.centrel-solutions.com/XIAAutomation/download.aspx

http://www.centrel-solutions.com/XIAAutomation/download.aspx


Install a license file

To install a license (this process is identical for both production and trial licenses) perform the following steps.

• Right click the list and select Replace license file

• Select the license file and click Open

• You will be prompted to replace any existing file.

• The contents of the license file will be displayed immediately.


Account Browser

The account browser allows for the selection of user, group and computer accounts accessible to the XIA Automation Server.

The accounts and locations displayed are those accessible to the XIA Automation Server even when the client tools are being run on a remote machine. Object Type The type of object(s) to display, clicking the object types button displays the Object Types Dialog. Location The location from which the objects are being displayed - this can be the local machine, an Active Directory domain or the entire directory Clicking the locations button displays the Locations Dialog. Username Contains Provides the ability to search for users with the specified username, Search Results Displays the results of the search


Selected Account(s) Displays the account or accounts that have been selected. Check Names Validates the names of the accounts that have been selected.


Object Types Dialog

The object types dialog allows the selection of the object types to display in the Account Browser.


Locations Dialog

The locations dialog allows the selection of the location from which user, group or machine accounts should be displayed.

The possible locations include

• The entire directory

• An individual Active Directory domain

• The local machine account of the server running XIA Automation Server


Automation Profiles

An Automation Profile allows automation tasks to be executed by the XIA Automation Server - for example an Automation Profile could be created to "Create Student Accounts". Within the automation profile a task would create the actual user account whilst another would create the user a home folder. When the Automation Profile is executed the user must provide answers to the required Variables either using a form, or from a CSV file. Variables are pieces of information that cannot be predefined. In the example of creating a student account the Automation Profile maybe preconfigured with the server on which the home folder is to be created, however the user's Firstname and Surname must be provided. Automation Profiles are configured with Access Control Entries which determine which user account or accounts are able to execute the automation profile. Automation provides can be enabled and disabled using the context menu.

A disabled automation profile has the following icon and is not displayed or accessible to users.


Creating an Automation Profile

To create a new Automation Profile:

• Right click the Automation Profiles node in the treeview and select "New Profile".

• Enter the name of the automation profile, this will be displayed to the users executing the

automation profile.


Automation Profile Properties

To access the properties of an automation profile right click the profile in the treeview and select "Properties".


General Tab

The general tab allows for the configuration of the profile name and description.

Profile Name This determines the name that will be displayed to the user in the web interface when they execute the automation profile. Profile Identifier The unique identifier for the profile in GUID format. This value remains constant even when the profile is renamed. Description The administrator defined description for this automation profile.


Help Text Tab

The help text tab allows for the configuration of the help text to be displayed to the user.

Form Help Defines the help text that will be displayed to users when they are executing this automation profile using a form. Form Failure Defines the message that will be displayed to users when they are executing this automation profile using a form and the automation profile fails to complete successfully. Form Success Defines the message that will be displayed to users when they are executing this automation profile using a form and the automation profile completes successfully. CSV Help Defines the help text that will be displayed to users when they are executing this automation profile using CSV input.


Access Control

Each automation profile can be assigned one or more access control entries that determine which users or groups are allowed to execute this automation profile. Note: In addition to being granted permissions to a specified automation profile users must also be in the "XIA Automation Server Users" security group. Note: Administrators are automatically allowed to execute all automation profiles.

To create a new access control entry

• Right click "Access Control" and select "New Entry"


• Enter the name of the user or group for which you wish to assign the access control entry and assign whether this user or group should be allowed or denied access to this automation profile. Deny access control entries are processed with priority over Allow entries.


• Clicking the browse button will show the Account Browser, when accessing an XIA Automation Server running on a remote machine accounts available to the remote machine are displayed.


Variables

Variables are fields that cannot be predetermined and therefore must be provided by the user. For example, in user provisioning fields such as first name and surname may need to be provided. These variables can be used within automation tasks. Certain tasks such as Variable Tasks and the Execute Custom Code Task are able to modify the values of variables dynamically. Variables are defined in each automation profile. To add a new variable

• Select the automation profile in which to create a variable

• Right click the variables section and select New Variable and select the variable you wish to create.


Variables are displayed to the user in the order they are configured within the management tools. Variables can be reordered using the context menu or the shortcut keys Ctrl+Up and Ctrl+Down.


General Tab

The general tab is provided for all variable types and allows the configuration of common information such as the variable name and description.

Name Enter the name of the variable. The variable name:

• May contain only letters and numbers

• Must be unique in the automation profile

• Is displayed within automation profiles with brackets - for example [MailboxStore]. Display Name The name that is displayed to the user in the user interface when they are executing the automation profile. Description The description of the variable that is displayed to the user. Hidden Variable Determines whether the user is visible for user input. This is used for variables that are set programmatically using automation tasks.


Input Required Determines whether the user must enter a value for this variable before progressing. When Hidden Variable is checked, this field is disabled.


Instance Locator

The instance locator is able to find where a variable has been used within automation tasks.

• Right click a variable and select Find Instances

• Variable instances dialog is shown, displaying where the variable is currently in use


System Variables

Unlike user variables system variables do not require configuration as they are automatically generated by the system. To insert a system variable, select the system variables submenu.

Hover over the variable to view a description of the variable.


Standard Variables

Standard variables provide a user interface for the user to enter or select a value or values. The source of the values is manually entered by the administrator using the XIA Automation Client tools.


Boolean Variable

The boolean variable allows the ability to request that the user selects a boolean (true or false) value.


Settings Tab

The settings tab allows for the configuration of the default boolean value.

Default Value Determines the default value that is displayed to the user.


DateTime Variable

The datetime variable allows the ability to request that the user selects a datetime value.

Command Buttons

Displays the calendar from which the user can select the required date

Configures the selected date to the current datetime on the XIA Automation Server

Clears the currently selected date


Settings Tab

The settings tab allows for the configuration of the datetime variable.

Current Date The default value is set to the current date at the time the automation profile is displayed to the user. Specific Date The default value presented to the user is the value specified.


Numeric Variable

The numeric variable allows the ability to request that the user selects a numeric value. The user is prevented from typing non-numeric characters into the field.


Settings Tab

The settings tab allows for the default, minimum and maximum values for the numeric variable.

Default Value The default value that will be displayed in the form when displayed to the user. Minimum Value The minimum value that can be entered by the user. Maximum Value The maximum value that can be entered by the user.


List Variable

The list variable allows the user to select a value or values from a predefined list. The list can be rendered in one of three modes: Fixed List The user must select a single value from a list of values.

Editable List The user can select a single value from a list of values, or may type an alternative value.

Multiple Select The user can select one or more values from the list of possible values.


Values Tab

The values tab allows for the selection of the type of list and the entry of the values to be displayed to the user.

Fixed List The user must select from a list of values. Editable List The user may select from a list of values, or enter an alternative value. Multiple Select The user must select one or more items from a list of values. Values The values that are presented to the user. The order in which the variables are displayed to the user can be modified.


To modify a value right click the value and click properties, this will display the Variable Option Value Property Dialog.


Variable Option Value Property Dialog

The value option dialog allows you to configure the text and value for each option value.

Text The text that is displayed to the user. Value The value that is assigned to the variable.


Add Multiple Values

To add multiple values simultaneously right click the values list and select Add Multiple Values

The following dialog is displayed which allows multiple values to be typed or pasted directory into the interface, one per line.


Text Settings Tab

The text settings tab allows for the configuration of text input settings when the list mode is set to editable list.

Text Mode The text mode is always set to default for list variables. Default Value The default value that will be displayed to the user in the text field. This setting does not apply for password fields. Maximum Length The maximum length of the value that the user is permitted to enter.


Validation Settings Tab

The validation settings tab is displayed for list variables only when the list mode is set to editable list. For more information see the Validation Settings Tab details for the text variable.


Text Variable

The text variable allows the user to input a text based values and passwords.


Settings Tab

The settings tab allows for the configuration of the text mode, default value and maximum length of the text variable

Text Mode - Default

Text Mode - Multiline


Text Mode - Password

Note: When using password fields, it is recommended that users are required to use HTTPS to connect to the XIA Automation Server. Default Value The default value that will be displayed to the user in the text field. This setting does not apply for password fields. Maximum Length The maximum length of the value that the user is permitted to enter.


Validation Settings Tab

The validation settings tab allows the configuration of regular expressions to validate the user's input.

Validation Type Determines the preconfigured validation settings to use, or custom allows custom entry of a validation expression and error message. Validation Expression The regular express to use to validate the user's input. Validation Error Message The error message to display to the user when their input is invalid. Test Area Allows the input of text to test the validation expression.


Dynamic Variables

Dynamic variables are based on the List Variable however the values that are available for selection by the user are provided dynamically from a target system such as Active Directory or a SQL Server database.


Active Directory Search Variable

The Active Directory Search variable is a dynamic variable able to populate values the user may select from using Active Directory.


Settings Tab

The settings tab allows for the selection of a fixed list or multiple selection

Fixed List The user must select from a list of values. Multiple Select The user must select one or more items from a list of values.


Directory Settings Tab

The directory settings tab allows for the configuration of the settings to use to search Active Directory

Search Type Determines the predefined search to perform against Active Directory or custom allows for the manual configuration of the search filter and properties. Use Default Computer Domain The variable will search the domain to which the XIA Automation Server is a member. Search this LDAP path The LDAP path in canonical format that should be searched - for example "LDAP://demonstration.int/corporate/staff/HR" Search Filter The LDAP file to use to search Active Directory. This field is read-only unless the search type is configured as custom. For more information on LDAP search filters see the following Microsoft article http://technet.microsoft.com/en-us/library/aa996205(v=exchg.65).aspx

http://technet.microsoft.com/en-us/library/aa996205(v=exchg.65).aspx


Display Property The name of the Active Directory property that should be used to generate the value to display to the user for each optional value. Value Property The name of the Active Directory property that should be used as the value that is assigned to the variable when the user selects the optional value. This may be the same as the display property. Recurse Child Containers Determines whether the variable should recursively search containers and organizational units within the specified search path.


Simulation Tab

The simulation tab allows the specified settings to be tested by the XIA Automation Server and the values displayed in the dialog window.

Execute Clicking execute will request that the XIA Automation Server execute the dynamic variable and display the results.


Dynamic Plugin Variable

The Active Directory Search variable is a dynamic variable able to populate values the user may select from using custom VB.NET or C# code.


Settings Tab

The settings tab allows the selection of the list mode and the launching of the code editor.

Launch Code Editor Launches the code editor dialog. Fixed List The user must select from a list of values. Multiple Select The user must select one or more items from a list of values.


Code Editor

The custom code editor allows you to create custom code to be executed by the XIA Automation Server to determine the values that are valid for a variable.

Load Empty Document Clears the code currently loaded into the editor and displays the default code template.

Save Document Saves the currently written code

Language Determines the language in which the code is written, either VB.NET or C#.NET. Changing the selected language will reload the default code template for that language.


Creating Custom Code

To create custom code within the Code Editor follow these steps:

• Select the language you wish to use with the language drop down of either VB.NET or C#.NET

• Modify the execute method, adding any values to the values object:

/// <summary> /// Enter the custom code within the execute method. /// The values displayed to the user are stored in the "Values" property. /// </summary> public override void Execute() {

Values.Add("Sample"); Values.Add("Sample2"); Values.Add("Sample3");

}

• For the example above, the following is displayed to the user:

• It is possible to display descriptive text to the user whilst providing a different value to the automation engine. To use display text, use the overloaded Add() method to provide both the display text and the value:

/// <summary> /// Enter the custom code within the execute method. /// The values displayed to the user are stored in the "Values" property. /// </summary> public override void Execute() { Values.Add("US Dollar", "$US"); Values.Add("Canadian Dollar","$CAD"); Values.Add("Great British Pound", "£GBP"); }

• Standard .NET exception handling applies to custom code. throw new ArgumentException("Unable to populate the values of the dynamic variable.");


Managing References

The references dialog allows additional references to be added to the compiled code.

• References are added one per line.

• You must click save once the references have been updated and code and reload the code editor for the new references to be available to Intellisense.


Dynamic Plugin Variable Example

The following example reads the values of office locations from a text file using a dynamic plugin variable.

• A list of departments is stored in a text file c:\data\departments.txt

• The XIA Service Account has access to the file c:\data\departments.txt

• The following using statement is added to the code using System.IO;


• The following code is used to read the contents of the departments.txt file and add them to the Values collection.

using System; using CENTREL.XIA.Automation.Model; using CENTREL.XIA.Automation.Server; using CENTREL.XIA.Automation.Support.Diagnostics; using System.IO; /// <summary> /// This is a dynamic variable plugin that provides options that the user may select from. /// </summary> public class DynamicVariablePlugin : DynamicPluginVariableBase { /// <summary> /// Enter the custom code within the execute method. /// The values displayed to the user are stored in the "Values" property. /// </summary> public override void Execute() {

string[] departments = File.ReadAllLines(@"c:\data\departments.txt"); foreach (string department in departments)

{ Values.Add(department);

} } }

• The output can be tested on the Simulation Tab.


Simulation Tab




SQL Server Dynamic Variable

The SQL Server variable is a dynamic variable able to populate values the user may select from using a Microsoft SQL Server database as the source of the values.


Settings Tab

The settings tab allows for the selection of a fixed list or multiple selection.

Fixed List The user must select from a list of values. Multiple Select The user must select one or more items from a list of values.


Connection Settings Tab

The connection settings tab allows for the configuration of the SQL Server instance, database and credentials to use when connecting to the database.

Instance Name The name of the SQL server or instance name - for example "DEMO-SQL01" or "DEMO-SQL01\SQLExpress". Database Name The name of the database against which the query should be executed. Use Default Credentials Uses windows authentication to connect to the SQL instance using the XIA Automation Server service account. Use Specific Credentials Uses SQL authentication to connect to the SQL Server with the specified SQL login credentials.


Command Tab

The command tab allows for the configuration of the SQL command to execute to obtain the values for the variable.

Stored Procedure The command to execute is a stored procedure. Text The command is a SQL statement that should be executed. Display Column Name The name of the column that should be used as the display text for the values. Value Column Name The name of the column that should be used for the values, this may be the same as the Display Column. Command The name of the stored procedure or SQL command to execute.


Parameters Tab

The parameters tab allows for the configuration of parameters that should be passed to the stored procedure or SQL statement.

To add a new parameter right click the list and click new


The SQL parameter dialog is shown

Parameter Name The name of the SQL parameter String (VARCHAR) The parameter value will be passed as a string (VARCHAR) value type. Integer (INT) The parameter value will be passed as an integer (INT) value type. Value The value of the value to pass to the stored procedure or SQL statement.


Simulation Tab




Automation Tasks

Automation tasks are the actual tasks to be performed by the XIA Automation Server. Tasks are processed sequentially from top to bottom.

To add a new automation task

• Right click the automation tasks node

• Select "New Task"

• Select the automation task you wish to add


• Complete the required fields for that automation task when prompted


General Tab (Common)

The general tab is common to all automation tasks.

Name Determines the name of the automation task. This should be descriptive and helps provide troubleshooting information to the user - for example "Create user's home folder". Description Provides detailed descriptive information about the purpose of this automation task. Enabled Determines whether this automation task is currently enabled and will be executed by the automation profile. When disabled, automation tasks are shown in the list with a strike-through.

Log and continue When selected if the automation task fails, the failure will be logged to the audit log and the automation profile will continue to the next task.


Abort the entire profile (default) When selected, if the automation task fails, the failure will be logged to the audit log and the automation profile will abort and no subsequent automation tasks will be executed.


Input and Using Variables

Inserting Variables Nearly all text fields within XIA Automation Server allows for the insertion of Variables which allows for the configuration to be changed automatically based on the users input when running an automation profile. To insert a variable

• Right click the field or press the [ key

• You will be able to select from system variables or user variables.

• Hovering over a variable provides more details about the variable's configuration.


Optional Properties Certain properties can be configured to be ignored by the task. When configured in this manner the default values will be used when creating new items or when updating an existing item the current settings are retained.

When enabled the property will be set by the task.


Active Directory Tasks

This section provides information relating to tasks that modify Active Directory.


Account Unlock Task

The account unlock task provides the ability to unlock local machine and Active Directory domain accounts. If you wish to reset a password in addition to unlocking the account, see the Password Reset Task.


Task Settings Tab

The task settings tab allows the configuration of the account that is to be unlocked.

Account Name The name of the account in the format "DOMAIN\User" for domain accounts or "MACHINENAME\User" for local machine accounts. Account Type Determines whether the account is a domain account residing within Active Directory or whether the account is a local machine account.


Account Creation Task

The account creation task is capable of creating and updating Active Directory user accounts in domains running the following server operating systems.


• Windows 2000 Server






Account Naming

The following describes the different naming types that are assigned to user accounts in Active Directory. It is recommended that the user part of both the user logon name and user logon name (pre-Windows 2000) should be the same. Common Name

• The common name is displayed in Active Directory User and Computers.

• This name is not used for authentication.

• This name does not have to be unique in the domain however must be unique within the container or organizational unit in which it is created.


• The common name is shown in search results.


Display Name

• The display name is used for display purposes.

• This name is not used for authentication.

• This does not have to be unique in the domain.

User Principal Name (UPN)

• The UPN name is used for authentication by Windows 2000 operating systems and newer.

• This name must be unique in the forest.


Logon Name (pre-Windows 2000)

• Also known as the SAM account name, this is used as the primary method of authentication.

• This name must be unique in domain.

• This name must not exceed 20 characters.


Settings Tab

The settings tab allows the configuration of the general settings for an Active Directory account.

First Name Configures the first name of the user. Initials Configures the initials of the user. Last Name Configures the surname of the user. Display Name Configures the display name of the user. For more information about the different account and display names within Active Directory please see the Account Naming section. Description Configures the description of the user. Office Configures the office of the user account.


Contact Tab

The contact tab allows for the configuration of contact related settings.

Telephone Number Configures the telephone number for this user. Other Telephone Number(s) Configures additional telephone numbers for this user. Email Configures the email address for this user. Web Page Configures the web page assigned to this user.


Address Tab

The address tab allows for the configuration of address related settings.

Street Configures the street for the user. P.O. Box Configures the PO Box address of the user. State/Province Configures the state or province in which the user resides. ZIP/Postal Code Configures the ZIP or postal code for the user. Country/region Configures the country or region in which the user resides.


Account Name Tab

The account name tab allows for the configuration of account naming settings, LDAP location and password assignment.

Account Name Templates Defines the templates that are used to determine the account name for the user. See the Account Name Templates section for more information. LDAP Path Defines the full path into which the user account should be created in canonical format. Password Defines the password to assign to the user account.


Account Name Templates

Account name templates are used to determine the name of the user account to create or update within Active Directory. Templates in the are processed sequentially until a valid account name is found.

To add a new account template

• Right click the account template list and click "New"


• Complete the required template fields on the General Tab and the Numbering Tab.


General Tab

The general tab allows for the configuration of how each account name type will be generated.

SAM Account Name Determines the SAM account name for the user without the domain prefix. The SAM account name may include Variables and also the <n> token which represents a number that should be inserted into the account name to ensure that it is unique. This is displayed as the "User Logon Name (pre-Windows 2000)" in Active Directory Users and Computers. User Principal Name Determines the User Principal Name (UPN) for the user. This is displayed as the "User Logon Name" in Active Directory Users and Computers. This may include the token <username> which will insert the SAM Account Name into the User Principal Name. Common Name Determines the common name for the user account. This may include the token <username> which will insert the SAM account name into the common name. When using special characters in the common name the character must be encoded otherwise the "An invalid dn syntax has been specified" error may be reported. For more information see http://msdn.microsoft.com/en-us/library/aa366101(v=vs.85).aspx Description Allows an administrator only visible description to be defined for this account naming template.

http://msdn.microsoft.com/en-us/library/aa366101(v=vs.85).aspx



For more information about the different types of account name used in Active Directory see the Account Naming section.


Numbering Tab

The numbering tab allows the configuration numbering rules that help ensure unique user names within Active Directory when creating new user accounts.

Maximum Variants Determines the maximum number of variants of an account name to create. For example, a value of 4 with a SAM account name of "bjones<n>" would allow the generation of the following usernames

• bjones1

• bjones2

• bjones3

• bjones4 Numeric Width Determines the numeric width of the numeric values to use when generating usernames. For example, a numeric width of one may generate the username "bjones1" whereas as value of two may generate the username "bjones01". Include Base Account Name Determines whether the account name without any numerical values should be generated before values are appended. When true in the previous example the user name "bjones" would be created before "bjones1", "bjones2" etc.


Account Tab

The account tab allows for the configuration of account related settings such as whether the user should be forced to change their password at the next logon and the hours on which the user is permitted to logon.

User must change password at next logon Determines whether the user should be forced to change their password at the next logon. This setting cannot be used with the Password Never Expires Setting. User cannot change password Determines whether the user is permitted to change their password. Password never expires Determines whether the user's password never expires. Account disabled Determines whether the user account should be enabled or disabled. If the field is set to "Not Set", newly created accounts will be created as Disabled, the default setting in Active Directory. Account expires Determines the date on which the account should expire. By default, new accounts are created without an expiry date.


Logon Hours Determines the hours that a user is able to logon using this account.


Profile Tab

The profile tab allows for the configuration of profile related settings such the user's profile path and login script.

Profile Path Configures the profile path for the user - for example "\\fileserver01\profile". Login Script Configures the login script for the user - for example "logon.bat" or "logon.vbs". Home Drive Determines the home drive letter for the user - for example "D:", this is used in conjunction with the "Home Path" setting. Home Path The local or UNC path to the user's home directory. When the "Home Drive" property is configured this must be set to a UNC path.


Behaviour

The behaviour tab allows for the configuration of the agent's behaviour to exhibit when creating or updated Active Directory user accounts.

Create Account Determines whether an account should be created by the task. Fail if Exists Determines whether the task should fail if the user account already exists. Update Existing Determines whether an existing user account should be updated by the task. Move Existing Determines whether if the user account already exists, the account should be moved to the organizational unit or path specified in the LDAP Path field on the Account Name Tab. Update Password Determines whether if the user account already exists, the account's password should be reset to that of the password field on the Account Name Tab.


Output Variables Tab

The output variables tab allows for information generated by this task to be stored in Automation Variables.

Account Created Determines the boolean variable in which a true or false response should be stored that indicates whether an account was created by the task. Username Determines the string variable in which the username - for example "tsmith01" that was generated by the task should be stored. Account Name Determines the string variable in which the account name - for example "demonstration\tsmith01" that was generated by the task should be stored. User Principal Name Determines the string variable in which the user principal name (UPN) - for example "[email protected]" that was generated by the task should be stored.


Remote Desktop Services Profile Tab

The remote desktop services profile tab allows for the configuration of remote desktop or terminal services profile settings.

Profile Path Determines the path that should be used for the user's profile when logging in through Remote Desktop Services. Home Drive Determines the home drive letter for the user when logging in through Remote Desktop Services - for example "D:", this is used in conjunction with the "Home Path" setting. Home Path The local or UNC path to the user's home directory when logging in through Remote Desktop Services. When the "Home Drive" property is configured this must be set to a UNC path. Deny Login Determines whether the user should be denied login through Remote Desktop Services.


Member of Tab

The member of tab allows for the configuration of groups to which the user should be made a member of, or removed from.

Retain Membership Determines whether when updating an existing user that user's existing group membership should be retained. When set to false all existing group memberships are removed except the primary group typically the Domain Users group. Add Groups Determines the names of the groups to which the user should be made a member, one per line. Remove Groups Determines the names of the groups from which the user should be removed, one per line. When "Retain Membership" is set to false this field is not available.


Telephones Tab

The telephones tab allows for the configuration of the user's telephony details.

Home Allows for the configuration of the user's home phone number. Pager Allows for the configuration of the user's pager number. Mobile Allows for the configuration of the user's mobile number. Fax Allows for the configuration of the user's fax number. IP Phone Allows for the configuration of the user's IP phone number. Notes Allows for the configuration of additional notes about the user's telephony details.


Organization Tab

The organization tab allows for the configuration of the user's organization details.

Job Title Determines the user's job title. Department Determines the department to which the user belongs. Company Determines the name of the company or organization to which the user belongs. Manager Determines the user name of this user's manager, this should be in the format "domain\username" - for example "DEMONSTRATION\tsmith01". If the manager is not found in Active Directory the task will fail. Setting the manager to a blank value will clear the currently configured manager.


Remote Control Tab

The remote control tab allows for the configuration of the remote control settings that apply when a user logs in through Remote Desktop Service or Terminal Services.

Remote Control Mode Determines the remote control mode that applies when a user logs in through Remote Desktop Service or Terminal Services.


Custom Attributes Tab

The custom attributes tab allows the configuration of Active Directory attributes that are otherwise not configurable within the XIA Automation Server interface.

For more information see the Custom Attributes section.


Directory Tab

The directory tab allows the configuration of how the task should interact with the directory service.

For more information see the Directory Settings section.


Group Creation Task

The group creation task is capable of creating and updating Active Directory security groups in domains running the following server operating systems.








Requirements

Active Directory running on the following operating systems:






• Windows 2000 Server All domain and forest functional levels are supported however please see the Microsoft documentation for details of which group scopes are available at which functional levels. http://technet.microsoft.com/en-us/library/understanding-active-directory-functional-levels(v=ws.10).aspx

http://technet.microsoft.com/en-us/library/understanding-active-directory-functional-levels(v=ws.10).aspx



Group Tab

The group tab allows the configuration of the general settings for an Active Directory group.

Name Determines the name of the group to create or update. LDAP Path Defines the full path into which the group account should be created (or existing groups may optionally be moved to) in canonical format - for example "LDAP://demonstration.int/users". Description Determines the description to assign to the group. Email Determines the email address to assign to the group. Notes Determines the notes to assign to the group.


Scope Tab

The scope tab allows the configuration of the scope of an Active Directory group.

Group Scope Determines the scope that should be assign to the Active Directory group. For more information on group scopes please see the following Microsoft article. http://technet.microsoft.com/en-gb/library/cc755692(v=ws.10).aspx To use a variable to assign the group scope, select custom and select an Integer variable. The value of the variable should match one of the following values. 0. Domain Local 1. Global 2. Universal

http://technet.microsoft.com/en-gb/library/cc755692(v=ws.10).aspx

http://technet.microsoft.com/en-gb/library/cc755692(v=ws.10).aspx


Members Tab

The members tab allows the configuration of the users and groups that should be added or removed from the membership of this group.

Retain Members Determines whether when updating an existing group the existing group membership should be retained or cleared. Add Members Determines the list of users and groups that should be added to the group, one per line. Remove Members Determines the list of users and groups that should be removed from the group, one per line. When the Retain Members field it set to false this property is not available.


Behaviour Tab

The behaviour tab allows for the configuration of the task's behaviour when creating or updated Active Directory groups.

Create Account Determines whether the group account should be created if it does not already exist. Update Existing Determines whether an existing group account should be updated. Update Scope Determines whether an existing group should have its group scope modified if the existing group's scope does not match the scope configured within the task. Move Existing Determines whether an existing group should be moved to the LDAP Path specified on the Group Tab if the group does not currently reside in that LDAP location.


Directory Tab




Troubleshooting

This section highlights the possible issues that you may encounter with this agent and suggested solutions. For more information please see the Active Directory Agent Troubleshooting section.


"The server is unwilling to process the request" changing group scope

Symptoms When attempting to create or modify an Active Directory group, you receive the error: Update of the group failed. Failed to set the group scope. The server is unwilling to process the request. (Exception from HRESULT: 0x80072035) Cause This error can occur if either the Active Directory domain and forest level do not support the specified group scope or that the conversion between group scopes is not permitted. Resolution Review the following Microsoft documentation and ensure that you are selecting a group scope that is valid for your current domain and forest functional level and if you are updating an existing group ensure that the conversation path is supported. Active Directory Group Scopes http://technet.microsoft.com/en-us/library/cc755692(v=ws.10).aspx Domain and Forest Functional Levels http://technet.microsoft.com/en-us/library/understanding-active-directory-functional-levels(v=ws.10).aspx

http://technet.microsoft.com/en-us/library/cc755692(v=ws.10).aspx




Password Reset Task

The password reset task provides the ability to reset passwords on local machine and Active Directory domain accounts. In additional password resets the tasks are able to unlock locked-out user accounts.


Task Settings Tab

The task settings tab allows the configuration of the account for which the password should be reset.

Account Name The name of the account in the format "DOMAIN\User" for domain accounts or "MACHINENAME\User" for local machine accounts. Password The value to which the account's password should be set. Unlock Account A boolean value that determines whether the account should be unlocked. Account Type Determines whether the account is a domain account residing within Active Directory or whether the account is a local machine account.


Organizational Unit Creation Task

The account creation task is capable of creating and updating organizational units in domains running the following server operating systems.








Settings Tab

The settings tab allows the configuration of the general settings for an Active Directory organizational unit.

Name Determines the name of the organizational unit to create or update - for example "Sales Staff". LDAP Path Defines the full path into which the organizational unit should be created or updated in canonical format - for example "LDAP://demonstration.int/corporate users". Description Determines the description to assign to the organizational unit. Update Existing Determines whether an existing organizational unit should be updated.


Address Tab

The address tab allows the configuration of the address settings for an Active Directory organizational unit.

Street The street address to assign to this organizational unit. City The city to assign to this organizational unit. State/province The state/province to assign to this organizational unit. ZIP/postal code The ZIP or postal code to assign to this organizational unit. Country/region The country or region to assign to this organizational unit. Country/region code The 2 digit ISO 3166-1-alpha-2 country code to assign to the organizational unit.


For more information about the ISO 3166 standard see the ISO web site: http://www.iso.org/iso/home/standards/country_codes/country_names_and_code_elements.htm

http://www.iso.org/iso/home/standards/country_codes/country_names_and_code_elements.htm


Directory Tab




Troubleshooting Active Directory Tasks

This section highlights the possible issues that you may encounter with Active Directory based agents.


A constraint violation occurred. (exception from hresult: 0x8007202f)

The agent reports "A constraint violation occurred. (exception from hresult: 0x8007202f)" Symptoms When you are creating or modifying an Active Directory object, you may find the following error reported: Could not commit the setting for Active Directory property 'PropertyName' to 'Value'. A constraint violation occurred. (Exception from HRESULT: 0x8007202F) Cause The setting that XIA has been instructed to set for the value is not valid for the property and has been rejected by Active Directory. This can occur if the value is too long or of the wrong type. Resolution Review the Microsoft documentation for the specified property and ensure that the value specified is valid.


An invalid dn syntax has been specified

The agent reports "An invalid dn syntax has been specified" Symptoms When attempting to create or modify an Active Directory object, you receive the error: "An invalid dn syntax has been specified" Cause This error can occur if the distinguished name is invalid. This can occur if the distinguished name includes invalid charters. Resolution Encode the special characters in the distinguished name for example the display name [Surname], [Firstname] should be encoded as [Surname]\, [Firstname] For more information see the following page: http://msdn.microsoft.com/en-us/library/aa366101(v=vs.85).aspx



Could not find the name or insufficient right to see name

The agent reports "Name translation could not find the name or insufficient right to see name" Symptoms When attempting to create or modify an Active Directory object, you receive the error: Could not convert the LDAP path 'Path'. Name translation: Could not find the name or insufficient right to see name. (Exception from HRESULT: 0x80072116) Cause This error can occur if the LDAP path entered to create the object in or move the object to is not valid or that the service account does not have permissions to this path. Resolution Ensure that the path is valid and that the service account has the required permissions to this path in Active Directory.


Exception from HRESULT: 0x80005008

The agent reports "Exception from HRESULT: 0x80005008" Symptoms When attempting to create or modify an Active Directory object, you receive the error: "Exception from HRESULT: 0x80005008". Cause The error 0x80005008 (ADS_BAD_PARAMETER) can occur when one of the properties has an invalid value. Typically, this is returned from a COM object when setting properties in an external system such as Remote Desktop (Terminal) Services. Resolution Ensure that all properties have a valid value. View the full exception text to determine which property has caused the exception. In the details below it is possible to determine that the library at fault was the TSUSEREXLib used for modification of Remote Desktop (Terminal) Services settings and the property with an invalid value is the Terminal Services profile path. ENTREL.XIA.Automation.Agents.AutomationAgentException: Update of the user account failed. Error setting remote desktop services profile settings. Exception from HRESULT: 0x80005008 ---> CENTREL.XIA.Automation.Agents.AutomationAgentException: Error setting remote desktop services profile settings. Exception from HRESULT: 0x80005008 ---> System.Runtime.InteropServices.COMException (0x80005008): Exception from HRESULT: 0x80005008 at TSUSEREXLib.IADsTSUserEx.set_TerminalServicesProfilePath


Failed to modify the group membership of the user. The object already

exists.

The agent reports "Failed to modify the group membership of the user. The object already exists." Symptoms When attempting to create an Active Directory user account you receive the error "Failed to modify the group membership of the user. The object already exists." Cause When you create a user account and assign the user to the Domain Users group in the domain you may see this error. The Domain Users group is managed by Windows and the account will automatically be added to this group without manual intervention. Resolution Remove the Domain Users group from the Member Of tab of the Account Creation Task.


The attribute syntax specified to the directory service is invalid

The agent reports "The attribute syntax specified to the directory service is invalid" Symptoms When setting custom attributes in Active Directory you may receive the following error: The attribute syntax specified to the directory service is invalid. (Exception from HRESULT: 0x8007200B) Cause This error can typically occur if you are setting the custom attribute to a value type that is invalid - for example setting a string value when the directory service is expecting an integer value. Resolution Ensure the "Commit Immediately" setting is enabled and rerun the task. The specific Active Directory attribute that is configured incorrectly will be displayed in the error message. Review the Microsoft documentation for this attribute and correct the value with the correct data type. Video Watch the video: The attribute syntax specified to the directory service is invalid.

https://youtu.be/ll9WSGpXXHA


The requested operation did not satisfy one or more constraints

The agent reports "The requested operation did not satisfy one or more constraints associated with the class of the object" Symptoms When you are creating or modifying an Active Directory object, you may find the following error reported: The requested operation did not satisfy one or more constraints associated with the class of the object. (Exception from HRESULT: 0x80072014) Cause One or more of the properties that are being updated on the Active Directory object are invalid. This can occur for example, if the value is too long or of the wrong type. Resolution To determine the exact property or properties causing the issue set the Update Immediately setting on the automation task to true and rerun the task. The error generated will then include information about the exact Active Directory property that has caused the error. For more information see A constraint violation occurred.


Custom Attributes

Custom attributes allow the setting of Active Directory attributes that are otherwise not configurable within the XIA Automation Server interface.

To create a new custom attribute:

• Right click within the list

• Select "New" and then the type of value you wish to create.


• Configure the value as required


• Both user and system variables are available for use


Directory Settings

The Directory settings determine how a task interacts with the directory service.

Replication Settings Determines whether the system should force replication between Active Directory domain controllers when the task completes. Forcing Active Directory replication can ensure that, for example, a recently created user account is available on all Domain Controllers for use in subsequent tasks such as setting NTFS permissions on a file or folder. Do not replicate The task should not attempt Active Directory replication. Replicate Active Directory The task should attempt Active Directory replication, however if replication fails to complete the task should not fail. Ensure Active Directory Replication The task should ensure Active Directory replication, if replication fails to complete the task should fail. Commit Immediately Determines whether the task should commit every setting change that is made to Active Directory immediately. This can assist in troubleshooting - for example, as detailed in the article The attribute syntax specified to the directory service is invalid


Special Characters

The following describes the special characters used in names and LDAP paths LDAP Path

Character Handling

\

The backslash character is supported and encoded - for example a path of LDAP://demonstration.int/sales/sales \ support Will be encoded to LDAP://demonstration.int/sales/sales \\ support

/ This character is not supported

Organizational Unit

Character Handling

\

The backslash character is supported and encoded For example, an organizational unit sales \ support Will be encoded to sales \\ support


Groups

Character Handling

\ This character is not supported.



Development Tasks

This section provides information relating to development tasks.


Execute a Plugin Task

Automation plugins allow for custom actions to be created and executed by XIA Automation Server. Unlike the custom code task plugins are written externally to XIA Automation Server using Visual Studio and compiled into a dynamic linked library (dll).

This section assumes you are proficient in .NET development and the use of Visual Studio. For more information on Visual Studio please see the Microsoft site: http://www.microsoft.com/visualstudio/ Automation Plugins

• Run under the context and privileges of the XIA Automation Server service account.

• Can modify the values of automation variables

• Can be written in VB.NET or C#.NET

http://www.microsoft.com/visualstudio/


Task Settings Tab

The task settings tab allows the configuration of the plugin that is to be executed.

Filename The filename (without a path) of the plugin file to execute. For more information about the creation of plugins see the Create a Plugin section.

Note: the plugin must be located in the plugins folder (by default C:\Program Files\CENTREL Solutions\XIA Automation Server\Server\app_data\plugins).


Create a Plugin

To create a plugin, you must create a Visual Studio class library project and compile this as a DLL which can be executed by XIA Automation Server. In the following example, the plugin is created using Visual Studio 2010 using the C# language. 1. Create a new Visual Studio project


2. Create a new Class Library using the C# or VB.NET language and the .NET Framework 3.5

3. Add references to the following files that can be found in the XIA Automation Server directory (by default C:\Program Files\CENTREL Solutions\XIA Automation Server\Server\bin). CENTREL.XIA.Automation.Agents.PluginBase.dll CENTREL.XIA.Automation.Model.dll CENTREL.XIA.Automation.Agents.BaseAgent.dll 4. Rename the default class file class1.cs to CustomPlugin.cs


5. Modify the code in the class file with the following: using System; using CENTREL.XIA.Automation.Agents; /// <summary> /// This is a sample plugin /// </summary> public class CustomPlugin : PluginBase { /// <summary> /// Implements the name of this custom plugin /// </summary> public override string Name { get { return "Custom Plugin"; } } /// <summary> /// Enter the custom code within the execute method /// </summary> public override void Execute() { OnAgentStatusChange("Plugin starting..."); OnAuditAction("Performed an action", AuditActionType.Success); OnAgentStatusChange("Plugin Complete"); } } 6. Ensure that the class name remains as CustomPlugin this is required by the system. 7. Modify the display name of the custom plugin from "Custom Plugin" as required. 8. Enter any custom code you wish to execute in the Execute() method - other methods and classes can be created if required. 9. Set the project build to Release and build the project


10. Open the Release folder and copy the created .dll file (and optionally the .pdb file for additional debug information). Do not copy the other reference files, these will be available automatically in the XIA Automation Server's bin directory.

11. Copy the files from the previous step to the XIA Automation Server installation directory's plugins folder (by default C:\Program Files\CENTREL Solutions\XIA Automation Server\Server\app_data\plugins).


Execute Custom Code Task

The custom code task allows for custom code to be created and executed by XIA Automation Server. Unlike the plugin task custom code is written internally using the XIA Automation Server tools rather than an external development environment such as Visual Studio and is compiled when the automation profile is executed.

This section assumes you are proficient in .NET development. Custom Code

• Runs under the context and privileges of the XIA Automation Server service account.

• Is compiled when the automation profile is executed.

• Can modify the values of automation variables

• Can be written in VB.NET or C#.NET


Task Settings Tab

The task settings tab allows the launching of the code editor.

Launch Code Editor Click the launch code editor button to launch the Custom Code Editor dialog.


Custom Code Editor

The custom code editor allows you to create custom code to be executed by the XIA Automation Server. The code can modify the values of automation variables and make changes to the system.

Load Empty Document Clears the code currently loaded into the editor and displays the default code template.

Save Document Saves the currently written code

Compile Code Compiles the specified code on the XIA Automation Server and returns any errors.

Execute Code Compiles the specified code on the XIA Automation Server, executes the compiled code immediately and returns any errors. NOTE: Automation variables are not available when testing plug-ins through the dynamic code editor.


Language

Determines the language in which the code is written, either VB.NET or C#.NET. Changing the selected language will reload the default code template for that language.


Creating Custom Code

To create custom code within the Custom Code Editor follow these steps

• Select the language you wish to use with the language drop down of either VB.NET or C#.NET.

• Modify the name of the plug-in that will be displayed in the audit log - for example "Update Database".

/// <summary> /// Implements the name of this custom plugin /// </summary> public override string Name {

get { return "Update Database"; } }

• Modify the execute method and add any custom code you wish, the comments in the summary block can be replaced as required.

/// <summary> /// The summary can be updated to provide useful information. /// </summary> public override void Execute() { }

• Variables can be accessed and modified through the Variables property. To modify a variable named ExpiryDate use the following code. Variables.FindByName("ExpiryDate").Value = DateTime.Now.AddMonths(1);

• Information can be written to the XIA Automation Server trace log using the OnAgentStatusChange() method. OnAgentStatusChange ("The custom plugin in now starting...");

• Information can be written to the XIA Automation Server audit log using the OnAuditAction() method passing the message to write to the audit log and the AuditEntryType. OnAuditAction("The agent has modified the ExpiryDate", AuditEntryType.Information);


• The optional available for the AuditEntryType are displayed by Intellisense

• Standard .NET exception handling applies to custom code. Variable UsernameVariable = Variables.FindByName("Username"); if (UsernameVariable==null) throw new ArgumentException("The Username variable was not found.");


Managing References

The references dialog allows additional references to be added to the compiled code.

• References are added one per line.

• You must click save once the references have been updated and close and reload the code editor for the new references to be available to Intellisense.


Custom Code Example - Mailbox Store Naming

In the following example, there is a business requirement that mailboxes be created across multiple mailbox stores.

• The Exchange mailbox store is determined by the name of the user that has been created

o Users with usernames that start with letters A-G are stored in "Store1" o Users with usernames that start with letters H-N are stored in "Store2" o Users with usernames that start with letters O-Z are stored in "Store3"

• The user's username has been stored in an output variable named [Username].

• The Mailbox Enable Task is configured with a mailbox store using the variable [MailboxStore] using System; using CENTREL.XIA.Automation.Agents; using CENTREL.XIA.Automation.Model; using CENTREL.XIA.Automation.Support.Diagnostics; using System.Text.RegularExpressions; /// <summary> /// Determines the name of the Exchange mailbox store. /// </summary> public class CustomPlugin : PluginBase { /// <summary> /// Implements the name of this custom plugin /// </summary> public override string Name { get { return "Determine Exchange Mailbox Store"; } } /// <summary> /// Determines the name of the Exchange mailbox store based on the user's name. /// </summary> public override void Execute() { string FirstLetter = Variables.FindByName("Username").ValueString.Substring(0,1); if (Regex.IsMatch(FirstLetter, "[A-G]")) { Variables.FindByName("MailboxStore").Value = "Store1"; } if (Regex.IsMatch(FirstLetter, "[H-N]")) { Variables.FindByName("MailboxStore").Value = "Store2"; } if (Regex.IsMatch(FirstLetter, "[O-Z]")) { Variables.FindByName("MailboxStore").Value = "Store3"; } } }


Google Account Tasks

This section provides information relating to Google account related tasks. For more information about Google please see the Google web site https://www.google.com/business/ Before the automation tasks can be executed you must follow the steps in the Preparing for automation section.

https://www.google.com/business/


Preparing for automation (Part 1 - Developers Console)

The follow steps describe how to generate a development project and create a Google service account private key.

• Logon to the developer console as an administrator. https://console.developers.google.com

• Click "Create Project"

• Enter the project name "XIA Automation Server"

• Select APIs and auth > APIs

• Enter "Admin SDK" in the search field

https://console.developers.google.com/

https://console.developers.google.com/


• Select the API and click Enable API

• Select APIs and auth > Credentials

• Select Add Credentials > Service account


• Select P12 and click “Create”

• Save the file that is created on the XIA Automation Server machine in the Google directory which is by default found in the following location C:\Program Files\CENTREL Solutions\XIA Automation Server\Server\app_data\encryption\Google

• Make a note of the password for the private key when prompted, typically this will be "notasecret"


• Select the newly created service account from the list

• Make a note of the Client ID and Email address


Preparing for automation (Part 2 - Admin Console)

The follow steps describe how to assign the service account created in Preparing for automation (Part 1 - Developers Console) to the domain:

• Logon to the Google Admin console as an administrator https://admin.google.com/

• Go to Security > API Reference

• Ensure that Enable API Access is ticked

• Go to Security > Advanced settings > Manage API client access

• Enter the Client ID stored from the previous step in the Client ID field

• Enter the following in the One or More API Scopes field. https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.user

https://admin.google.com/

https://admin.google.com/


• Click Authorize


Google Connection Settings

The connection settings determine the credentials required to connect to the Google online services for your domain. Delegated User Email The email address of the administrative user in the Google domain as whom the actions will be performed. Service Account Email The email address of the service account created in the Preparing for automation (Part 1 - Developers Console) section. Private Key File The absolute path of the private key file (.p12) created in the Preparing for automation (Part 1 - Developers Console) section. Private Key Password The private key password, by default this is set by the Google developer's console to "notasecret".


Create or Update Google Account Task

The Create or Update Google Account task is able to create or update a Google account.

Note: Ensure that the Google domain has been configured by following Preparing for automation (Part 1 - Developers Console) and Preparing for automation (Part 2 - Admin Console).


Task Settings Tab

First Name The user's first name. Last Name The user's surname. Password The user's password. This is mandatory when creating an account. Primary Email Address The user's primary email address - for example "[email protected]". The domain name must be valid for the account configured within the Connection Settings Tab. Change Password at Next Logon Determines whether the user is required to change their password at next logon. Suspended Determines whether the account should be configured as suspended.


Behaviour Tab

Create Account Determines whether an account should be created if one does not exist with the Primary Email Address specified on the Task Settings Tab. Update Existing Account Determines whether the account should be updated if one exists with the Primary Email Address specified on the Task Settings Tab.



Note: The tab is common to all Google Account Tasks, see the Google Connection Settings section for more information.


Delete Google Account Task

The Delete Google Account task is able to delete a Google account using a user's primary email address or unique identifier.



Task Settings Tab

Account Name The name of the Google account to be deleted. This can be the user's primary email address or unique identifier. Throw exception if account doesn't exist Determines whether an exception should be thrown if the user account to be deleted does not exist. By default, this is false.



Note: The tab is common to all Google Account Tasks, see the Google Connection Settings section for more information.


Troubleshooting

This section provides common troubleshooting steps for the Google Account Tasks.



Error connecting to Google online services. Bad request.

The agent reports "Error connecting to Google online services. Bad request." Issue When you execute one of the Google Account Tasks you experience an error similar to the following: "Error connecting to Google online services. Bad request." Cause This can be caused when the Service Account Email has been entered incorrectly in the Google Connection Settings section. Solution Ensure that the Service Account Email has been entered correctly in the Google Connection Settings section. The service account email must be exactly that which was created in Preparing for automation (Part 1 - Developers Console).


Error connecting to Google online services. Could not find file

The agent reports "Error connecting to Google online services. Could not find file" Issue When you execute one of the Google Account Tasks you experience an error similar to the following: Error connecting to Google online services. Could not find file 'path\App_Data\Encryption\Google\auth.p12'. Cause This can be caused when the encryption key specified in the Google Connection Settings has been entered incorrectly, or if the specified key does not exist. Solution Ensure that the key created in Preparing for automation (Part 1 - Developers Console) has been saved to the correct location and has been specified correctly.


Error connecting to Google online services. Not a valid email.

The agent reports "Error connecting to Google online services. Not a valid email." Issue When you execute one of the Google Account Tasks you experience an error similar to the following: "Error connecting to Google online services. Not a valid email." Cause This can be caused when the Delegated User Email has been entered incorrectly in the Google Connection Settings section. Solution Ensure that a valid administrator account for the domain has been entered correctly for the Delegated User Email field in the Google Connection Settings section.


Error connecting to Google online services. The specified network

password is not correct.

The agent reports "Error connecting to Google online services. The specified network password is not correct." Issue When you execute one of the Google Account Tasks you experience an error similar to the following: "Error connecting to Google online services. The specified network password is not correct." Cause This can be caused when the Private Key Password has been entered incorrectly in the Google Connection Settings section. Solution Ensure that the password has been entered correctly for the Private Key Password field in the Google Connection Settings section that was created in Preparing for automation (Part 1 - Developers Console).


Exchange Tasks

This section provides information relating to Microsoft Exchange server tasks. For more information about Microsoft Exchange please see the Microsoft web site: http://microsoft.com/exchange

http://microsoft.com/exchange


Mailbox Enable Task

The mailbox enable task is capable of creating mailboxes on Microsoft Exchange servers on the following platforms:

• Exchange 2013

• Exchange 2010

• Exchange 2007

• Exchange 2003

Note: The Exchange management tools for the required version of Exchange must be installed on the server running XIA Automation Server.


Exchange Version Tab

The exchange version tab allows the selection of the version of the Exchange environment where the mailbox is to be created.

The version of Exchange selected determines the settings that are required for completion on the settings tab.


Settings Tab (Exchange 2003)

When the Exchange version is set to Exchange 2003 the settings tab requires the following information.

Ensure that the XIA Service account has at least Exchange View Only Administrator rights and access to the user accounts which are to be mailbox enabled. Without this permission, you may see the error: There is no such object on the server. (Exception from HRESULT: 0x80072030).

For more information see: http://www.microsoft.com/en-us/download/details.aspx?id=18442



Account Name The name of the account to mailbox enable in the format "DOMAIN\Username". Domain Name The name of the Active Directory domain in which the Exchange organization resides. Organization [1] The name of the Exchange Organization in which to create the mailbox. Note that the "(Exchange)" suffix is not part of the organization name. Admin Group [2] The name of the administrative group in which to create the mailbox. Exchange Server [3] The name of the Exchange server on which to create the mailbox. Storage Group [4] The name of the storage group in which to create the mailbox. Mailbox Database [5] The name of the mailbox database in which to create the mailbox.



When the Exchange version is set to Exchange 2007 the settings tab requires the following information.

Account Name The name of the account to mailbox enable in the format "DOMAIN\Username". Storage Group The name of the storage group in which to create the mailbox. Exchange Server The name of the Exchange Server on which to create the mailbox. Mailbox Database The name of the mailbox database in which to create the mailbox.



When the Exchange version is set to Exchange 2010 the settings tab requires the following information:

Account Name The name of the account to mailbox enable in the format "DOMAIN\Username". Mailbox Database The name of the mailbox database in which to create the mailbox (optional).



When the Exchange version is set to Exchange 2013 PowerShell remoting is used and the settings tab requires the following information.

Account Name The name of the account to mailbox enable in the format "DOMAIN\Username". Exchange Server The name of an Exchange server to connect to. Mailbox Database The name of the mailbox database in which to create the mailbox (optional).


Troubleshooting

This section highlights the possible issues that you may encounter with this agent and suggested solutions.


Could not load file or assembly 'System.Management.Automation'

Issue When attempting to mailbox enable a user on Exchange 2007 or above you may receive the error "Could not load file or assembly 'System.Management.Automation". Cause This error can occur if PowerShell is not installed on the machine running XIA Automation Server. Solution Ensure that the correct Exchange version is selected within the configuration. Install PowerShell and the Exchange Management Console on the machine running XIA Automation Server and try again.


There is no such object on the server. (Exception from HRESULT:

0x80072030)

Error "There is no such object on the server. (Exception from HRESULT: 0x80072030)" Issue When attempting to mailbox enable a user on Exchange 2003 you may receive the error "There is no such object on the server. (Exception from HRESULT: 0x80072030)". Cause

• This can occur if one of the settings such as the Exchange organization name has been entered incorrectly into the configuration.

• For Exchange 2003 the user does not have the Exchange View Only Administrator permission Solution

• Ensure that all configuration settings have been entered correctly and try again.

• For Exchange 2003 ensure that the user is granted at least the Exchange View Only Administrator permission.


File and Directory Tasks

This section provides information relating to tasks that modify the file system.


Directory Creation Task

The directory creation task is capable of creating and updating directories on local and remote file systems, sharing directories and setting NTFS permissions. The task can create and update directories on file servers running on the following operating system versions:









The directory settings tab allows the configuration of the file server and path on which the directory should be created or updated.

File Server The name of the local or remote file server on which the directory should be created or updated. For the local machine the machine name or "localhost" can be used. Path The absolute path where the directory should be created, or an existing directory should be updated. This should always be a local path even when updating a directory on a remote machine. Update Existing A boolean value that determines whether an existing directory should be updated.


Sharing Tab

The sharing tab allows the share configuration settings for a directory.

Retain existing settings Any existing share settings are preserved. Share this folder The folder will be shared with the specified share name, any existing share names will be removed. Delete existing shares The folder will not be shared, and any existing shares will be removed. Custom To use a variable to assign share action select custom and select an Integer variable. The value of the variable should match one of the following values: 0. Retain existing settings 1. Delete existing shares 2. Share the folder


Share name The name that should be assigned to the share. Appending a dollar $ symbol to the share will cause the share to be hidden when browsing the shared folders on the server. Description Determines the description to assign to the share. Limit Maximum Connections Determines the maximum number of concurrent connections that should be allowed to access the shared folder. Permissions Determines the share level permissions to assign to the share. For more information see the Share Permissions section.


Share Permissions

The share permissions dialog allows the configuration of share permissions.

Share permissions are used in conjunction with NTFS permission, the most restrictive permissions are applied. Group or user names Select the group or user to which you wish to assign the share permission. Full Control The specified user or group will be allowed or denied full control over the shared folder. Change The specified user or group will be allowed or denied change permissions over the shared folder. Read The specified user or group will be allowed or denied read permissions over the shared folder. This is the default permission assigned.


Security Tab

The security tab allows the configuration of the NTFS permissions to assign to the directory.

For more information see the NTFS Permissions section.


NTFS Permissions

NTFS permissions are the security permissions assigned at the filesystem level, they include an owner and an access control list (ACL) which contains access control entries (ACE) which determine what permissions a user or group has over a file or directory. Permissions can be inherited, meaning that permissions set on a parent directory will flow automatically to files and directories within that directory.


General Tab

The general tab allows the configuration of general NTFS permission settings such as inheritance.

Set NTFS permissions Determines whether the NTFS permissions should be modified for this directory. Inherit permissions Determines whether the permissions on this folder should be inherited from the parent directory. Replace existing permissions Determines whether any existing NTFS permissions explicitly set on the directory should be removed from the access control list (ACL) and replaced with the permissions on the permissions tab. Replace child permissions with inheritance Determines whether the permissions on child objects should be removed and replaced with permissions inherited from this directory.


Permissions Tab

The permissions tab allows the modification of the access control list (ACL) for the specified directory.

The permissions tab is not disabled when Set NTFS Permissions is set to false on the General Tab.

Group or user names Determines the user or group for which an access control entry (ACE) should be created. Permissions The permissions to assign to the specified user or group.


Owner Tab

The owner tab allows the modification of the owner of the specified directory.

Change Owner Determines whether the owner should be changed for the directory Recurse Owner Determines whether the owner should be changed for this directory and all directories and files within it. Take Ownership (Service Account) Transfers the ownership of the directory to the service account that is running the XIA Automation Server. Transfer Ownership Transfers the ownership of the directory to the specified user account in the format "DOMAIN\username".

When using this option, the service account must have the Restore files and directories user right assignment.


Output Variables Tab

The output variables tab allows for information generated by this task to be stored in Automation Variables.

Directory Exists Specifies the boolean variable in which a true or false response should be stored that indicates whether the directory already exists when the task is executed.


Directory Copy and Move Tasks

The directory move task is capable of moving or copying a directory between local or remote file systems. The task can copy or move directories on file servers running on the following operating system versions:









The directory settings tab allows the configuration of the file servers and paths between which the directory should be copied or moved.

Source Server The name of the file server on which the folder to copy or move resides. If the server is the machine running the XIA Automation Server either the server name or "localhost" may be used. Source Path The absolute path of the source directory. This should always be a local path even when copying or moving a directory from a remote machine. Destination Server The name of the file server to which the folder should be copied or moved. If the destination server is the machine running the XIA Automation Server either the server name or "localhost" may be used. Destination Path The absolute path where the directory should be copied. This should always be a local path even when copying or moving a directory to a remote machine.


Copy Directory Indicates that the directory should be copied. Move Directory Indicates that the directory should be moved. Overwrite Existing Directory Determines whether, if the destination directory already exists, it should be overwritten by the directory being copied or moved.

WARNING: when overwriting an existing directory any existing files and subfolders are removed.


File Writer Task

The file writer task is capable of creating and updating text files on local and remote file systems. The task can create and update files on file servers running on the following operating system versions:








File Settings Tab

The file settings tab allows the configuration of the file server, path and contents which should be written to a text file.

Server The name of the file server on which to write the file. If the server is the machine running the XIA Automation Server either the server name or "localhost" may be used. File Path The absolute path of the text file to write. This should always be a local path even when writing a file to a remote machine. Text The text to write to the text file. Overwrite The contents of the text file should be overwritten with the text in the text field. Append The text in the text field should be appended to the text file.


Office 365 Tasks

This section provides information relating to Microsoft Office 365 online account related tasks. For more information about Office 365 please see the Office 365 web site: https://products.office.com Before the automation tasks can be executed you must follow the steps in the Requirements section.

https://products.office.com/


Requirements

Microsoft Office 365 is managed by XIA Automation Server using Windows PowerShell and the Azure Active Directory Module for Windows PowerShell.

• The agent can only be used on 64-bit systems.

• Download the Microsoft Online Services Sign-In Assistant for IT Professionals RTW, selecting the "en\msoidcli_64.msi" option when prompted.

• Execute the installer, reviewing the terms

https://msdn.microsoft.com/en-us/mt173057.aspx

https://technet.microsoft.com/library/jj151815.aspx

http://go.microsoft.com/fwlink/?LinkID=286152


• Complete the installation

• Download the Azure Active Directory Module for Windows PowerShell (64-bit version).

• Execute the installer, reviewing the terms

http://go.microsoft.com/fwlink/p/?linkid=236297


• Review the installation location and click Next

• Complete the installation


Office 365 Connection Settings

The connection settings determine the credentials required to connect to the Microsoft Office 365 online services for your domain. Username The email address of the administrative user in the Office 365 domain as whom the actions will be performed. Domain This field is not required. Password The password of the administrative user.


Create or Update Office 365 Account Task

This task is able to create or update a Microsoft Office 365 online account.

Note: Ensure that the server meets the Requirements before executing this task.


Task Settings Tab

First Name The user's first name. Last Name The user's surname. Display Name The display name for the user. Password The user's password. This is mandatory when creating an account, and optional when updating an account. User Principal Name The user's primary logon - for example "[email protected]". The domain name must be valid. Change Password at Next Logon Determines whether the user is required to change their password at next logon.


Licenses and Location Tab

Licenses The licenses to assign to the account when it is created. This field has no effect when updating an existing account. Usage Location A valid 2 letter country code for the country in which this account will be used.


Behaviour Tab

Create Account Determines whether an account should be created if one does not exist with the User Principal Name specified on the Task Settings Tab. Update Existing Account Determines whether the account should be updated if one exists with the User Principal Name specified on the Task Settings Tab. Update Password Determines whether the account's password should be updated if the account already exists.


Troubleshooting

This section provides common troubleshooting steps for the Office 365 Tasks.

Note: Ensure that the requirements section has been completed prior to executing any of the Office 365 Tasks.


Could not load the "Azure Active Directory Module for Windows

PowerShell"

Error "Could not load the "Azure Active Directory Module for Windows PowerShell" Issue When you execute one of the Office 365 Tasks you experience an error similar to the following "Could not load the "Azure Active Directory Module for Windows PowerShell". Please ensure that this has been installed. The specified module 'MSOnline' was not loaded because no valid module file was found in any module directory." Cause This is caused when the requirements have not been installed on the server running XIA Automation Server. Solution Ensure that steps in the requirements section have been completed correctly and restart the Office 365 Task.


Utility Tasks

This section provides information relating to utility tasks.


Pause Task

The pause task is capable of pausing the entire automation process for the specified period of time. This can be used when the automation process must manually wait for another process to complete.


Task Settings Tab

The task settings tab allows the configuration of the pause task.

Pause Duration The amount of time that the automation process should pause in milliseconds.


Send Email Task

The send email task is capable of sending an email via SMTP to one or more recipients. This can be used to notify the completion of an automation task.

Note: The global SMTP settings must be configured on the server. For more information see the SMTP Settings Tab section.


Task Settings Tab

The task settings tab allows the configuration of the addresses, subject and message body for the email.

To Address(es) Determines the email addresses to which the email should be sent, one per line or separated by semicolons. Subject The subject of the message to send. Message Body The body of the message to send.


CC Addresses Tab

The CC addresses tab allows the configuration of CC and BCC addresses to which the email should be sent.

CC Address(es) Determines the email addresses to which the email should be CC (carbon copied), one per line or separated by semicolons. BCC Address(es) Determines the email addresses to which the email should be BCC (blind carbon copied), one per line or separated by semicolons.


Start Application Task

The start application task is capable of executing an external application on the XIA Automation Server.

Note: The application is executed using the credentials of the XIA Automation Server service account.


Task Settings Tab

The task settings tab allows for the configuration of settings to use when executing the external application.

Filename The absolute path to the executable file on the XIA Automation Server. Working Directory The absolute path to the directory that should be used as the working directory when executing the application. This is typically the directory in which the executable file resides. Arguments The command line arguments to use when executing the application. Wait for Completion Determines whether the automation process should wait until the application has completed and returns an exit code before progressing. Timeout When Wait for Completion is true, determines the amount of time to wait in seconds for the application to complete. If the application execution time exceeds the timeout the application is terminated and the task is marked as failed.


Note: The when application is executed the returned exit code is checked, any code other than 0 is deemed a failure and the task is marked as failed.


Variable Tasks

This section provides information relating to variable modification tasks.

Variables can also be modified using the Execute Custom Code Task.


Copy Variable Task

The copy variable task allows for the copying of the value of a variable into another variable of the same type. This is useful when the you wish to modify the value of a variable whilst also retaining the original value.


Copy Settings Tab

The copy settings tab allows for the configuration of the source and destination variables.

Source Variable Name Determines the variable from which the value should be copied. Both user and system variables maybe selected. Destination Variable Name Determines the variable to which the value should be copied.

• Only user variables maybe selected.

• The variable must be of the same data type as the source variable.


Password Generator Task

The password generator task allows for the generation of a random password which is stored in an output variable. This variable may then be accessed for use in subsequent tasks such as the Account Creation Task.


Password Settings Tab

The password settings tab allows for the general configuration of the task.

Variable Name Determines the text variable into which the generated password should be stored. Create a Variable Clicking the create a variable link will automatically create and assign a new variable name [PASSWORD] or if this variable exists [PASSWORD<n>] where <n> is a numerical value starting at zero incremented until an unused variable name can be found. Minimum Length The minimum number of characters that the generated password must have. When this field is set to the same as the maximum length passwords will always be generated with the same number of characters. Maximum Length The maximum number of characters that the generated password must have. When this field is set to the same as the minimum length passwords will always be generated with the same number of characters.


Display Output Determines whether the generated password should be displayed within the diagnostics trace log. By default, this is disabled for security reasons.


Minimum Characters Tab

The minimum characters tab determines the minimum number of each character class that must be included in the generated password.

Uppercase The minimum number of uppercase characters that must be included in the generated password. Lowercase The minimum number of lowercase characters that must be included in the generated password. Numerical The minimum number of numerical characters that must be included in the generated password. Special The minimum number of special characters that must be included in the generated password.

Note: the total number of characters of all character classes must not exceed the maximum characters specified on the Password Settings Tab.


Allowed Characters Tab

The allowed characters tab determines what characters are available for use within each character class. By default, certain characters such as "1", "i" and "l" are excluded from the possible characters as they may be difficult for users to differentiate.

Uppercase The uppercase characters that may be used when generating a password. Lowercase The lowercase characters that may be used when generating a password. Numeric The numeric characters that may be used when generating a password. Special The special characters that may be used when generating a password.


Date Modification Task

The date modification task can be used to modify a date variable. This task can be used for example to set an expiry date to be used with the Account Creation Task, setting the expiry date to be a month from now.


DateTime Settings Tab

The DateTime settings tab allowed the selection of the variable to modify, the action and the amount by which the date time value should be modified.

Variable Name Determines the name of the DateTime variable to modify. Subtract The specified value will be subtracted from the selected variable. Add The specified value will be added to the selected variable. Modification Value The value by which the date time variable should be modified.


Modify a String Task

The modify a string task is able to modify a string (text) variable assigning either a specific value or by randomly selecting a value from a list of possible values. This can be used from example to randomly load balance the home directory created for a user with the Directory Creation Task across a range of file server names.


Task Settings Tab

The task settings tab allows the selection of the variable to modify and the values to assign the variable.

Variable Name The string (text) variable whose value is to be modified. Assign this value The value to assign to the variable. This may include both user and system variables. Randomly assign from these values A list of values (one per line) that may be assign to the variable. The task will automatically assign the value randomly. The values may include both user and system variables.


Variable Substring Task

The variable substring task is able to modify the value of a variable by taking part of the text value (a substring) based on a start index and length. This can be used from example to determine the user's first initial from their first name.


Task Settings Tab

The task settings tab allows the configuration of the variable to modify, the start index and length.

Variable Name The name of a string (text) variable to be modified. Start Index The numerical value of the position within the string to start the substring. Length The number of characters to take from the string.

A length of zero indicates that the remainder of the string should be taken. Sample Text Allows for the entry of sample text for which the start index and index can be tested. Output The output of the configured settings on the sample text.


Variable Task Example - Determine First Initial

The following example shows how to determine the user's first initial using variable modification tasks:

• Create a new text automation variable called [FirstName]. The variable should not be hidden and should be set to required as the user will need to provide this information.

• Create a new text automation variable called [FirstInitial] the variable should be hidden.

• Create a new Copy Variable Task

• Set the source variable to [FirstName] and the destination variable to [FirstInitial].

• Create a new Variable Substring Task.


• Select the [FirstInitial] as the variable to modify, the start index to zero and the length to one.

• The user's first initial will now be available in subsequent tasks as the [FirstInitial] variable.


Reference

This section provides a technical reference for the XIA Automation Server product.


Changing the service account password

The service account password is assigned to the application pool in IIS. When you change the password for the user account in Active Directory Users and Computers the password must also be updated in the IIS Manager application.

• Open the IIS Manager Application

• Expand the server configuration and select application pools

• Select the XIA Automation application pool which is named after the instance name selected during the installation. By default, this is XIAAutomation however in the example screenshot the instance name selected was UserProvision.


• Select Advanced Settings from the Action Pane.

• Select the identity and click the ellipsis (...) to assign the new password you have set in Active Directory Users and Computers.


Task Orchestrator

The task orchestrator is responsible for executing an automation profile, reading each automation task within the configuration and dynamically loading and executing the automation agent required to perform that task.

Figure 1: Task Orchestrator process


Scheduler Service

The XIA Automation Server scheduler service schedules automated tasks such as:

• Automatically Importing Files The task runs as a Windows service which starts automatically, and is installed by default to run as the Network Service account.

https://msdn.microsoft.com/en-us/library/windows/desktop/ms684272(v=vs.85).aspx


Automatically Importing Files

The Scheduler Service provides the ability to poll a directory on the file system and automatically import files within that directory. To enable automatic import, complete the following steps:

• Logon as an Administrator

• Ensure that the Scheduler Service is configured and running

• Enable the import functionality see the Import Tab of the Server Configuration dialog

• Open the Import directory within the XIA Automation Server installation, by default this can be found here: C:\Program Files\CENTREL Solutions\XIA Automation Server\Server\App_Data\Import

• View the properties of the automation profile you wish to automate in the Client Tools and note the profile identifier


• Create a new directory in the Import directory that matches either the profile name or profile identifier. It is recommended that the profile identifier is used as this remains constant even if the profile name is changed.

• Place any CSV files containing the data into the directory created. The data will be automatically imported by the Scheduler Service at the next polling interval and the results written to the audit log.


Polling Interval

By default, the Scheduler Service automatically polls the XIA Automation Server every 60 seconds (60000ms). This value can be modified using the following registry key.

HKEY_LOCAL_MACHINE\SOFTWARE\CENTREL Solutions\XIA Automation Scheduler PollingInterval REG_DWORD The value is stored in milliseconds and should be entered as a Decimal value.


Diagnostics Logs

To enable diagnostics trace logs for the Scheduler Service, set the following registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\CENTREL Solutions\XIA Automation Scheduler PollingInterval REG_DWORD Set the value to 1 to enable and 0 to disabled. Files will be written to the following file by default. C:\Program Files\CENTREL Solutions\XIA Automation Server\XIA Automation Scheduler\Logs\Trace\trace.log.


Server URL Configuration

The Scheduler Service automatically polls the URL of the XIA Automation Server on the polling interval. The URL is automatically configured by setup however can be reconfigured by modifying the following registry key.

HKEY_LOCAL_MACHINE\SOFTWARE\CENTREL Solutions\XIA Automation Server\Setup SERVER_URL REG_SZ


Troubleshooting

This section provides troubleshooting information for the XIA Automation Server.


Diagnostics

The diagnostics section allows for the configuration of logging on the XIA Automation Server. To access this section 1. Open the XIA Automation Client Tools 2. Press Server Configuration in the bottom left 3. Select Diagnostics in the tree view on the left

Logging Enabled Displays whether logging is currently enabled on the XIA Automation Server. Log File Displays the absolute path to the current log file on the XIA Automation Server. Toggle Logging Enables or disabled logging on the XIA Automation Server. By default, logging is disabled. View Log File Opens the log file for viewing - this can be used when the client tools are being run remotely on a different machine to the XIA Automation Server.

Enable Diagnostics Manually

Diagnostics logging can be enabled manually in the web.config file to allow logging to commence immediately when the XIA Automation Server is started without the need to connect the client tools. To enable logging manually

• Open the web.config file by default this is found in C:\Program Files\CENTREL Solutions\XIA Automation Server\Server\Web.config

• Locate the following section in the configuration file <system.diagnostics>

<trace autoflush="true"> <listeners> <clear/>  </listeners> </trace> </system.diagnostics>

• Remove the comments so that the section resembles the following <system.diagnostics>

<trace autoflush="true"> <listeners> <clear/> <add name="TextTracer" type="System.Diagnostics.TextWriterTraceListener, System, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="app_data\logs\trace\xiaautomation.log"/> </listeners> </trace> </system.diagnostics>

• Restart the XIA Automation Server

• By default, the log file will be written to the following location C:\Program Files\CENTREL Solutions\XIA Automation Server\Server\App_Data\Logs\Trace\xiaautomation.log


HTTP Error 401 - Unauthorized access

Error "HTTP Error 401 - Unauthorized access" Issue When you connect to XIA Automation Server with an account other than an administrator, you may see the error "HTTP Error 401 - Unauthorized access". Cause This can be caused by the user account not having permissions to access the site. Solution Ensure that the user is a member of the "XIA Automation Server Users" local or domain group.


HTTP Error 401.2 - Unauthorized

Error "HTTP Error 401.2 - Unauthorized. You are not authorized to view this page due to invalid authentication headers." Issue When you connect to XIA Automation Server, you receive an error “HTTP Error 401.2 - Unauthorized. You are not authorized to view this page due to invalid authentication headers.”

The user account you are connected with is known to have the appropriate permissions. Cause This is due to problems with the configuration of the authentication settings within IIS Solution

• Open IIS Manager then select the XIA Automation virtual directory and double click the Authentication icon.


• Ensure that Windows authentication is enabled then right click it and select Providers

• Ensure that both Negotiate and NTLM are in the list of Enabled Providers. If they are not listed select them from the available providers drop down list and click add.


Only system administrators can perform this action

Issue When you open the Client Tools you receive the error message "Only system administrators can perform this action" even though you are logged in as a local administrator. Cause This can be caused by the wrong authentication settings being configured in the IIS virtual directory. Solution

• Open the Internet Information Services (IIS) Manager tool

• Browse to the XIA Automation virtual directory

• Ensure that "Anonymous Authentication" is disabled, and that only "Windows Authentication" is enabled.


You are prompted for a password when you attempt to

access the XIA Automation Server Web Interface.

Issue When using Vista or Windows 2008 or above, you find you are prompted for a password by the browser even though the system is configured with Windows Authentication. Clicking cancel displays an Unauthorized error message.

Cause This is caused by the local server not being in your Intranet Zone and therefore the browser is not passing your current credentials to the XIA Automation Server.


Solution

• Add the XIA Automation Server URL to your Intranet Zone in Internet Options

• Ensure that access to the XIA Automation Server is not being routed via a proxy server.

• When using the Firefox web browser, please see the following article Using Integrated Authentication with Firefox.


Web Interface

Users access XIA Automation Server through a web interface. The shortcut to the web interface is automatically created in the start menu.


Form Input

Form input allows the user to execute an automation profile using a standard web form.


To access the input form directly without the full user interface, provide the user with the url: http://localhost/xiaautomation/inputform.aspx?ProfileID=23edf67a-8914-413f-845e-9b144ba72516 Replacing the address with that of the XIA Automation Server and the profile ID with the profile you wish to display.


The profile ID can be obtained from the XIA Automation Client tools by selecting the automation profile.

Profiles are only displayed on the form input user interface when the following conditions are true:

• The user has permissions to execute the automation profile

• The profile is enabled

• The profile contains at least one automation task


CSV Input

CSV input allows the mass execution of automation profiles using a comma separated volume (.csv) file.

• Create a CSV file with the required values


• Click the browse button and browse to the CSV file

• Click the upload file link

• When the file has been uploaded validate the fields are correctly assigned to the correct column

• Any errors detected in the CSV file will be highlighted, these errors should be corrected in the CSV and the file uploaded again before the automation process can continue.

• Click Next to initiate the automation process for all users.


Note: Profiles are only displayed on the CSV input user interface when the following conditions are true

• The user has permissions to execute the automation profile

• The profile is enabled

• The profile contains at least one automation task

• The profile contains at least one variable

xia automation server - it-administrator...page 9 of 291 xia automation server prerequisites...

Documents