XIA Automation Server

Transcription

1 Administrator's Guide Version: 3.1 Copyright 2017, CENTREL Solutions

2 Table of contents About... 6 Installation... 7 Installation Requirements (Server)... 8 Prerequisites (Windows 2016 / 2012)... 9 Prerequisites (Windows 2008) Prerequisites (Windows 2003) Installation Requirements (Client) Installation Process Authentication Using Integrated Authentication with Firefox Logging Out Client Tools Connecting to Server Configuration Branding Server Configuration Dialog Security Tab Branding Tab Default Branding Tab Mobile Branding Tab SMTP Settings Tab Import Tab Licensing Install a license file Account Browser Object Types Dialog Locations Dialog Automation Profiles Creating an Automation Profile Automation Profile Properties General Tab Help Text Tab Access Control Variables General Tab Instance Locator System Variables Standard Variables Boolean Variable DateTime Variable Numeric Variable List Variable Text Variable Dynamic Variables Active Directory Search Variable Dynamic Plugin Variable SQL Server Dynamic Variable Page 2 of 292

3 Automation Tasks General Tab (Common) Input and Using Variables Active Directory Tasks Account Unlock Task Task Settings Tab Account Creation Task Account Naming Settings Tab Contact Tab Address Tab Account Name Tab Account Tab Profile Tab Behaviour Output Variables Tab Remote Desktop Services Profile Tab Member of Tab Telephones Tab Organization Tab Remote Control Tab Custom Attributes Tab Directory Tab Group Creation Task Requirements Group Tab Scope Tab Members Tab Behaviour Tab Custom Attributes Tab Directory Tab Troubleshooting Password Reset Task Task Settings Tab Organizational Unit Creation Task Settings Tab Address Tab Custom Attributes Tab Directory Tab Troubleshooting Active Directory Tasks A constraint violation occurred. (exception from hresult: 0x f) An invalid dn syntax has been specified Could not find the name or insufficient right to see name Exception from HRESULT: 0x Failed to modify the group membership of the user. The object already exists Failed to modify the group membership of the user. There is no such object on the server The attribute syntax specified to the directory service is invalid The requested operation did not satisfy one or more constraints Custom Attributes Directory Settings Special Characters Development Tasks Page 3 of 292

4 Execute a Plugin Task Task Settings Tab Create a Plugin Execute Custom Code Task Task Settings Tab Custom Code Editor Google Account Tasks Preparing for automation (Part 1 - Developers Console) Preparing for automation (Part 2 - Admin Console) Google Connection Settings Create or Update Google Account Task Task Settings Tab Behaviour Tab Connection Settings Tab Delete Google Account Task Task Settings Tab Connection Settings Tab Troubleshooting Error connecting to Google online services. Bad request Error connecting to Google online services. Could not find file Error connecting to Google online services. Not a valid Error connecting to Google online services. The specified network password is not correct Exchange Tasks Mailbox Enable Task Exchange Version Tab Settings Tab (Exchange 2003) Settings Tab (Exchange 2007) Settings Tab (Exchange 2010) Settings Tab (Exchange 2013) Troubleshooting File and Directory Tasks Directory Creation Task Directory Settings Tab Sharing Tab Security Tab Output Variables Tab Directory Copy and Move Tasks Directory Settings Tab File Writer Task File Settings Tab Office 365 Tasks Requirements Office 365 Connection Settings Create or Update Office 365 Account Task Task Settings Tab Licenses and Location Tab Behaviour Tab Troubleshooting Could not load the "Azure Active Directory Module for Windows PowerShell" Utility Tasks Page 4 of 292

5 Pause Task Task Settings Tab Send Task Task Settings Tab CC Addresses Tab Start Application Task Task Settings Tab Variable Tasks Copy Variable Task Copy Settings Tab Password Generator Task Password Settings Tab Minimum Characters Tab Allowed Characters Tab Date Modification Task DateTime Settings Tab Modify a String Task Task Settings Tab Variable Substring Task Task Settings Tab Variable Task Example - Determine First Initial Reference Changing the service account password Task Orchestrator Scheduler Service Automatically Importing Files Polling Interval Diagnostics Logs Server URL Configuration Troubleshooting Diagnostics Enable Diagnostics Manually HTTP Error Unauthorized access HTTP Error Unauthorized Only system administrators can perform this action You are prompted for a password when you attempt to access the Web Interface Web Interface Form Input CSV Input Page 5 of 292

