Updated from TeamSite Technical Solution and Implementation

EWIS serves much of the existing content on VA.gov (e.g. http://www.va.gov/health) and to accommodate this our systems serve that request from our version of the site on sites that exist on the same domain.

Diagram of how EWIS is served to the user

Requests to subdomain hosts such as http://www.benefits.va.gov are not proxied through our systems and are not under our control. Content for these sites exists on TeamSite: a content management system utilized by the VA to manage content across several properties at the VA. Each property in TeamSite consists of perl-based template files, which on publish rendered content to a file store. The rendered content contains server side includes, which reference content from a directory called va_files, which has shared header and footer functionality.

There are no consistent staging/production environments for TeamSite properties, and there are multiple variants of header and footer functionality in va_files (attached to this issue). For properties that do have staging and production variants, they reference the same version of header and footer content. A change to the header or footer will affect both the staging and production versions of a property.

Scripts and TeamSite Administration

The header injection markup is added to TeamSite templates by their administrator. Current point of contact for this is:

Current markup added to TeamSite templates:

<style type="text/css">.brand-consolidation-deprecated { display: none !important; } </style>
<link rel="stylesheet" href="https://prod-va-gov-assets.s3-us-gov-west-1.amazonaws.com/generated/styleConsolidated.css" />
<script type="text/javascript" src="https://prod-va-gov-assets.s3-us-gov-west-1.amazonaws.com/js/settings.js"></script>
<script type="text/javascript" src="https://prod-va-gov-assets.s3-us-gov-west-1.amazonaws.com/generated/polyfills.entry.js"></script>
<script type="text/javascript" src="https://prod-va-gov-assets.s3-us-gov-west-1.amazonaws.com/generated/vendor.entry.js"></script>
<script type="text/javascript" src="https://prod-va-gov-assets.s3-us-gov-west-1.amazonaws.com/generated/proxy-rewrite.entry.js"></script>
<script type="text/javascript" src="https://prod-va-gov-assets.s3-us-gov-west-1.amazonaws.com/js/vendor/uswds.min.js"></script>
CODE

TeamSite behavior and allowlist pages

There are an unknown number of TeamSite templates that drive the <head> content on TeamSite pages and there are several pages that receive the above markup that should not show the VA.gov header. The proxy rewrite application uses a allowlist to drive the activation of the header content. Example allowlist entry:

{
  "hostname": "www.benefits.va.gov",
  "pathnameBeginning": "/",
  "cookieOnly": false
},
CODE

Pages can be allowlisted in two ways:

  • cookieOnly: false - the header will always activate

  • cookieOnly: true - the header will activate when proxyRewrite cookie is set to true.

This cookie can be set in the console by running document.cookie = "proxyRewrite=true;"

Considerations when editing and testing the allowlist

  • Some TeamSites redirect to both subdomain.va.gov and www.subdomain.va.gov (sometimes alternating between the two). Always test the redirect behavior of the first level of links on the page and ensure that both hosts are allowlisted if necessary.

  • New hostnames need to be added to our allowed_origins here and here. Subdomains are considered separate hostnames by CORS and the browser performs CORS checks on all of the webfonts injected by the TeamSite header scripts. Terraform updates are not automatically deployed- work with a Devops engineer to deploy these changes.

  • There are at least two behaviors provided by the TeamSite system for adding the inline scripts to the page:

    • as part of the initial document response, or

    • injected as part of a TeamSite sourced JavaScript.

Proxy Rewrite

The proxy-rewrite application is used to inject site-wide VA.gov components into pages that are outside of the VA.gov build and publish process. The affected sites are generally referred to as "TeamSite", because TeamSite is the name of the CMS use for those pages.

This works by -

  1. A request is sent to a VA.gov website

  2. The content requested from the TeamSite servers and passed through the VA.gov proxy

  3. A code snippet included in the TeamSite page downloads the proxy-rewrite app which overwrites the TeamSite header and footer with VA.gov content

Because the TeamSite template containing the proxy-rewrite snippet is used both on sites that should and shouldn't show the VA.gov header, the script is governed by an allow list contained in proxy-rewrite-whitelist.json.

Local Dev

Since TeamSite content is not run through the vets-website build process, testing changes on Teamsite requires running local or staging changes against the production pages. The proxy-rewrite app supports targeting a specific environment for testing:

For example: https://staging.va.gov/health/?targetEnvironment=vagovstaging

The default behavior for https://staging.va.gov/health is to load the production assets. When the targetEnvironment is set, the loader will delete the production nodes from the DOM and add script and style nodes for the target environment.

The injection script will support any of these environment names set as the targetEnvironment.

Caveats:

  • Style node deletions will prompt a rebuilding of the CSSOM but removing script nodes doesn't undo any JS that was run before the JS node was removed. For most cases this should not impact testing as the application specific code doesn't run but JS that is executed before the application (e.g. polyfills) will always run the production code first.

Charles Proxy

You can also use an application called Charles Proxy to map the proxy-rewrite bundles of TeamSite pages to your local machine. This way you can navigate directly to https://www.va.gov/health/ and when the request for the production bundle of proxy-rewrite is sent, Charles will have overridden that file to instead be served locally. Instructions to set this up are located here.

TeamSite Examples

This list is not exhaustive- there's not an easy way to determine all of the sites that receive the template content. All external links in the megamenu have been investigated.

Site

Header State

Template Behavior

https://www.telehealth.va.gov/

Not Whitelisted

Inline in Document

https://www.benefits.va.gov/

https://benefits.va.gov

Whitelisted

Injected by JS

https://www.va.gov/homeless/nationalcallcenter.asp

Whitelisted

Inline in Document

https://www.cem.va.gov/

Whitelisted

Inline in Document

https://www.volunteer.va.gov/index.asp

Not Whitelisted

?