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. (See: Documents vs. HTML)

If you have multiple language versions of a document, there are steps you can take to make those different versions of the document more visible. See the Language section of the Creating Documents section below for detailed instructions.

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:

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

Via “Download” buttons in various content types, such as How-to pages

(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 several 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.

Title

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

Short Description

Optional. You can provide a 1-2 sentence high level description of the document for viewers of the file.

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.

Organization(s)

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

Language

Optional. English is listed by default, but you should choose another language via the dropdown menu if your document is in a language other than English. Doing so will bring up another field in which you can associate the English version of that document with the language of the document you're adding to the system.

Filling in the correct language and the associated English page will result in documents displaying on pages with links to all language versions. This will only be true, however, for documents linked in certain fields, such as Additional Resources and Downloads found in many content types, including Events, How-tos, Information Details, and Services. This will also work on Binder Appendixes and Curated List document links. Documents will not display this way when linked in rich text fields.

This document display with language links can make your page designs more streamlined. You’ll no longer need to publish pages to list a series of documents in different languages.

Use the “Non-English Documents” report—accessible via a tab on the main navigation bar--to identify non-English versions of documents that are not linked to English versions.

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).

Type

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

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.

Collections

Optional. Most content will not be in a collection. Only add content to a collection if the collection creator has approved it. Learn more about collections.

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.

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.

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.

Link to documents via rich text field icon

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.

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.

Link to document via “Additional Resources” or “Downloads” button

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:

Go to the “All Documents” tab under the “Content” menu and find your document.
Click “Edit” next to the title of the media entity that contains your file
In the Select the File field, click “Remove”

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."

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.

Tracking revisions to documents

For organizations with multiple authors and/or pages with dynamic content, the ability to track a document's revision history is critical. You can track status changes to documents by locating the document, clicking on edit, and then selecting the "revisions" tab.

In this view, you can track a document's history and authors. You can also click the "revert" button to restore a document to a previous state.