6 About ( 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 '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. 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 Page 6 of 292

7 Installation This section describes the installation process of. Download the latest installation package: 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. Page 7 of 292

8 Installation Requirements (Server) This section describes the requirements for the installation of. Requirements The following operating systems are supported for the installation of the : 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 v 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 Browser Requirements The following web browsers are supported for accessing the : Chrome Firefox Microsoft Edge Internet Explorer 11, 10, 9, 8 Safari Android Page 8 of 292

9 Prerequisites (Windows 2016 / 2012) In Server Manager, ensure that the Microsoft.NET Framework 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) Page 9 of 292

10 Prerequisites (Windows 2008) For Windows 2008 (not R2), download and install the Microsoft.NET Framework if not already installed For Windows 2008 R2, In Server Manager, ensure that the Microsoft.NET Framework Feature is installed: Page 10 of 292

11 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) Page 11 of 292

12 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. In the example, xiaserver is used however any valid value can be used. Page 12 of 292

13 Enter the IP address of the 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 Page 13 of 292

14 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. Page 14 of 292

15 In the IIS Management Console, ensure that the ASP.NET v extension is installed and set to Allowed: More information can be found in the following Microsoft support article - please note that the steps to execute setspn.exe are automatically performed by the installer. Page 15 of 292

16 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 2016 Windows Server 2012 R2 Windows Server 2012 Windows Server 2008 R2 Windows Server 2008 Windows Server 2003 Windows XP / Vista / 7 / 8 / 10 Microsoft.NET 3.5 Page 16 of 292

17 Installation Process Ensure that all of the prerequisites have been completed for the target operating system. Download and execute the installer (this installs on both 32bit and 64bit): You must agree to the End User License Agreement (EULA) to continue: Page 17 of 292

18 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. Page 18 of 292

19 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 For Windows 2008 and above this will be Page 19 of 292

20 Enter the credentials required to run the. This account must have sufficient access rights to perform the tasks configured on the. 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. Page 20 of 292

21 Click Validate to validate the credentials. Select the installation folder Click Install when ready. Page 21 of 292

22 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. Page 22 of 292

23 Ensure that the web interface loads correctly. If you are prompted for credentials when using Internet Explorer, ensure that the URL is configured within the Local Intranet zone. Page 23 of 292

24 Authentication 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 for external access. Users are prompted for credentials when they access the 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 " Users" local or domain group. Page 24 of 292

25 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 Page 25 of 292

26 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 Note: Do not enter the full URL - for example for the URL " SRV01/xiaautomation" enter only " 5. Restart the browser when ready Page 26 of 292

27 Logging Out 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 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 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. Page 27 of 292

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

29 Connecting to To connect the, enter the address in the server field and click connect. Page 29 of 292

30 For more options, click the options action point to display all connection options Server The base address of the. Use Default Credentials The system will connect to the 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. Page 30 of 292

31 Server Configuration This section describes the server configuration settings. To access the server configuration: Connect to the using the client tools Select the server configuration navigation bar item Click the Server Configuration action point to display the Server Configuration Dialog. Page 31 of 292

32 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. Page 32 of 292

33 Server Configuration Dialog This section describes the options available on the server configuration dialog window. Page 33 of 292

34 Security Tab The security tab allows the configuration of the administrators of this. 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 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". Page 34 of 292

35 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. Page 35 of 292

36 Description The description to display on the home page Page 36 of 292

37 Default Branding Tab The default branding tab allows the configuration of the image to display on the home page for nonmobile 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. Page 37 of 292

38 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. Page 38 of 292

