Automated IT Glue to Hudu Migration Script

A few weeks after we had completed our move to Hudu by performing a manual migration, I finally figured out how you could do an automated migration. So after 5 weekends of work, many evenings, well over 100 hours, a ridiculous amount of restored snapshots and one very supportive and understanding partner 🙂 . Here is a script which should make your life easier when migrating.

What can it migrate:

  • Companies
  • Contacts
  • Locations
  • Configurations
  • Domains
  • Flexible Asset Layouts
  • Flexible Assets
  • Documents with folder structure
  • Passwords
  • Document Links

What are the limitations:

All layout fields will be marked as non-required – To handle rewriting tags between assets, the script has to first create a holding item for each Asset Layout and Asset. To do this I use a new “Migrated from IT Glue” field and set the date of the migration there in each layout and asset on the first creation. Once the migration completes you can edit the layout to remove this field. You will also need to go through each Layout and manually set every field that needs to be required.

Everyone’s environment is going to be unique – I have only been able to test on a few environments so there may be issues you run into. If you run into problems feel free to reach out on https://www.reddit.com/r/hudu or in the MSP Geek Slack #v-hudu channel and I will do my best to help.

IT Glue does not give API access to Documents – To workaround this, this script needs to upload them from a full export of your tenant. The documents uploaded are then limited by how IT Glue rendered them to HTML in this export. Everything else will be migrated via the IT Glue API.

IT Glue and Hudu give no API access to Checklists / Processes – These will need to be manually migrated

Matching Existing Items – This script tries to match on existing items first that are already in Hudu, for example Companies, Locations, Contacts and Configurations. There is no guarantee this will work, so you may end up with duplicates.

Other Tag Field Types and Item relations – At present Hudu doesn’t have a mechanism for tagging certain items in an Asset through the API. For example companies passwords etc or related items on the right bar. An HTML report is generated at the end with details on what you need to do manually.

Requirements

Powershell 7 https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-core-on-windows?view=powershell-7.1

A full backup of your Hudu system before you start the import. Things could go wrong so make sure you can get back to a state from before you run the tool.

This is an interactive script and must be run from a machine that is encrypted. The script saves progress to JSON files which are dumps of everything migrated so make sure the machine it is run on is secure and encrypted.

An IT Glue API Key with password access enabled.

Your IT Glue API URL.

A full export of your IT Glue tenant.

An instance of Hudu installed. Ideally with your PSA and RMM integrations setup so Companies, Contacts and Devices will already have synchronised across.

A Hudu API Key with password access enabled.

Your Hudu Base Domain

A full backup of your Hudu system before you start the import. Things could go wrong so make sure you can get back to a state from before you run the tool. (Yes I put this twice).

Notes

At some point during the script you are likely to trigger Hudu rate limiting. Just leave the script running when this happens and it will keep retrying automatically.

At present importing Global KB articles is slow as each one has to download every folder in Hudu and parse them to get the global KB folder structure. Hudu are going to add a filter which will speed this up shortly.

It is an interactive script which will ask you questions as it goes through so please keep an eye on it.

If you only want to migrate certain things there are script settings which will allow you to turn sections on and off. The script will still try to match against the existing items in Hudu for tag matching, but will not migrate new items across for the disabled sections.

Logs

The script will create a MigrationLogs folder the location the script is run from. In here it will keep a copy of the new Hudu items and the old IT Glue items stored as json. If anything goes wrong you can use these files to track down the problem and undo anything if required.

Rollback / Resume

At various points the script will prompt you to take a snapshot. If you are able to I would recommend taking a VM snapshot. If something goes wrong you can then revert to the snapshot and remove the .json file(s) that correspond to the items you imported after the snapshot from the MigrationLogs folder. You can then restart the script and it will carry on from the point of the snapshot, by loading the *.json files in the MigrationLogs folder.

If you are on a cloud version or can’t take snapshots and something goes very wrong. Please make sure you keep the contents of MigrationLogs and reach out to me and I will be able to provide an undo script (hopefully, with no guarantees).

