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 On Demand Migration 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.
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:
- 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.
Please Note: The computer must be rebooted for the applied group policy to complete the agent installation.
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.
Please Note:A newly applied group policy will not immediately be displayed.
The Computer Settings section displays the applied group policy, but the agent installation is not completed until the computer is rebooted.
Please Note: If using the agent Auto-Upgrade feature and deployment software that uses MSI ProductCode based detection, the Auto-upgrade feature should be disabled after initial deployment or the detection method should verify via a folder path.
What are the Repositories?
Repositories are storage locations (network shares) which you configure on your network used for four specific job types: Agent Logs, Custom Downloads, Offline Domain Join, and Microsoft Entra Device Join. These job types access or create files in the defined locations. If you are not using these job types you do not need to configure Repositories.
How do I manage Repositories?
Repositories are managed from the Repositories section of the Configurations page. There you can view and copy the currently defined share path for each job type. You can update and save the configuration. Make sure that the defined network share path is routable from the devices being migrated.
What can I do with a Repository?
Repositories are used to locate files for four job types:
- Agent Logs – Agent logs are maintained on individual workstations. To centralize them so that review does not require logging into each machine, the Upload Logs Action can be applied to the Devices of interest. This will create a copy of the Device’s logs in the defined network share.
-
Custom Downloads – Custom Actions with a Download File Task can be used to download a specified file from the defined network share to the workstation. A common use of this job type is distributing a new VPN client to workstations after Cutover.
A Custom Download Repository should not be used with the Offline Domain Join Action type when configuring custom actions.
-
Microsoft Entra Bulk Enrollment – The Microsoft Entra ID Cutover Action relies on access to an Azure bulk enrollment package which has been created by a client administrator using the Windows Configuration Designer as described in the Microsoft Entra Device Join Quick Start Guide.