39 SMTP Settings Tab The SMTP settings tab configures the global SMTP settings to use when sending 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 address from which messages are sent. Use Default Credentials Connections to the SMTP server use the current credentials of the service account. Use Specific Credentials Uses the specified credentials when making a connection to the SMTP server. Page 39 of 292

40 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. Page 40 of 292

41 Licensing must be provided with a valid trial or production license. To obtain a trial license please visit 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. Page 41 of 292

42 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. Page 42 of 292

43 Account Browser The account browser allows for the selection of user, group and computer accounts accessible to the. The accounts and locations displayed are those accessible to the 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 Page 43 of 292

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

45 Object Types Dialog The object types dialog allows the selection of the object types to display in the Account Browser. Page 45 of 292

46 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 Page 46 of 292

47 Automation Profiles An Automation Profile allows automation tasks to be executed by the - 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. Page 47 of 292

48 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. Page 48 of 292

49 Automation Profile Properties To access the properties of an automation profile right click the profile in the treeview and select "Properties". Page 49 of 292

50 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. Page 50 of 292

51 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. Page 51 of 292

52 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 " 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" Page 52 of 292

53 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. Page 53 of 292

54 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. Page 54 of 292

55 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. Page 55 of 292

56 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. Page 56 of 292

57 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. Page 57 of 292

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

59 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 Page 59 of 292

60 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. Page 60 of 292

61 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. Page 61 of 292

62 Boolean Variable The boolean variable allows the ability to request that the user selects a boolean (true or false) value. Page 62 of 292

63 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. Page 63 of 292

64 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 Clears the currently selected date Page 64 of 292

65 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. Page 65 of 292

66 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. Page 66 of 292

67 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. Page 67 of 292

68 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. Page 68 of 292

69 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. Page 69 of 292

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

71 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. Page 71 of 292

72 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. Page 72 of 292

73 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. Page 73 of 292

74 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. Page 74 of 292

75 Text Variable The text variable allows the user to input a text based values and passwords. Page 75 of 292

76 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 Page 76 of 292

77 Text Mode - Password Note: When using password fields, it is recommended that users are required to use HTTPS to connect to the. 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. Page 77 of 292

78 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. Page 78 of 292

79 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. Page 79 of 292

80 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. Page 80 of 292

81 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. Page 81 of 292

82 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 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 Page 82 of 292

83 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. Page 83 of 292

84 Simulation Tab The simulation tab allows the specified settings to be tested by the and the values displayed in the dialog window. Execute Clicking execute will request that the execute the dynamic variable and display the results. Page 84 of 292

85 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. Page 85 of 292

86 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. Page 86 of 292

87 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. Page 87 of 292

88 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."); Page 88 of 292

89 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. Page 89 of 292

90 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; Page 90 of 292

91 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. Page 91 of 292

92 Simulation Tab The simulation tab allows the specified settings to be tested by the and the values displayed in the dialog window. Execute Clicking execute will request that the execute the dynamic variable and display the results. Page 92 of 292

93 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. Page 93 of 292

94 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. Page 94 of 292

95 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 service account. Use Specific Credentials Uses SQL authentication to connect to the SQL Server with the specified SQL login credentials. Page 95 of 292

96 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. Page 96 of 292

97 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 Page 97 of 292

98 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. Page 98 of 292

99 Simulation Tab The simulation tab allows the specified settings to be tested by the and the values displayed in the dialog window. Execute Clicking execute will request that the execute the dynamic variable and display the results. Page 99 of 292

100 Automation Tasks Automation tasks are the actual tasks to be performed by the. 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 Page 100 of 292

101 Complete the required fields for that automation task when prompted Page 101 of 292

102 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. Page 102 of 292

103 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. Page 103 of 292

104 Input and Using Variables Inserting Variables Nearly all text fields within 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. Page 104 of 292

105 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. Page 105 of 292

106 Active Directory Tasks This section provides information relating to tasks that modify Active Directory. Page 106 of 292

107 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. Page 107 of 292

108 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. Page 108 of 292

