# Protected: Migrate your Macs to Hexnode with Hexnode Gateway The Hexnode Gateway application remotely migrates macOS devices from another UEM to Hexnode UEM without performing a device wipe. This document will guide you through the steps to seamlessly migrate your macOS devices to Hexnode UEM. Note:- [Configure the APNs certificate](https://www.hexnode.com/mobile-device-management/help/apns-settings/) before enrolling an Apple device. Migrate Mac to Hexnode UEM --------------------------- The Hexnode Gateway app can be installed by creating a configuration file from the Hexnode console and then deploying the PKG file to the devices. Follow these steps to migrate your Mac from another UEM to Hexnode. 1. Navigate to **Enroll > Platform-Specific > macOS > Migrate to Hexnode**. 2. If you have already generated the configuration file, skip to step 20. If not, click on **Generate a new Configuration File**. 3. Provide a suitable name for the configuration file under the **Configuration Name** field. ### Configure Gateway app settings 5. Enable the option **Enforce Hexnode Gateway app in full screen** to open the app in full screen. 6. Allow users to leave the full screen during migration enforced by the Gateway app by enabling the option **Allow user to exit full screen**. 7. Enable the option **Allow user to defer migration for a later time** to allow the user to defer the migration once for 30 min, 1 hour, 2 hour or tomorrow. In case the user selects ‘tomorrow’ under the **Allow user to defer migration for a later time** option, the migration will be attempted after 24 hours. ### Remove device from existing UEM automatically If the UEM profile on the device is non-removable, follow the steps below to automatically initiate disenrollment from the current MDM, or manually disenroll the device from the current MDM. 10. Click on **Remove device from existing UEM automatically** to remove the device from an existing UEM automatically. Upon selecting the option, additional fields will appear to specify the current MDM, UEM portal URL, and UEM API key. 11. Select the current UEM you are enrolled in using the **Specify the Current MDM** option. A dropdown will display a list of MDMs from which migration can be initiated, such as Jamf, VMWare Workspace One, Kandji, Addigy and Jumpcloud. 12. Specify the portal URL of your current UEM instance in the **portal URL** field. 13. Specify the API key of your current UEM instance in the **API key** field. ### Configure the selected UEM If Jamf is selected, in the portal fields: 1. Specify the portal URL of your Jamf instance in the **Portal URL** field. 2. Specify the “Client ID” and “Client Secret” of your Jamf instance in the required fields. To obtain the Client ID and Client Secret, complete the following steps in the Jamf portal: #### Create an API role 1. Navigate to **Settings > API Roles and Clients > API Roles** tab. 2. Click **New** and enter a display name. 3. Assign privileges: ***Read Computers*** and ***Send Computer Unmanage Command***. 4. Save the role. #### Create an API client 1. Navigate to **Settings > API Roles and Clients > API Clients** tab. 2. Click **New** and enter a display name. 3. Assign one or more API roles (client inherits all privileges). 4. Set **Access Token Lifetime** (in seconds). 5. Check **Enable API Client** option. 6. Save the client. #### Generate a Client Secret and Client ID 1. Open the created API client. 2. Click **Generate Client Secret > Create Secret**. 3. Copy and securely store the secret (it will only be shown once). 4. Copy the Client ID from the same page for later use in the Hexnode portal. If VMWare Workspace One, Kandji, Addigy, or Jumpcloud is selected: 1. Specify the portal URL of your current UEM instance in the **Portal URL** field. 2. Specify the API key of your current UEM instance in the **API key** field. ### Configure network settings 27. Wi-Fi configuration – Enable the option **Add Wi-Fi settings to configuration file** to configure the [Wi-Fi settings](https://www.hexnode.com/mobile-device-management/help/set-up-wifi-on-macos-using-hexnode-mdm/). 28. VPN configuration – Enable the option **Add VPN settings to configuration file** to configure the [VPN settings](https://www.hexnode.com/mobile-device-management/help/configure-vpn-on-macos-using-hexnode-mdm/). Warning: Once the PKG file is deployed, there may be chances that the network configurations be exposed to the users at the device end. Thus, while configuring the network settings, we advise using temporary network configurations and refrain from using Enterprise network configurations. ### Elevate standard account 31. Select **Elevate standard account to Admin** option to elevate the current user’s privileges from standard to administrator account during the migration process. On completing the migration, the account privileges revert to standard. Note: To prevent the user from using administrator privileges for actions unrelated to migration, enforce the Hexnode Gateway app in full screen mode. It can be done by selecting **Enforce Hexnode Gateway app in full screen** under **Configure Gateway settings** in the Hexnode UEM portal. ### Renew FileVault Recovery key 34. To renew and escrow the FileVault Recovery key during the migration process, select the **Renew and escrow FileVault recovery key** option. ### Set up the device configurations to be applied 36. Customize the device name in the **Enrolled device name** field. The use of wildcards such as %wifimacaddress%, %serialnumber%, %model%, %name%, %domain%, %userprincipalname%, %email% are supported from the dropdown. 37. To add the device to Hexnode’s [custom device groups](https://www.hexnode.com/mobile-device-management/help/custom-device-groups/), select the **Add to device groups** option and choose the required device groups from the dropdown. 38. To add the device to an organizational unit, choose one from the available dropdown under **Add to Organizational Unit**. ### Customize the Gateway app 40. Customize the Gateway app by adding an image of the company logo using the **Add company logo** option. ### Generate the configuration file 42. Check the **I agree to the Terms of Use** checkbox to generate the configuration file. Since the migration is processed silently, the admin must accept the Terms and Privacy Policy on behalf of the end user. 43. Click on **Generate a custom PKG file** to generate the configuration file in downloadable format. 44. Download the PKG file onto your device. 45. Deploy the configuration file to target macOS devices. You can even use your existing UEM to deploy the file. ### Complete device migration The deployed PKG file installs the Hexnode Gateway app on the device and associates the configurations. The Hexnode Gateway app automatically opens up after installing the PKG file on the device. Notes: If your current UEM requires either the bundle ID or the version of the Hexnode Gateway app while migrating: - The bundle ID for the Hexnode Gateway app is ‘**com.hexnode.onboarder**’. - Manually install the downloaded Hexnode Gateway PKG file on one of the macOS devices, and then use the Terminal to execute the following command for fetching the version of the Hexnode Gateway application: defaults read /Applications/Hexnode\\ Gateway.app/Contents/Info.plist CFBundleShortVersionString 1 defaults read /Applications/Hexnode\\ Gateway.app/Contents/Info.plist CFBundleShortVersionString Choose any of the following cases depending on your device scenarios and follow the steps accordingly to complete the migration. **Case 1: Device Enrolled via Automated Device Enrollment** 1. When a device is enrolled via Automated Device Enrollment (ADE), it can be reassigned to another UEM server through the ABM/ASM portal as a part of the migration process. You can [reassign the device in the ABM/ASM portal](https://www.hexnode.com/mobile-device-management/help/change-mdm-with-dep/) to an UEM server associated with the Hexnode UEM console. 2. Download and deploy the generated PKG file to the targeted devices using the currently enrolled MDM. Once the PKG file is installed, the Hexnode Gateway app opens on the device and initiates the migration. 3. Disenrollment of the device from the current UEM will be automatically initiated based on the configured settings under the **Remove device from existing UEM automatically** option in the Hexnode portal. If the UEM profile on the device is removable, the existing profile will be automatically removed. 4. On macOS 14+, user approval is required to initiate UEM migration, and the UEM profile needs to be approved by the user before installation. 5. If the **Renew and escrow FileVault recovery key** is enabled under the **Renew FileVault recovery key** option in the Hexnode UEM portal, the user will be prompted to enter the local account password. 6. Once done, the device will get enrolled in Hexnode without getting wiped. Update the ADE Enrollment profile associated with the ABM/ASM portal if needed, after the device is enrolled in Hexnode. Disclaimer: FileVault cannot be enabled via the Hexnode Access policy in the ADE Enrollment profile during enrollment in Hexnode UEM, if: - The device was previously enrolled in another UEM and - FileVault was not enabled In that case, the device must be wiped and re-enrolled in Hexnode to enable FileVault. **Case 2: Device enrolled manually** 1. Download and deploy the generated PKG file to the targeted devices using the currently enrolled MDM. Once the PKG file is installed, the Hexnode Gateway app opens on the device and initiates the migration. 2. The new UEM profile needs to be approved by the user before installation. 3. If the **Renew and escrow FileVault recover key** under the **Renew FileVault recovery key** option in the Hexnode UEM portal is enabled, the user will be prompted to enter the local account password. 4. Once done, the device will get enrolled in Hexnode without getting wiped. Note:The Hexnode Gateway app can be used to migrate macOS devices between two different Hexnode UEM portals. Migration between two different Hexnode portals can be done without needing to select the option “Remove device from existing UEM automatically.”