If you are following along in this guide, after performing Step One the Devices from your source Environment should now be visible in the Not Ready Devices tab on the Active Directory Devices + Servers page. The way Devices move from the Not Ready Devices tab to the Ready Devices tab is by having a Active Directory agent installed on them and communicating with the Active Directory server.
The Active Directory agent will need to be installed on each Device which is to be migrated.
The Agent installer msi file can be downloaded from the Downloads section of the Active Directory Configurations page. Installing the agent will also require the values of the Service URL and Auth Key which are listed in the same page in Active Directory below the download button.
An example PowerShell command to install the agent would be:
msiexec.exe /I 'C:\workspace\AD.Agent-188.8.131.521.msi' SERVICEURL=https://us.odmad.quest-on-demand.com /api/ADM AUTHKEY=##################################################################
Run this command to invoke the installer UI. Walk through the screens filling out the needed information and click finish when completed. The settings for using a customer web proxy for communications are optional and can be left blank for the purposes of this guide.
As needed the installer can also be invoked in quiet mode with the /QN switch (requires running PS as admin). The fields which can be populated when included as command line arguments to the installer are SERVICEURL and AUTHKEY. Additionally, it is possible to configure the agent to use a web proxy using command line arguments as well. They are beyond the scope of this guide but listed here for info: WEBPROXYENABLE (optional), WEBPROXYURL (optional), WEBPROXYPORT (optional), WEBPROXYUSER (optional), and WEBPROXYPASS (optional).
The agent communicates with the Active Directory server over three outbound ports: TCP 443/80 and UDP 3030. When in web proxy mode the agent will communicate to the proxy on the defined port and outbound to the internet on TCP 443/80 only, UDP over port 3030 is not used when using a web proxy
The agent uses .Net framework 4.5.2 and will download it on install if it is not present and an internet connection is available.
Agent communications – To avoid overload, each workstation agent will communicate with our server at specific random and uniformly distributed intervals. On startup an agent will first register with the server within four hours. Thereafter a running agent will check for work by calling our job availability cache once every two minutes over UDP port 3030. Note that in the product UI the ‘Agent Last Contact’ column relates to the TCP communications not to the UDP communications, so do not expect it to update every 2 minutes. There is a per client limit of 600 agent jobs which will be available to agents per two-minute interval. If an agent has a job queued it will then connect over https to retrieve the job. As a fallback for this the agent will also connect by https once every four hours even if a job has not been available in the job availability cache.
Wait up to four hours for initial registration. While you are waiting for this initial communication can be a good time to read ahead and get a head start on Step Three: Set up Active Directory Profiles and Configurations.
Now that you have installed the Active Directory agent on a Device you wish to migrate and waited up to the initial four hours for it to register, you should see that Device move from the Not Ready Devices tab over to the Ready Devices tab in Active Directory. If you do not see this transition take place troubleshoot the network connectivity for agent communications and check the logs from the agent locally on the device.
Now that Directory Sync is configured and the Active Directory agent is installed on the device to migrate you can proceed with configuring the profiles and configurations.
Profiles: Profiles are groups of related settings and options related to the device migration. There are six kinds of profiles in Active Directory: Migration, Network, Device ReACL, File Share ReACL, Credentials, and Credential Cache.
For the minimum purposes of this guide we will not need to set up a File Share ReACL profile, Credentials profile, or a Credential Cache profile.
Migration Profile - Migration Profiles contain common device cutover settings used to manage the domain join process.
Network Profile - Network Profiles contain common network adapter settings that need to be updated during the device’s migration to the new domain.
Device ReACL Profile - Device ReACL Profiles contain common settings to manage updating permissions of Windows workstations and servers prior to migration.
The Migration, Network, and Device ReACL profiles have a default profile available. Review the settings on the default profiles and determine if you need to create your own new profiles which have different settings.
Configurations: New in Active Directory are the Configurations page and sections.
Downloads: You should already have seen the Downloads page when downloading the agent. This is the only Configuration section which will apply to this simple guide. Also, on the Downloads page is the setting for the agent auto-upgrade feature for your whole project. This is one of the best new features which will ensure that if a new version of the agent is released, your agents will be updated automatically. If necessary, you can also disable this setting.
The Repositories page defines storage locations for certain migration jobs which require local storage of files. These job types are ‘Upload Logs’, ‘Download File’, and ‘Offline Domain Join’. For the purposes of this guide none of these locations will need to be defined, but they will be very important should you proceed to using their related jobs.
Custom migration Actions and their constituent Tasks are organized in a similar system to the Active Directory Pro product. Click ‘Show System’ to view the standard Actions which come with the product and then copy them if you want to edit them or create your own. For this guide we are only using the system actions, but here is where you would customize your own as needed.
Variables is a section for defining global variables to be made available to scripts running as part of Custom Tasks and Actions.
If you have proceeded this far in setting up Profiles and Configurations while waiting for initial agent registration, you will need to pause here until that step is completed. Otherwise you are ready to proceed to performing migration activities.
Once Profiles and Configuration have been set up you can proceed to migration activities.
Before or while performing migration activities it may be helpful to organize and partition the list of devices to be migrated by using the Migration Waves feature. To assign devices to a migration wave for grouping select devices in the Ready Devices tab and then select the ‘Add to Migration Wave’ action from the drop down and click the Apply Action button. You can also manage Migration Waves by going directly to the Waves page from the left menu. A powerful tool for tracking devices and statuses throughout the migration is combining the defined migration waves with the Ready Devices table filters.
The simplest migration activities flow consists of applying a ReACL action followed by a Cutover action. This is the flow we will follow in this guide.
Before working with the devices, ensure that the users related to the device you are going to migrate have already been matched in the target in Directory Sync. This will allow the ACLs to be updated correctly for use in the target by the ReACL process. Remember that if those users were created by your Workflow you will need to run the workflow a second time in order to read them back into the database and finish the matching.
From the Active Directory Devices + Servers page on the Ready Devices tab select a device on which to perform a migration action. There are several useful actions in the Select Action dropdown which you can apply to that device. For this guide the first action we need to use is ReACL. Device ReACL is non-destructive and can be performed multiple times prior to the cutover event. After clicking to apply the action the ReACL Job Options dialog is displayed and you can enable ‘Do Not Start Before’ and choose a time in the future to start the job. Otherwise, it will be queued when you click Apply. Do not enable the option for now and click Apply.
Wait for the ReACL job to be picked up by the agent and for the job to complete. You can track the status as it updates in the Ready Devices table or from the product dashboard.
If you want to see what jobs are currently queued for a device or review the outcome of previous jobs for that device select the device from the Ready Devices table and then select and apply the ‘View Jobs’ action. For planning which User objects need to be migrated to the target prior to migrating the devices they are using, the ‘Show Profiles’ action is a helpful one to see which user profiles have logged into the device in question.
After the ReACL process has been completed successfully it is time to queue a Cutover action.
From the Ready Devices table select the device you just ReACLed on which to perform a cutover action. Select the Cutover action from the dropdown and click the Apply Action button. After clicking to apply the action the Cutover Job Options dialog is shown. You can select here to ignore the ReACL status of that device. The cutover action will error out and fail to queue it if the ReACL status of the device is not ‘Completed’ or chosen to be ignored. On this dialog you can also enable ‘Do Not Start Before’ and choose a time in the future to start the job. Otherwise, it will be queued when you click Apply. Choose that option for now.
Wait for the Cutover job to be picked up by the agent and for the job to complete. You can track the status as it updates in the Ready Devices table or from the main Product dashboard.
When the Cutover is completed inspect the workstation or server and ensure that things went as expected. When the entire project is completed the Cleanup action can also be run. Congratulations on
For more information about other topics visit the online help center.
Now that the first device(s) have been configured and migrated in Active Directory you are ready to progress to more planning and more involved migration scenarios. For instance, further information is available on Offline Domain Join and the related Credential Cache jobs should they meet the needs of your project scenario.
Learn more by visiting the On Demand Migration Active Directory User Guide.