Skip to main content
File Substitutions
Luiza Gircoveanu avatar
Written by Luiza Gircoveanu
Updated over a week ago


File Substitution allows you to swap or block javascript files in your ObservePoint test environment. This allows you to see the impact of changes without negatively impacting customer experiences. It can be used in either Audits or Journeys for a variety of testing use cases.

Common Use Cases

  • Mitigate Analytics Server costs when testing - The most common example would be to use a regex to match Adobe Analytics in the File Substitution configuration and then swap it with a blank JavaScript file. ObservePoint traffic is synthetic, leveraging File Substitutions will save you money as it will prevent outbound analytics calls from hitting your vendor's servers.

  • Test a TMS migration - One important use case for File Substitution is to test the migration from one tag management system to another. Once your new tag management system is ready to be tested, use File Substitution to swap out the current file that loads your TMS and replace it with a reference to the new one. Check the Variable Summary report to spot any pages still loading the old one and to verify the new one loads each time.

  • Find tags loading outside of your TMS - Another use case is verifying that all your tags load from the tag management system. Unauthorized tags may be hard-coded on some pages without your knowledge, and would be hard to detect without File Substitution. If you replace the call to your TMS with a blank file, it effectively turns off the tag manager for the audit; any tag that loads comes from some source other than your tag manager. Because it is done in the audit, visitors to your site are completely unaffected. View the Tag Presence report to find any tags that load.

  • Test an update to your tag manager - Before deploying a new tag management version to your site, run an audit with File Substitution. Substitute the call to the old TMS with the new one to make sure all pages load the new TMS. The Tag Versions report can identify which version loads.

  • Test new tags and variables - Test a new tag from your tag manager by pointing to an instance where the new tag is configured. Look at the Variable Summary report to make sure it loads on every page and captures the right values.

  • Test compatibility with new JavaScript or other library files - File Substitution can be used on your production site to test new JavaScript widget file or a new responsive CSS file, for example. By using File Substitution in an audit or Journey, there is no risk that any user will be affected by the test. Simply tell ObservePoint to substitute an old file with a new one that you've uploaded to ObservePoint. Check your reports to validate that the new file doesn't change any of your data collection.


To set up a File Substitution you need to go to the Configurations and then the File Substitution Library.

Note: Successful configuration will not remove the tag from Tag Inventory and other reports in the Audit. It will neutralize it, making it unable to fire additional tags.

From there you'll click Create New to create a new mapping

Then you'll be able to match to the value of the file or request you're looking to replace and put in the remote file URL or upload a file.

Click on the URL field and enter the URL or regular expression (regex) to match on. (For regex, all qualifying matches will be mapped to the new file.) This URL or regular expression value should match the current script URL or reference that is deployed on the page. Depending on the type of value, select the radio button that matches your entry. In the field under that, either enter a URL or upload a replacement file by clicking the blue text.

Note: If File Substitution is not replacing the file as expected, check to verify that the content type of the file being replaced matches the replacement file.

Once you have it set and saved with a name you can go to the Advanced Settings of any Audit or Journey to select your existing File Substitutions.

You can select more than one to be mapping within an audit or Journey!

Looking At Results

You can see the results for the File Substitution in the Page Details report.

In audits, look in the Page Summary report in the left-hand navigation bar of the audit results/report.

After you've run your Audit/Journey with File Substitution, the results are displayed in the reports. For Journeys, each action step shows the File Substitution request and whether the file passed or not.

See the results of File Substitution on each step of the Journey actions.

Tag Initiators Tree View

You can view what and where something is substituted by clicking into an Audit Report, selecting Tag Health, clicking on a page URL, and selecting Tag Initiators. This is a great way to see if your File Substitutions are successful and on the pages that you are testing.

Did this answer your question?