Configurations
Actions
What are Actions and Tasks?
Actions are a sequence of Tasks to complete a process.
The Actions screen will allow you to create a new Custom Actions that can be performed against Accounts, Computers or File Shares. Existing or new tasks can be added to a the desired Custom Action and then ordered as necessary to complete the custom process.
It is important to note that System actions and tasks can only be viewed or copied, they are not editable.
How is an Action created or copied?
To add or copy an action: Below the table, click New or select an existing Custom Action and click Copy. Check Show System to view and select any existing Systemactions.
- Action Name (Required): Enter a name for the Custom Action. The Action Name must be unique.
- Action Display Name: Enter the name that appears in the Actions menu.
- Description: Enter a description for the action.
Action Target: Select one of the options from the drop-down list.
- Computer: The Action will appear in the Actions menu on the Computers screen.
- File Share: The Action will appear in the Actions menu on the File share screen.
Action Type: Select one of the options from the drop-down list. The Action Type determines what validations are applicable to the job, and which status columns are updated when the job runs. For example, a Custom Action with the ReACL type, will have the same validations as the System ReACL action.
- Other (default): An action not related to any System action. No predefined validations are applicable. By default, new Actions are assigned as type Other.
- Discovery: Gathers properties from the computer.
- Cutover: Moves a computer from the source domain to the new target domain.
- ReACL: Updates computer domain user profiles for use by the matching target user after cutover.
- ReACL Share: Updates the File Share’s domain user profiles for use by the matching target user after cutover.
- ReACL Rollback: Rolls back all changes made by the ReACLShare process.
- ReACL Rollback Share: Rolls back all changes made by the ReACL process.
- Cleanup: Removes the Source SIDs after the Cutover process completes.
- Cleanup Share: Removes the Source SIDs after the Cutover process completes.
- Explicit Rollback: Rejoins a computer back to the source domain.
- Upload Logs: Uploads log files from the Active Directory Pro Agent to the Active Directory Pro Server using Microsoft BITS.
How is a Task created or copied?
To add or copy a task: Below the Tasks table, click New or select an existing task and click Copy. Check Show System to view and select an existing Systemtask.
- Task Name (Required): Enter a name for the task. The Task Name cannot begin with "BT-" which is used to identify system tasks.
- Description: Enter a description for the menu action.
Task Type (Required): Select one of the options from the drop-down list.
- PowerShell Script: Allows you to define a PowerShell script for the process on the Command and Rollback screens. Global Variables can be added and used in the script.
- Command Line: Allows you to define a Command Line command for the process on the Command and Rollback screen. Global Variables can be added and used in the command line.
- Download File: Downloads a file to the predefined Downloads folder.
Automatic Rollback:
- Auto-Rollback On Error: if checked, automatic rollback on error is added to the task.
Include Variables For:
- Manage Credentials: if checked, the PowerShell script or Command Line command includes the $CutoverCredentials_XXXXX parameters.
- Network Profile Settings: if checked, the PowerShell script or Command Line command includes the $NetworkProfile_XXXXX parameters.
- Migration Profile Settings: if checked, the PowerShell script or Command Line command includes the $MigrationOption_XXXXX parameters.
- Global Variables: if checked, the PowerShell script or Command Line command includes the Global Variables.
- Script: Enter a PowerShell script or Command Line command. If creating a PowerShell script, click Load Script Framework to populate the entry box with the basic framework of a script. Enter or edit the Command Line command or PowerShell script. Text is required. The return value of the script or command will determine success or failure.
- Rollback: Enter a PowerShell script or Command Line command to run in case of failure/Rollback. Ideally this would undo the effects of the above script. If creating a PowerShell script, click Load Script Framework to populate the entry box with the basic framework of a script. Enter or edit the Command Line command or PowerShell script. Text is required. The return value of the script of command will determine success or failure.
- Task Timeout: For PowerShell script or Command Line command, enter the number of seconds the process will be attempted before timing out.
- Retry Count: For the PowerShell script or Command Line command, enter the number of times the process will be retried.
- Update Interval: For PowerShell script or Command Line command, enter the number of seconds between process runs.
File Download: Enter the following options if adding or copying a Download File task. When a new download job is created for a managed workstation, the specified file that is stored in the configured Custom Downloads Repository will be downloaded to c:\Program Files (x86)\Binary Tree\P365ActiveDirectoryAgent\Downloads\ on the workstation’s local disk.
- File Name (required): The file name. Based on the File Location for Download Jobs used during installation The File Name cannot contain invalid filepath characters and cannot use the following reserved file names: map.usr, map.gg, and ReACL-config.json.
- File Path: The target Location of the download job. The Target Location cannot contain invalid filepath characters and cannot use the following reserved file names: map.usr, map.gg, ReACL-config.json. A Target Location is required if the File Name contains environment variables.
The local download folder on an Active Directory managed machine will be secured with permissions only for the BUILTIN\Administrators group.
Note: If rights other than BUILTIN\Administrators are required then the administrator will need to make a change on the local downloads folder (c:\Program Files (x86)\Binary Tree\P365ActiveDirectoryAgent\Downloads\) on the Agent machine.
How is a Task added to an Action?
To add a Task to an Action: Select a Task in the Tasks table, select an Action in the Select Action drop-down menu and click the Add To button.
Under a given Action the Tasks are listed in the order in which they will be executed. Drag and drop tasks to reorder them. Tasks can be viewed, copied, or removed by selecting the tasks and clicking the appropriate button.
How do you activate an Action?
Only Actions marked as Active will appear in the Actions menus. Select an Action in the table and click the Disable or Enable button to change the active status of the Action. Inactive actions can be displayed in the table by clicking the Show Disabled button. You may want to create a new action, enable it, and then disable the corresponding System action.
Additional Information
Downloads
How are Mapping Files downloaded?
Use the Downloads page to generate the User Mapping File (Map.usr) and Group Mapping File (Map.gg). These files are automatically created during the ReACL process so the only time they need to be created manually is when re-permissioning SQL databases.
To create the mapping files:
- Click the Download button.
- Select the source and target environment and click Submit.
Use the browser options to open or save the mappings.zip file containing the User Mapping File (Map.usr) and Group Mapping File (Map.gg).
Note: Each time the Create Mapping Files process is run, the Map.usr and Map.gg files are overwritten.
Note, Use the Downloads page to generate the Active Directory and Exchange Processing Wizard Mapping Files. Additional detail for Active Directory and Exchange Processing Wizard Mapping Files can be found at Migration Manager for AD 8.15 - Resource Processing Guide (quest.com)
How are device agents downloaded?
To download a device agent:
- Select an available agent version from the drop-down menu.
- Click the Download button.
Use the browser options to save the agent installer package.
What are the Device Agent Service URL and Auth key used for?
The Device Agent Service URL and Auth Key as defined on the Downloads section of the Configurations page are provided to the Device Agents at install and allow them to connect to the correct customer’s Power365 project. They are unique to the agents in a given client and all agents of the same client should use the same values. If installing the agent from the command line without UI the arguments for providing the Service URL and Auth Key are their names in all uppercase i.e. SERVICEURL and AUTHKEY respectively.
How are device agents automatically upgraded?
To automatically upgrade the device agents:
- Click the Enable button at the bottom of the Device Agent section.
Installing the Active Directory Agent
Each Active Directory Computer (device) that will be migrated must have an agent installed on the workstation to orchestrate local jobs that must occur to prepare and execute the workstation’s domain move.
Refer to the Requirements for to verify all devices meet the requirements for agent installation.
The agent is available as an MSI package from the Downloads section of the Configurations page. You will also need the values of the Service URL and Auth Key found on that page.
You can install the agent by running the MSI manually on the device, with a PowerShell command, or in bulk by using a GPO or other third-party delivery method.
How do you manually install the Active Directory Agent?
- Download the Active Directory MSI file from the Downloads page.
- Copy the Active Directory MSI file to each computer.
- Double-click the file to open the installer.
On the Welcome screen, click Next.
On the License Agreement screen, accept the agreement and click Next.
On the Agent Registration screen, enter the Service URL and Authorization Key, found on the Downloads page, and then click Next.
On the Network Settings screen, if using a Web Proxy, check Use Web Proxy and enter the Web Proxy settings. Click Next.
On the Ready to Install the Program screen, click Install.
When the install completes, click Finish.
Note: Once the agent is installed and the service is running it will connect to the server within four hours. This delay is randomized and uniformly distributed to avoid overloading the server when large numbers of agents come online at the same time.
How do you install the Active Directory Agent using a PowerShell Command?
- Download the Active Directory MSI file from the Downloads page. The Service URL and Auth Key values also found on the Downloads page are required.
Create and run the PowerShell command with the required SERVICEURL (Service URL) and AUTHKEY (Auth Key) values.
Example:
msiexec.exe /I 'C:\workspace\AD.Agent-20.3.1.1401.msi' SERVICEURL=https://us.odmad.quest-on-demand.com/api/ADM AUTHKEY=################################################################## - Walk through the install wizard, filling out the needed information and click Finish when completed. The settings for using a customer web proxy for communications are optional.
As needed the installer can also be invoked in quiet mode with the /QN switch (requires running PowerShell as admin).
Additionally, it is possible to configure the agent to use a Web Proxy using the below command line arguments:
- WEBPROXYENABLE – Is a Web Proxy used? Values: Yes=1, No=0
- WEBPROXYURL – The Web Proxy Address
- WEBPROXYPORT – The Web Proxy Port
- WEBPROXYUSER – The optional Web Proxy Credentials Username
- WEBPROXYPASS – The optional Web Proxy Credentials Password
How do you install the Active Directory Agent using a GPO (Group Policy Object)?
To install the agent using a GPO you must convert the MSI package and the parameters into an MST file. One method to do this is using Microsoft Orca. Install Orca (available in Windows SDK Components for Windows Installer Developers). Orca will be used to create the necessary MST file.
Download the Active Directory Agent MSI file from the Downloads page.
Right-click on the MSI file and select Edit with Orca.
Once you have Orca opened, click on the Transform menu and select New Transform.
Next, navigate to the Property table and add the following:
- Add a Row with property of SERVICEURL and the Service URL value found on the Downloads page.
Add a Row with property of AUTHKEY and the Auth Key value found on the Downloads page.
Optionally, the following properties and values can also be added to configure the agent to use a Web Proxy:
- WEBPROXYENABLE – Is a Web Proxy used? Values: Yes=1, No=0
- WEBPROXYURL – The Web Proxy Address
- WEBPROXYPORT – The Web Proxy Port
- WEBPROXYUSER – The optional Web Proxy Credentials Username
- WEBPROXYPASS – The optional Web Proxy Credentials Password
- Click the Transform menu and select Generate Transform to complete the MST file creation. This MST file will be used in a later step.
- Right-click on the Active Directory Agent MSI, point to Share with, and click on specific people.
- Add a security group. The "authenticated users" group already includes all computers and is a good group to use. The group you add must have the shared Read permission and NTFS permission.
- Click Share.
- Click Done.
- From the Start menu, point to Administrative Tools and click on Group Policy Management.
- Right-click on the domain or OU you will be migrating and click on Create a GPO in this domain, and link it here.
- In the New GPO dialog box, enter a Name for the GPO and click OK.
- Click on the new GPO and click OK.
- Right-click on the GPO and select Edit.
- Open Computer Configuration > Policies > Software Settings and right-click on Software Installation and then point to New and click on Package.
- In the File Name field, enter the UNC path to the MSI file and click Open.
- Select the Active Directory Agent MSI file and click Open.
- In the Deploy Software window, select the Advanced deployment method and click OK.
- Under the Modifications tab, add the MST file you created earlier and click OK.
How do you verify the GPO?
- Log on to a workstation within the scope of the GPO using administrator credentials.
- From a command prompt on the workstation, run gpresult -r
- The Computer Settings section will display the applied group policy.
The Computer Settings section displays the applied group policy, but the agent installation is not completed until the computer is rebooted.