Instructions

  1. Have a base Hudu install with your integrations setup to sync in things like companies and contacts from your PSA and configurations from your RMM. Don’t setup any Layouts other than for synchronised assets from integrations.
  2. Perform a clean up of you IT Glue environment. Make sure you have cleaned up any duplicate records. Removed any old ones you don’t want to migrate.
  3. Check your Flexible Layouts don’t have any fields named the same thing on the same layout. For example we had two fields called Pre-Shared Key on our Wireless asset. (One for primary one for guest). If this is the case rename one of them.
  4. In IT Glue perform a full export and wait for that to complete and download the zip file.
  5. Extract that ZIP to C:\temp or equivalent.
  6. Obtain an API Key with password access from IT Glue
  7. Obtain an API Key with password access for Hudu.
  8. Read through the settings section of the script and configure it as needed.
  9. Double check your backups of Hudu
  10. Run the script and answer questions as the script runs.

Configuration Settings

The settings in the script all have instructions on what they are for. If you choose to disable importing of any items they will just be matched against what is already in Hudu.

The Script

Get the latest version on Github here: https://github.com/lwhitelock/ITGlue-Hudu-Migration/blob/main/ITGlue-Hudu-Migration.ps1

You may also like...

29 Responses

  1. Bronson says:

    Attempted this script. It imported a lot of data but the flexible assets were blank inside. It just says “Imported from IT Glue” and then shows the date. No details listed.

    Would be nice if you could do one client at a time as a test. Right now the script is trying to create flexible assets for companies I haven’t sync’d in yet.

  2. Richard says:

    Thanks for the script … I am having trouble figuring out what value I need to put in for $InternalCompany
    # IT Glue Internal Company Name (The documents from this company will be migrated to the Global KB)
    $InternalCompany = “???????”

    I have tried all the obvious values I can find including our primary organization (what shows in ITG under account->primary organization … any help would be greatly appreciate .. error I am getting is:
    A single Internal Company was not found please run the script again and check the company name entered exactly matches what is in ITGlue

    • That’s the name of the company in IT Glue, whose documents you want to use as the Global Knowledge Base in Hudu. Normally people will have an “Internal” company in IT Glue where they keep the global KB which is why it is there. If you don’t want to migrate anything into the Global KB, just create a blank company in IT Glue and set $InternalCompany = to the name of that blank company.

      • Richard Banham says:

        We have CompanyA in hudu and CompanyA in IT Glue. CompanyA in ITG is setup as our internal company (i.e. CompanyA is what shows under the Settings -> General Tab -> Account Info -> Company Name field). We are continue to get this error:
        0 ITG Glue Companies Found
        A single Internal Company was not found please run the script again and check the company name entered exactly matches what is in ITGlue

        • Check you have an API key with the correct permissions. Try running the get IT Glue companies command and see what the name of the internal company is there that it returns.

          • Michael says:

            I am running into the same issue, when i run the Get-itglueorganizations command, it comes back with “message:forbidden”

            you said earlier to check API permissions, but i do not see anywhere in ITglue to check that. I did ensure that the “password access” was selected when generating the key.

  3. Terry Cole says:

    Luke,
    Nice script (to say the least!), but my execution fails at “Import-Module HuduAPI” on line 549. Executing “get-module -listavailable”, no HuduAPI is present in the resulting list. I found your HuduAPI at github, but no idea how to install it (yet). I may have this resolved before you reply, but posting here just in case you have handy advice.

    • You should just be able to do install-module HuduAPI in a PowerShell prompt to install it.

    • Terry Cole says:

      Disregard….got it sorted. Information your detailed instructions should additionally include: A) get HuduAPI and ITGlueAPIv2 GitHub packages from url1 and url2 B) save them in folders c:\blah and C) rename folders huduapi-master to “huduAPI” and “Itglueapiv2-master” to “itglueapiv2”. When these things were done, all is good.

  4. Dan OIson says:

    Can this migrate OTP codes?

  5. Brian Anhalt says:

    To be clear, if I’m reading the documentation correctly, the migration script cannot migrate “tag” fields in Flexible Assets, nor related items. Is this correct?

    Docs say “An HTML report is generated at the end with details on what you need to do manually.” – does this report show all tag fields and related items for all assets (from what was in ITGlue) which you’re supposed to manually add? I’m asking because we need to know how much manual work it will take to replicate what we have in ITG now (we have thousands of companies, tens of thousands of configurations, etc.) and manually adding related items/tagged fields will be a lot of work.

  6. Garrett Lynch says:

    Hi Luke,

    A great script overall and would love to see Tim and team work with you on an official migration avenue. One issue we’re seeing–

    Build 2.1.5.10

    On password imports, embedded passwords within a flexible asset (in the actual asset layout versus right-side embedded) will import and match accordingly and the JSON reports match this. However, general ITG passwords will import but other embedded passwords tied to assets do not. The script will say for example, imported 2,453 passwords but Hudu only shows a handful of them. Contacts, Configurations, and Flex Assets that contain embedded passwords all remain blank in Hudu. Thoughts?

    • Garrett Lynch says:

      I forgot to mention that embedded logins will “Matched to xxxx” but no content. OTP will be a challenge but that’s ITG making our lives difficult.

  7. Alec says:

    I too am having issues with 0 ITG Glue Companies found. I tried setting up a Blank company and input that for the Internal company and it failed. I reset the API and made sure the password option is selected. It is not working. Any help would be greatly appreciated.

  8. Andy Smith says:

    Hey Luke,

    Trying out your script with a trial Hudu cloud and running into a few Status 500 errors. For example when doing Asset Layouts
    Line |
    69 | … $Response = Invoke-HuduRequest -Method post -Resource “/api/v1/asset_ …
    | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    | ‘{“status”:500,”error”:”Internal Server Error”}’
    From what I can tell from the Locations log therse no HuduID and possibly why its failing. Any guidance you can provide is appreciated.

  9. Brandon says:

    Trying to run this today and it seems to fail whenever it tries to create new asset layouts.

    Error is line 69 of New-HuduAssetLayout.ps1 with “Status 500 Internal Server Error”

    HUDU Version – 2.1.5.14

    There was also an error but probably because it never created the Asset Layout:

    1621 | … -id $UpdateLayout.HuduID -name $UpdateLayout.HuduObject.Name -icon $ …
    | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    | Cannot process argument transformation on parameter ‘Name’. Cannot convert value to type System.String.

  10. Hello. Just attempted to run this script and got stuck on the following:

    Fetching Companies from IT Glue
    Get-ITGlueOrganizations: C:\ITG\Update ITGlue-Hudu-Migration.ps1:612
    Line |
    612 | … Select = { (Get-ITGlueOrganizations -page_size 1000 -page_number $i). …
    | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    | {“message”:”Forbidden”}

    I checked the API key and reissued, same result. Made sure the option to allow password access was enabled.

    Any suggestions?

  11. Erik Rotar says:

    Remove-Module:

    remove-module ITGlueAPI

    No modules were removed. Verify that the specification of modules to remove is correct and those modules exists…

  12. Erik Rotar says:

    Doesn’t work: Remove-Module:
    Line |
    563 | remove-module ITGlueAPI
    | ~~~~~~~~~~~~~~~~~~~~~~~
    | No modules were removed. Verify that the specification of modules to remove is correct and those modules exist in the runspace.
    No previous runs found creating log directory
    Fetching Companies from IT Glue
    Get-ITGlueOrganizations:
    Line |
    612 | … Select = { (Get-ITGlueOrganizations -page_size 1000 -page_number $i). …
    | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    | {“message”:”Forbidden”}
    Retrieved 0
    0 ITG Glue Companies Found
    A single Internal Company was not found please run the script again and check the company name entered exactly matches what is in ITGlue

  13. Erik Rotar says:

    Hello,

    When transferring Articles it gives me that error message:

    Loading Article Migration
    Get-ChildItem:
    Line |
    1947 | … tachfiles = Get-ChildItem “$($ITGLueExportPath)attachments\documents” …
    | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    | Cannot find path ‘Z:\attachments\’ because it does not exist.

  14. Ian says:

    When trying to run the script it gets to the point of asking for a backup. When I select “Y” it flashes and closes. Any ideas?

  15. Mark says:

    Hi there,

    First off – thank you for providing such awesome work – it’s greatly appreciated!

    I’m attempting to run the migration script, but it get’s stuck at Get-HuduAppInfo (line 554). We have version 2.1.1 of the HuduAPI installed, we can confirm by running a manual Import-Module. However, the version always comes back 0.0.0.0:

    > Import-Module HuduAPI -Version 2.1.1
    > $HuduAppInfo = Get-HuduAppInfo
    > $HuduAppInfo.version
    0.0.0.0

    I’ve tried removing/re-adding the module, but not luck. Is there error an issue with the PowerShell Module, or the API setup on the server?

    Thank you,
    Mark

  16. Randy Bryan says:

    Hi. Will this work with the hosted version of Hudu?

  17. Tim says:

    If your not from the EU be sure to change where the API for IT glue is pointed. https://api.itglue.com

    Without changing this it kept printing out no company’s found.

Leave a Reply

Your email address will not be published. Required fields are marked *