How to Use the New HubSpot CMS URL Mapping Tool

If you're a regular user of the HubSpot CMS URL Mapping Tool, you may have noticed that it has undergone a facelift. Don't worry, though—the changes are all for the better!

In this blog post, we'll guide you through the new look and feel of the tool, providing you with all the information you need to make a seamless transition. We've included helpful screenshots, detailed descriptions, and explanations of the different options available to you, so let's dive in!

Why use the HubSpot CMS URL Mapping Tool?

A URL map is a powerful tool that gives you control over how URLs are handled on your website. With URL mappings, you can redirect URLs to a new destination and manage your previous pages without visitors encountering any error messages. This is especially helpful when redesigning your website, changing domain names, or if you've neglected your page errors for too long.

Essentially, you’ll want to use the mapping tool when you have a page that gives a 404 error message. This occurs when the URL typed into the viewer’s browser doesn't match up with an existing page on your website. This is something you’ll really want to pay attention to if you’re redesigning your website, changing your domain name or if you’ve ignored your page errors for a while, (believe me, they pile up!)

Not Sure Which Pages are Returning an Error Message?

There are multiple ways in which you can find a list of your site’s errors, but the most accessible way is to use Google Webmasters:

• Once you’re logged in, you’ll see 3 calls-to-action on your dashboard. Find the section for crawl errors, and click on the “Crawl Errors” button.
• Once you’re on the “Site Errors” page, you’ll see three tabs for Server Error, Not Found and Other.
• You’ll find any 404-page errors on the “Not Found” tab.
• Go ahead and download that report to CSV, and you’re ready to begin mapping!

How to Format URL Mappings for the Bulk Uploader

To use the HubSpot CMS URL Mapping Tool, you’ll have two options: you can either add one URL mapping at a time, or you can bulk add URL mappings. Depending on how many redirects you’d like to implement, you may want to choose one option over the other. If you have 5 mappings like we do now, it may be timelier to just add singular mappings. However, I typically recommend using the bulk tool to save some time and effort.

Formatting an Excel document for the bulk uploader is easy to do:

• Pull list of URLs in CSV formatting (If your list isn’t in CSV formatting, you’ll be able to select CSV under “Save as type” options under the "Save as" menu).
• Format with 2 columns – old URLs in the first column, and the new URLs that you’d like to direct that traffic towards in the second column.
• Do not include headers.
• You can either include full URLs, “http://www.newbreedmarketing.com/full-url” or you can use the relative links, “/relative-link-style”.
• To be safe, you’ll want to use the relative link style only when you’re dealing with your main domain. If you’re using subdomains, or other domains in general, it’s a safe bet to use the full URL styling.

It should look something like this once you’re set:

Finding the COS URL Mapping Tool

Now that you’ve got your URLs all mapped out and saved as a CSV file, you’re ready to add them to the bulk uploader. To access the CMS URL Mapping Tool you’ll want to click on Content > Content Settings > and then under the “Content Optimization System Options” menu on the top left-hand side, CMS URL Mappings.

Bulk Upload

To bulk upload your CSV doc, you first click on, “Add new URL mapping” in the top right-hand corner of the page. This brings down a drop-down menu where you can choose, “Bulk add URL mappings.”

• Select the two columns of URL mappings in your CSV document, copy them, and then paste them into the “URL mapping redirects” text box.
• Make sure the “Separator type” is set as a comma, or the character used between the old URL and the new URL. If you’re unsure, copy and paste the character that’s used within the URL mapping redirects text box.
• You may or may not want to check the box at the bottom that says, “Update existing mappings with new destinations in case of conflict” depending on what you’d like. This will replace any duplicate old URLs, since you can’t have 2 different redirects off of one URL. If you don’t check this box and there are duplicates, the tool will automatically give priority to the uppermost mapping, which you can see in the mapping dashboard.
• Hit “Add URL Mappings” and you’re good to go!

HubSpot URL Mapping Tips

If you’re having trouble uploading URLs from a CSV format, you can try copying and pasting the URLs from a text editor instead.

The bulk uploader only allows 100 mappings at a time, so if your mappings exceed this number, you’ll have to split them into groups and upload multiple times.

Add One URL Mapping

From the drop-down menu, select, “Add one URL mapping.”

• Input your old URL in the “Original URL or path,” and your new URL in “Destination URL or path.”
• Check off applicable boxes:

“Redirected URLs should match original URL’s query string, or lack thereof”

A query string is a group of letters symbols and numbers that are typically created in a URL when there are tracking parameters set on the back end. You’ll usually see the URL and then a question mark with a bunch of mambo jumbos after it, like this:

If either of the URLs have something similar to this, you’ll want to check this box

“Ignore this URL mapping if a page exists at the requested URL”

You will want to check this box if the original URL is only temporarily down, or if you’d like to republish the page at any point in time.

We often use this with our career pages as we grow – we fill a position so we take the page down, but then a few months later we need to hire another employee. We put the page up again, but in the meantime, we don’t want people landing on a 404 page. Instead, we redirect them to our careers page.

“Advanced: Original URL is a flexible pattern URL”

This box is used to redirect a certain group of URLs using parameters that you set. We often use this functionality during website redesigns to bring over an entire group of pages, such as a blog. To use this box, you’ll probably want to have some coding experience, but it’s certainly easy enough to implement once you have the right pattern laid out.

Under this drop down, you’ll want to select whether the redirect is permanent or temporary. Refer to my example under the second bullet for an example of why you’d want to use a temporary redirect. Now it’s time to click “Add URL mapping,” and you’re good to go!

Maintaining your Mappings

Chances are, adding in 301 redirects won’t be a one-time process. I recommend checking your Webmasters account frequently to evaluate and update any site errors. This will not only help to keep visitors on your site, but it will also help improve your search engine optimization.

Through tools such as Moz, you can also track where the 404 error is linked from and how many times people have landed on the 404 page. You may want to consider reaching out to the referrer to ask them to update the URL on their site page. Or, if you’re noticing that the particular 404 link draws a lot of traffic, you may want to consider creating a relevant page using that URL to catch and keep that traffic.

It’s surprising, at times, the amount of insight you can gain from error pages on your website!