109 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 Server 2012 Windows 2000 Server Windows Server 2008 R2 Windows Server 2008 Windows Server 2003 R2 Windows Server 2003 Page 109 of 292

110 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. Page 110 of 292

111 The common name is shown in search results. Page 111 of 292

112 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. Page 112 of 292

113 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. Page 113 of 292

114 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. Page 114 of 292

115 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. Configures the address for this user. Web Page Configures the web page assigned to this user. Page 115 of 292

116 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. Page 116 of 292

117 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. Page 117 of 292

118 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" Page 118 of 292

119 Complete the required template fields on the General Tab and the Numbering Tab. Page 119 of 292

120 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 Description Allows an administrator only visible description to be defined for this account naming template. Page 120 of 292

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

122 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. Page 122 of 292

123 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. Page 123 of 292

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

125 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. Page 125 of 292

126 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. Page 126 of 292

127 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 "tsmith01@demonstration.int" that was generated by the task should be stored. Page 127 of 292

128 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. Page 128 of 292

129 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. Page 129 of 292

130 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. Page 130 of 292

131 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. Page 131 of 292

132 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. Page 132 of 292

133 Custom Attributes Tab The custom attributes tab allows the configuration of Active Directory attributes that are otherwise not configurable within the interface. For more information see the Custom Attributes section. Page 133 of 292

134 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. Page 134 of 292

135 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. Windows 2000 Server Windows Server 2003 Windows Server 2003 R2 Windows Server 2008 Windows Server 2008 R2 Windows Server 2012 Page 135 of 292

136 Requirements Active Directory running on the following operating systems: Windows Server 2012 Windows Server 2008 R2 Windows Server 2008 Windows Server 2003 R2 Windows Server 2003 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. Page 136 of 292

137 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. Determines the address to assign to the group. Notes Determines the notes to assign to the group. Page 137 of 292

138 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. 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 Page 138 of 292

139 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. Page 139 of 292

140 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. Page 140 of 292

141 Custom Attributes Tab The custom attributes tab allows the configuration of Active Directory attributes that are otherwise not configurable within the interface. For more information see the Custom Attributes section. Page 141 of 292

142 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. Page 142 of 292

143 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. Page 143 of 292

144 "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: 0x ) 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 Domain and Forest Functional Levels Page 144 of 292

145 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. Page 145 of 292

146 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. Page 146 of 292

147 Organizational Unit Creation Task The account creation task is capable of creating and updating organizational units in domains running the following server operating systems. Windows Server 2012 Windows Server 2008 R2 Windows Server 2008 Windows Server 2003 R2 Windows Server 2003 Windows 2000 Server Page 147 of 292

148 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. Page 148 of 292

149 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 alpha-2 country code to assign to the organizational unit. Page 149 of 292

150 For more information about the ISO 3166 standard see the ISO web site: Page 150 of 292

151 Custom Attributes Tab The custom attributes tab allows the configuration of Active Directory attributes that are otherwise not configurable within the interface. For more information see the Custom Attributes section. Page 151 of 292

152 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. Page 152 of 292

153 Troubleshooting Active Directory Tasks This section highlights the possible issues that you may encounter with Active Directory based agents. Page 153 of 292

154 A constraint violation occurred. (exception from hresult: 0x f) The agent reports "A constraint violation occurred. (exception from hresult: 0x f)" 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: 0x F) 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. Page 154 of 292

155 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: Page 155 of 292

156 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: 0x ) 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. Page 156 of 292

