Public & visitor feedback
Documents
Learn more about working with documents (also known as files) on Mass.gov.
Documents refer to .pdf, .doc, .xlsx, and other files used for government content.
While documents might be the best format for some content, they have significant shortcomings compared with HTML and Mass Digital recommends converting documents to HTML for display on Mass.gov when possible.

How documents work

Authors should be able to create something once and reuse it in multiple places. Instead of updating a document on each page, you should only need to do it once, and your document will be up –to date wherever it lives on the website.
To understand documents on Mass.gov, it helps to learn the difference between a “file” and a “media entity,” since you’ll be working with both.
"File" means what you think it means: A Microsoft Word document or a .pdf, for example.
A media entity is a container for a file and for the information associated with that file. (This associated information is called “metadata,” and it helps make documents easier to find for content managers and constituents. When you add a download to a page, you’re linking your content to the media entity.
You can edit the data contained in a media entity just as you can edit a content type. On the “All documents” menu, click “edit” to open a media entity in edit mode:
Document editing
Once you’ve opened the media entity, you can change the data it contains, such as its Title and the Organization it is associated with.
You can also change the file it contains by clicking on "Remove." You’ll then be shown a “Choose file” button so that you can replace the file.
Replacing the file inside the media entity will cause the file to update anywhere you’ve linked to the media entity on Mass.gov.

Creating a document

You can add new documents to Mass.gov in multiple ways, including:
  • From the main CMS navigation menu’s “+Add Document” tab
+Add Document tab
  • Via “Download” buttons in various content types, such as How-to pages
Download buttons
(Once a document has been added to the CMS, you can also link to it from the “Download” button in various content types and via the documents icon in rich text fields.)
If you choose to add a document via the “+Add Document” tab, a form will display in which you can add a file, such as a .pdf or .doc, within a media entity that includes information about the file.
The form includes more than a dozen fields under the “Basic” tab, but only a handful (Title, Select the file, Organization(s), etc.) are required. You can decide whether filling in the fields that aren’t required will help your organization better manage its documents. Most organizations do not fill out fields under the “Advanced” tab.
The Add Document form includes more than a dozen fields, some required, some not.

Title

Required. Fill in this field with the clickable text you want to appear for the file on Mass.gov.
Clickable document title

Listing description

Optional. Use this to briefly describe the document — why someone might need it, for example. When you add documents to Curated Lists, you can click a box to make sure this description appears along with your document.

Select the file

Required. Click this button to upload the file from your computer to Mass.gov’s document repository.

Category

Optional. Dropdown field to use to indicate the type of file you’re uploading.

Organization(s)

Required. Show the organization or organizations that published the file.

Language

Optional. English is listed by default, but you can choose another language via dropdown menu.

Author

Optional. The person or people responsible for the contents of the file.

Publishing Frequency

Required. This field defaults to “once,” which means the file is not published on a regular schedule. If the file is periodically published, select the time interval. For example: The state tax form that is updated once per year has an “annual” publishing frequency.

Geographic Place

Required. Region or place associated with the file—Massachusetts by default.

Contact name

Optional. Person or organization responsible for answering questions about the document.

Contact information

Optional. Email, address, phone number or link to online form to get questions about file answered.

Timeframe

Required. Use dropdown menus to choose the Start Date for the file to be published, and an End Date if one is appropriate, to indicate the end of the document’s effectiveness (this will not unpublish the document).
Timeframe dropdowns

Labels

Optional. Labels can be used to group content together for use with Curated Lists and for searching on related content in Drupal. If creating a label, make it unique. If opting for an existing label, it will appear in the autofill fill as you type it in.

Type

Optional. Choose from a long checklist to identify the type of file.

Tags

Optional. May help with searching for documents.

Internal notes

Optional. Only visible to CMS users. Describe anything important about the document, such as changes or updates.

Saving a document

After you’ve filled out the fields, you must save the document. By default, the dropdown menu at the bottom of the form is set at “Draft.” Change that to “Published” if you want the file to go live.
Choose “Unpublished,” if you want to hide a document from Mass.gov visitors. Use the Pages linking here tool to remove links to the document on Mass.gov pages, so that visitors won’t see broken links.
Choose “Trash” if you want to remove the document from the system.
Choose “Restricted” if you want to keep a document private to yourself. If you restrict a document that you did not author, you will no longer have access to it. If you accidentally restrict a document that you need access to, submit a ServiceNow request.

Searching for documents in the CMS

Documents can be located within the CMS via the “All documents” tab on the main navigation bar near the top of the screen.
All Documents filters
Once you click on “All documents,” a series of filters will appear that you can use to search for documents by title, author, organization, and more.
If your search results in a collection of documents that you wish to save or share via an Excel file, click the “CSV” button and a spreadsheet will be downloaded to your computer.
Documents can be saved in a CSV file
There are 2 main ways to add documents to pages in the CMS, and both involve using a file browser.
Any document added to a page using the file browser will automatically be updated if the underlying file is updated.
Point your cursor to wherever you want your document link to appear within the rich text field. Then click on the file browser icon in the rich text field toolbar.
The file browser displays as a pop-up screen that allows you to search for documents in the CMS via title, author, organization, etc. Check off the document you want from a list of results (you can only select 1), then hit “Select file” at the bottom of the screen to embed a link to the document in the rich text field. The document will appear on the page displaying the document title.
File browser in action
You can change the link text in the rich text field either by clicking on it and overwriting the words, or by clicking the “Source” button in the toolbar and changing the text in the code.
Clicking on “Additional Resources” or “Downloads” within various content types will display the same file browser described above for adding documents to content.
Follow the same instructions, searching for the document title, checking it off from the list of documents displayed, then hitting the “Select file” button.

Updating a document

When it comes time to update or replace an outdated document, it's important to do so correctly for a number of reasons. This ensures that the new version keeps all of the valuable search rankings that the older version had. People searching for the old version will quickly and easily find the new one.
Updating the existing document, rather than unpublishing it and creating a new one, also prevents the old document from appearing in search results and confusing people.
Finally, updating documents using the following steps helps prevent broken links where you've embedded the original version. It's still a good idea to check which pages are linking to your document before replacing it though.

How to update your document

To update or replace a document with a new file in the CMS, follow these steps:
  1. 1.
    Go to the “All Documents” tab under the “Content” menu and find your document.
  2. 2.
    Click “Edit” next to the title of the media entity that contains your file
  3. 3.
    In the Select the File field, click “Remove”
Remove a file to update it
4. Click the “Choose File” button in the Select the File field and select your replacement document from your computer.
5. Scroll to the bottom of the page and make sure the Change to: state is set to "Published.” Then click "Save."
Publishing and Saving a document
Updates made to a media entity will be reflected anywhere you’ve linked to it.

Deleting a document

While you can replace or unpublish a document, if you want it permanently deleted from the CMS, you’ll need to submit a ServiceNow request.
Note: Please make sure the file is unpublished and has been moved to the Trash before submitting a ServiceNow request.
Make sure to include the following in your request:
  • File name/title
  • Node ID
  • File URL
If you're requesting a large number of files to be deleted, here are some tips on streamlining the process:
  • Make a spreadsheet of the files you want deleted that includes each file's title, node ID, and URL
  • Include no more than 50 files per request. If you need more than 50 files deleted, please repeat the process as necessary.

Document download analysis

You can use Google Analytics to track how often documents on your content are downloaded by Mass.gov visitors.