157 Exception from HRESULT: 0x The agent reports "Exception from HRESULT: 0x " Symptoms When attempting to create or modify an Active Directory object, you receive the error: "Exception from HRESULT: 0x ". Cause The error 0x (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: 0x > CENTREL.XIA.Automation.Agents.AutomationAgentException: Error setting remote desktop services profile settings. Exception from HRESULT: 0x > System.Runtime.InteropServices.COMException (0x ): Exception from HRESULT: 0x at TSUSEREXLib.IADsTSUserEx.set_TerminalServicesProfilePath Page 157 of 292

158 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. Page 158 of 292

159 Failed to modify the group membership of the user. There is no such object on the server. The agent reports "Failed to modify the group membership of the user. There is no such object on the server." Symptoms When attempting to add a newly created Active Directory user account to a group, you receive the error "Failed to modify the group membership of the user. There is no such object on the server." Cause When you create a user account in a directory with more than one domain controller, the user account may not have replicated to all the domain controllers before an attempt is made to add that user to a group. Resolution Within the user account creation task, go to the Directory tab and select Replicate Active Directory or Ensure Active Directory Replication. You can also change Commit Immediately to True if you want every Active Directory setting change to be made immediately. Page 159 of 292

160 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: 0x B) 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. Page 160 of 292

161 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: 0x ) 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. Page 161 of 292

162 Custom Attributes Custom attributes allow the setting of Active Directory attributes that are otherwise not configurable within the interface. To create a new custom attribute: Right click within the list Select "New" and then the type of value you wish to create. Page 162 of 292

163 Configure the value as required Page 163 of 292

164 Both user and system variables are available for use Page 164 of 292

165 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 Page 165 of 292

166 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 / This character is not supported Groups Character Handling \ This character is not supported. / This character is not supported Page 166 of 292

167 Development Tasks This section provides information relating to development tasks. Page 167 of 292

168 Execute a Plugin Task Automation plugins allow for custom actions to be created and executed by. Unlike the custom code task plugins are written externally to 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: Automation Plugins Run under the context and privileges of the service account. Can modify the values of automation variables Can be written in VB.NET or C#.NET Page 168 of 292

169 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\\Server\app_data\plugins). Page 169 of 292

170 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. In the following example, the plugin is created using Visual Studio 2010 using the C# language. 1. Create a new Visual Studio project Page 170 of 292

171 2. Create a new Class Library using the C# or VB.NET language and the.net Framework Add references to the following files that can be found in the directory (by default C:\Program Files\CENTREL Solutions\\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 Page 171 of 292

172 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 Page 172 of 292

173 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 installation directory's plugins folder (by default C:\Program Files\CENTREL Solutions\XIA Automation Server\Server\app_data\plugins). Page 173 of 292

174 Execute Custom Code Task The custom code task allows for custom code to be created and executed by. Unlike the plugin task custom code is written internally using the 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 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 Page 174 of 292

175 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. Page 175 of 292

176 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 and returns any errors. Execute Code Compiles the specified code on the, executes the compiled code immediately and returns any errors. NOTE: Automation variables are not available when testing plug-ins through the dynamic code editor. Page 176 of 292

177 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. Page 177 of 292

178 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 trace log using the OnAgentStatusChange() method. OnAgentStatusChange ("The custom plugin in now starting..."); Information can be written to the 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); Page 178 of 292

179 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."); Page 179 of 292

180 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. Page 180 of 292

181 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"; } } } Page 181 of 292

182 Google Account Tasks This section provides information relating to Google account related tasks. For more information about Google please see the Google web site Before the automation tasks can be executed you must follow the steps in the Preparing for automation section. Page 182 of 292

183 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. Click "Create Project" Enter the project name "" Select APIs and auth > APIs Enter "Admin SDK" in the search field Page 183 of 292

184 Select the API and click Enable API Select APIs and auth > Credentials Select Add Credentials > Service account Page 184 of 292

185 Select P12 and click Create Save the file that is created on the 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" Page 185 of 292

186 Select the newly created service account from the list Make a note of the Client ID and address Page 186 of 292

187 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 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. Page 187 of 292

188 Click Authorize Page 188 of 292

189 Google Connection Settings The connection settings determine the credentials required to connect to the Google online services for your domain. Delegated User The address of the administrative user in the Google domain as whom the actions will be performed. Service Account The 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". Page 189 of 292

190 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). Page 190 of 292

191 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 Address The user's primary address - for example "sjones@centrel-solutions.com". 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. Page 191 of 292

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

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

194 Delete Google Account Task The Delete Google Account task is able to delete a Google account using a user's primary address or unique identifier. 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). Page 194 of 292

195 Task Settings Tab Account Name The name of the Google account to be deleted. This can be the user's primary 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. Page 195 of 292

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

197 Troubleshooting This section provides common troubleshooting steps for the Google Account Tasks. 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). Page 197 of 292

198 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 has been entered incorrectly in the Google Connection Settings section. Solution Ensure that the Service Account has been entered correctly in the Google Connection Settings section. The service account must be exactly that which was created in Preparing for automation (Part 1 - Developers Console). Page 198 of 292

199 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. Page 199 of 292

200 Error connecting to Google online services. Not a valid . The agent reports "Error connecting to Google online services. Not a valid ." 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 ." Cause This can be caused when the Delegated User 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 field in the Google Connection Settings section. Page 200 of 292

201 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). Page 201 of 292

202 Exchange Tasks This section provides information relating to Microsoft Exchange server tasks. For more information about Microsoft Exchange please see the Microsoft web site: Page 202 of 292

203 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. Page 203 of 292

204 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. Page 204 of 292

205 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: 0x ). For more information see: Page 205 of 292

206 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. Page 206 of 292

207 Page 207 of 292

208 Settings Tab (Exchange 2007) 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. Page 208 of 292

209 Settings Tab (Exchange 2010) 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). Page 209 of 292

210 Settings Tab (Exchange 2013) 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). Page 210 of 292

211 Troubleshooting This section highlights the possible issues that you may encounter with this agent and suggested solutions. Page 211 of 292

212 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. 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. Page 212 of 292

213 There is no such object on the server. (Exception from HRESULT: 0x ) Error "There is no such object on the server. (Exception from HRESULT: 0x )" 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: 0x )". 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. Page 213 of 292

214 File and Directory Tasks This section provides information relating to tasks that modify the file system. Page 214 of 292

215 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: Windows Server 2012 Windows Server 2008 R2 Windows Server 2008 Windows Server 2003 R2 Windows Server 2003 Windows 2000 Server Page 215 of 292

216 Directory Settings Tab 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. Page 216 of 292

217 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 Page 217 of 292

218 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. Page 218 of 292

219 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. Page 219 of 292

220 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. Page 220 of 292

221 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. Page 221 of 292

222 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. Page 222 of 292

223 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. Page 223 of 292

224 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. Page 224 of 292

225 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. Page 225 of 292

226 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: Windows Server 2012 Windows Server 2008 R2 Windows Server 2008 Windows Server 2003 R2 Windows Server 2003 Windows 2000 Server Page 226 of 292

227 Directory Settings Tab 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 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 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. Page 227 of 292

228 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. Page 228 of 292

229 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: Windows Server 2012 Windows Server 2008 R2 Windows Server 2008 Windows Server 2003 R2 Windows Server 2003 Windows 2000 Server Page 229 of 292

230 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. Page 230 of 292

231 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: Before the automation tasks can be executed you must follow the steps in the Requirements section. Page 231 of 292

232 Requirements Microsoft Office 365 is managed by 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 Page 232 of 292

233 Complete the installation Download the Azure Active Directory Module for Windows PowerShell (64-bit version). Execute the installer, reviewing the terms Page 233 of 292

234 Review the installation location and click Next Complete the installation Page 234 of 292

235 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 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. Page 235 of 292

236 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. Page 236 of 292

237 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 "test.user@centrel-solutions.com". The domain name must be valid. Change Password at Next Logon Determines whether the user is required to change their password at next logon. Page 237 of 292

238 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. Page 238 of 292

239 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. Page 239 of 292

240 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. Page 240 of 292

241 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. Page 241 of 292

242 Utility Tasks This section provides information relating to utility tasks. Page 242 of 292

243 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. Page 243 of 292

244 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. Page 244 of 292

245 Send Task The send task is capable of sending an 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. Page 245 of 292

246 Task Settings Tab The task settings tab allows the configuration of the addresses, subject and message body for the . To Address(es) Determines the addresses to which the 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. Page 246 of 292

247 CC Addresses Tab The CC addresses tab allows the configuration of CC and BCC addresses to which the should be sent. CC Address(es) Determines the addresses to which the should be CC (carbon copied), one per line or separated by semicolons. BCC Address(es) Determines the addresses to which the should be BCC (blind carbon copied), one per line or separated by semicolons. Page 247 of 292

248 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 service account. Page 248 of 292

249 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. 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. Page 249 of 292

250 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. Page 250 of 292

251 Variable Tasks This section provides information relating to variable modification tasks. Variables can also be modified using the Execute Custom Code Task. Page 251 of 292

252 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. Page 252 of 292

253 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. Page 253 of 292

254 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. Page 254 of 292

255 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. Page 255 of 292

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

257 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. Page 257 of 292

258 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. Page 258 of 292

259 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. Page 259 of 292

260 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. Page 260 of 292

261 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. Page 261 of 292

262 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. Page 262 of 292

263 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. Page 263 of 292

264 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. Page 264 of 292

265 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. Page 265 of 292

266 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. Page 266 of 292

267 Reference This section provides a technical reference for the product. Page 267 of 292

268 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. Page 268 of 292

269 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. Page 269 of 292

270 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 Page 270 of 292

271 Scheduler Service The 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. Page 271 of 292

272 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 installation, by default this can be found here: C:\Program Files\CENTREL Solutions\\Server\App_Data\Import View the properties of the automation profile you wish to automate in the Client Tools and note the profile identifier Page 272 of 292

273 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. Page 273 of 292

274 Polling Interval By default, the Scheduler Service automatically polls the 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. Page 274 of 292

275 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 Scheduler\Logs\Trace\trace.log. Page 275 of 292

276 Server URL Configuration The Scheduler Service automatically polls the URL of the 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\\Setup SERVER_URL REG_SZ Page 276 of 292

277 Troubleshooting This section provides troubleshooting information for the. Page 277 of 292

278 Diagnostics The diagnostics section allows for the configuration of logging on the. 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. Log File Displays the absolute path to the current log file on the. Toggle Logging Enables or disabled logging on the. 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. Page 278 of 292

279 Enable Diagnostics Manually Diagnostics logging can be enabled manually in the web.config file to allow logging to commence immediately when the 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\\Server\Web.config Locate the following section in the configuration file <system.diagnostics> <trace autoflush="true"> <listeners> <clear/> <!-- <add name="texttracer" type="system.diagnostics.textwritertracelistener, System, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089" initializedata="app_data\logs\trace\xiaautomation.log"/> --> </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= , Culture=neutral, PublicKeyToken=b77a5c561934e089" initializedata="app_data\logs\trace\xiaautomation.log"/> </listeners> </trace> </system.diagnostics> Restart the 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 Page 279 of 292

280 HTTP Error Unauthorized access Error "HTTP Error Unauthorized access" Issue When you connect to with an account other than an administrator, you may see the error "HTTP Error 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 " Users" local or domain group. Page 280 of 292

281 HTTP Error Unauthorized Error "HTTP Error Unauthorized. You are not authorized to view this page due to invalid authentication headers." Issue When you connect to, you receive an error HTTP Error 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. Page 281 of 292

282 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. Page 282 of 292

283 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. Page 283 of 292

284 You are prompted for a password when you attempt to access the 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. Page 284 of 292

285 Solution Add the URL to your Intranet Zone in Internet Options Ensure that access to the is not being routed via a proxy server. When using the Firefox web browser, please see the following article Using Integrated Authentication with Firefox. Page 285 of 292

286 Web Interface Users access through a web interface. The shortcut to the web interface is automatically created in the start menu. Page 286 of 292

287 Form Input Form input allows the user to execute an automation profile using a standard web form. Page 287 of 292

288 To access the input form directly without the full user interface, provide the user with the url: Replacing the address with that of the and the profile ID with the profile you wish to display. Page 288 of 292

289 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 Page 289 of 292

290 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 Page 290 of 292

291 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. Page 291 of 292