PIER System Support | Documents
February 14, 2012 3:53:00 PM PST

Documents are the primary information element in the PIER Site. They usually equate to "web pages" on the External Site or to "messages" that are distributed from PIER. You may also use them to store "Internal" information (see Folder - Access level) or to hold "template" information (see Special Folders).

The organization of Documents is as follows:

Folders contain Documents

Documents have one or more Drafts

Drafts have one or more Parts

Folders

Folders (sometimes known as "doctypes") are the first line of organization for documents. Every PIER Site has a unique naming and ordering methodology, including which Folders are on the "top" of the list and also which Folders have sub-folders. There are only two levels of folder heirarchy supported.

Folders also have many properties that can be assigned to them.  These are all availble in the Documents tab under the "Edit Folders" link. Most of the properties such as "Description" and "Display Options" are self explanatory. Some properties, such as the Folder View template, reach into advanced topics that are touched on more fully in the Concept document titled "Web Design". The most common properties are considered here.

The first property to consider is the "Access Level" which can be "public, "hidden", or "internal". Documents in Public folders are displayed on the web site and any visitor can access them. Hidden folders are not displayed, but they can be viewed following a search operation or using a specific link such as might go out in an email. Internal folders are for PIER User access only and are not available to the general public. There is another capability at the Folder level to limit access to Guest Contacts, - see the complete explanation under the Concept document titled "Guests".

The second property is the "Signature" which is applied to all documents in the Folder. Maintained under "Settings>>Documents>>Signatures", - this is the "For more information contact" data that is added to each Document that is emailed out or presented on the External Web site. As an added note, - if the email value is set for the signature, this is the default "from" address used during distributions of documents.

Another property to consider on Folders actually comes through the "Approval List" for the system, which is a requirement before a Document can be Published. If approvals are set up "per folder", then this is a consideration at the folder level. See "Approving, Publishing, Archiving" below.

If the Approval List setting is "Per Folder", another property will be important at the Folder level, - the automatic Document Status Notification. Under "Settings>>System>>Email Notifications" there is a flag to set in order to automatically send email to "all approvers and draft contributers" when a Document within the appropriate folder is "Approved for Publishing" or "Published". If there is only one "Approval List" for the whole PIER Site, then all Approvers will be notified of all of these operations on All folders.

"RSS" and "Recent Updates" feeds are also managed at the Folder level with parameters such as how many Documents to show, whether or not sub-folder documents are included, etc.

Finally, there is a special Internal Folder identified as the "Templates" Folder, where the "Top 10" Approved and Published documents are made available on the New Document menu as starter Templates for Document creation. This construct facilities rapid, standardized Document generation during a crisis.

Documents

Documents are simply the "Message" information in PIER. They are actually collections of Document drafts and maintain a few simple properties. These include a Title, Subtitle, Publishing Date (actual or overridden), and a Folder address. At this level there is a "Secured" flag for added security if you wish to lock certain documents behind an additional PIER User Permission. And there is an optional override value for the "Signature" that would otherwise be designated at the Folder level.

Of note here is the collective "status" of a Document. If none of it's Drafts are Published, the Document (collection) is deemed to be in "UnPublished" state. As soon as any draft is Published,  the Document is noted as "Published". When the Document is "Archived", - then all Drafts are marked with that status.

Each document has a "document number". From the external site it will generally be visible as the last (6 or 7 digit) number in a URL reference to the document, right after the site number. From the inside of the site, you can hover over any draft link and the document number will be displayed in a tool-tip window. Each draft also has a number, but all drafts of a document share the same document number.

Drafts

Drafts are versions of the one Document (Message) that can be created and modified by other individuals. Only one PIER User can edit a single draft at a time. Each draft has a "status", and those are described as:

In Progress - As far as the system knows, a PIER User is actively editing this document. In the case where they navigated away without closing the draft, it will be suspended in the "In Progress" status. That person can re-examine the document and choose to "Continue Editing" the document.

Unpublished - This is a draft that has been closed and has not been pushed to any other status.

*Pending Approval - This is a draft that has been submitted to personnel on the "Approval" list but has not yet been approved for publishing.

*Approved - This is a draft that has been gained Approval from a PIER User on the appropriate Approval List.

*Published - This is the "draft of record" that would be shown on the web site or that would be sent out in a distribution.

Archived - This status is set on all Drafts when the Document (group) is moved to Archive (either manually or automatically on a chosen date).

*To avoid confusion, only one draft can be in each of certain statuses. If another Draft is processed into that status, the old one will be "bumped" to "Unpublished".

Beginning in PIER 6.4, you may create new Drafts and process them through approvals, etc., while there is a "Published" draft available. You no longer need to "unpublish" before beginning a new draft.

Parts

When examining a Draft, one or more tabs are presented that contain separate elements associated with that draft. These might be an "HTML" part (full of formatting, links, etc.) a "Text" part (just the text, nothing else), or a File (which was uploaded), a Description (of the uploaded file), or a Thumbnail.

The Parts of a draft are linked together by "Content Generation". Changes made to the front-most part are automatically reflected on the other parts as appropriate. For instance, adding a bolded word Pineapple to the HTML will be reflected as merely the letters in the "Text" part. The "Content Generation" can be disabled on the secondary part, and that part can be edited separately from the first part.

"Parts" are best explained by distribution methods. Because the External Web Site or an Email can contain rich formatting of an HTML page, but an SMS Text message or a synthesized phone message can only process the raw words, the Text page distinguishes only that element.

In practice, an Email document may be long on text and formatting (HTML), but an SMS message (TEXT) can be edited separately and pared down to 140 characters of highly optimized text.

New Documents

There are several ways to create a new Document. The first is a [Notification] button that is available to PIER Users who have all the privileges necessary to create, approve, and send Documents. The intent of this button is to provide the most rapid capability to create and distribute information. This option is discussed in more detail below.

The second most optimized method for creating documents is under the "New Document" construct. If document templates have been created (and approved and published, - in the Templates Folder), the menu will display the "Top 10" Documents in that folder. Selecting one of the templates will pre-populate the new document with a copy of the template, saving time and steps in organizing the new content. After selecting a title and a folder, the new Document is ready to process through.

A third way to create a New Document is to use one of the "new" types.

  • Blank - this will create an empty document with HTML and Text parts. Every word in the title, subtitle, and the parts of the document will be indexed for searching. The HTML portion will be used for display on the web site and for rendering to Fax and Email distributions. Text content will be generated automatically (until the "disable content generation" box is checked) from the HTML content, and would be used for rendering to SMS and Text-to-voice distributions.

  • Upload File - this will initiate an upload of an existing file that you would share in it's original format such as a spreadsheet, word processing, PDF or graphic file. PIER will automatically recognize many types of graphic files and create thumbnails that your web site visitors can view on a file listing. "Parts" for the document will be created based on the file type / extension, such as a "File" part, HTML and Text Description parts, and perhaps a Thumbnail part. This document type is useful for sharing files created with other (non-PIER) software. Only the title, subtitle, and description parts are indexed for searching.

    PIER does not open contents and scan for objectionable content (macros or viruses), so care around those files has to be exercised before upload and distribution.

  • Link - this format is for posting a direct link to a specific web site or page URL. This is a "lightweight" option to refer to information without duplicating it on the PIER site, however PIER does not validate the URL to ensure the page is available (or remains available over time).  Only the headline, subtitle, and description parts are indexed for searching.

  • Notification - this will create a basic document with only a Text part. The intent is for simplicity of creating an un-formatted, text-only document as quickly as possible that could be distributed in all modes. Title, subtitle, and the "notification" part are all indexed for searching.

    If you are an approver on the site, a separate "Notification" bar is also available above the "New Document" bar on the both the Home tab and the Documents tab.

One more way to create a New Document is to consider any Draft of any Document in a Folder listing, and choose the "New Document from This Draft" Icon. This will copy the content of that Draft just as the Template is copied, but it will pre-populate the "Folder" property with the same Folder which the originating Draft / Document came from.

On standard PIER Sites, the search function is found at the bottom of the News & Info menu. To search for documents on your internal PIER site, use the search box located in the top section of the Documents menu panel.

Editing

Editing the "HTML" part of a document is facilitated by the "TinyMCE" Editor and toolbars. Several operations are available on the toolbar that should be noted:

  • Paste as Plain Text, Paste from Word : A simple paste operation will attempt to retrieve the "best" data to copy in to the document, and often that information is over-complicated by other programs. These two icons execute operations that attempt a "cleaner" version of a copy.
  • Insert / Edit Image : This operation facilitates inserting an image from another web site or from the Media Manager. Among the properties of the image is the "description" value, which is generally recommended because of useability issues for 508C compliance needs.
  • Insert Content : This enables dynamic content such as an RSS feed to be injected into the document.
  • Insert/Edit Link, Unlink : This facilities creation of "Web Links" under selected text or images.
  • HTML button : This is a function to allow editing of the underlying HTML source code directly. This should be considered an "advanced" function and used primarily by persons experienced with HTML development. After "updating" the code in the window, the tinyMCE Editor will resume operations on the document

If the page is too complicated, or the browser is not able to work with Rich Text Editors (such as tinyMCE), the "Source Editor" link is available on the bottom of the window. This will toggle directly to a text-only type source editor for the HTML page. This capability is particularly important if document creation is necessary for users of iPad and iPhone devices which feature browsers that do not have the constructs to work with the regular editor.

Editing the "Text" part is rather more simple. By default, "Content Generation" is enabled and editing is not available for this part. This window shows a "Character Count" on the bottom that is useful, but editing of this part is not supported until the "Disable Content Generation" box is checked.

If at any time a checked "Disable Content Generation" box is un-checked, the Content Generation function will discard the secondary parts and re-generate them from the primary (usually the HTML) part.

On "File" documents, the only editing feature is the "change" link which allows a different file to be uploaded to the PIER Site.

Approving, Publishing, Archiving

Documents require "Approval" before they may be Published. Under "Settings>>PIER Users>>Approvers", this can be set at a site level or on a per-folder level, and the requirement can be set to a single approver or "all" approvers. The most simple scheme would set all users as approvers at the site level, and require only one approval. The most complex scheme would be to assign certain persons as approvers for each folder, and require the whole set of people to approve the document. The more complex the scheme, the more work it may be to move a document through approval, and the more difficult it will be to maintain as users change. Regardless of the scheme, PIER Users are selected to the list(s) as Approvers independent of the permissions that they have. (See People - Users and Contacts in the Additional Information area below.)

Any document draft can be sent for approval, and every PIER User on the Approver list will be notified. If the PIER User working with a draft is actually an Approver, they will be shown the "Publish" and "Publish & Send" menu links. Awareness of the "Draft Status" is useful when considering Approving and Publishing, as these can be separate operations. 

When an Approved document is Published, it may be available immediately on the External Web Site and on RSS feeds (see Folder Access Level). This is often called "general distribution". Published Documents are also available for Distribution. (This is described fully in another concept document titled "Distribution".)

The Recent Update feed for your site will list the "latest" published documents for your site. If you have cause to back-date a document (to fix a link or a typo), you can reset the publish date when editing the draft under the "Advanced Properties" area, by setting the "Time" value. When published, the document will show in the Recent Update feed according to the date you specified here.

File listings and RSS feeds will show the files in the order that they are placed in the folder. By default, this is in order of "real" recent activity. You may "Reorder Published Documents" in the folder (there are manual methods, or "by date", or "Alphabetical" operations available).

Unpublished Documents have no "published" drafts, and are accessible only by PIER Users on the "inside" of the site. Those documents may:

  • be accessed through a document list
  • be accessed through a search (by keyword or document number)
  • be emailed to other PIER users
  • be re-drafted (and have multiple drafts)
  • be approved (by someone on the Approver list) and then published
Published Documents have one "published" draft and may
  • be distributed to contacts
  • be found via document search on the web site
  • be viewed via a distributed link (such as mydomain.com/go/doc/site/docnumber)
  • be available on the web site, recent updates, and RSS feeds (depending on other security parameters)
  • be re-drafted and processed through approvals even while the published draft remains in that status
  • may be un-published or archived
Archiving a document will move all drafts to "Archived" status and move it out of the regular paths where Published documents are visible.
If there was a published draft at the time of archiving, the document many found in two ways. 
  • At the bottom of a folder list, a "View Archives" link will be generated, and
  • A document search will yield archived documents if they meet the search criteria.

Document Activity Notifications

PIER Users can be automatically notified of Documents that are Approved or Published. This notification is set in the "Settings>>System>>Email Notifications" screen with a simple Yes/No selection. The actual notification is executed through the applicable "Approval List" for the Document (which can be per-folder if approvals are set that way or for the whole site), and then to the Email address for the PIER User credentials of those Approvers. There is no automatic notification mechanism for Contacts or non-Approver PIER Users.

Gateway To Document

There is a special Gateway system in PIER that provides for Document creation and even publishing. Normal permissions apply, and validation is associated through the PIER User telephone number matching the SMS device submitting the document text.

Special Folders

Certain Folders can be designated for special purposes on the PIER Site. The first is the "Templates" Folder from which the first 10 Documents are listed under the "New Document" menu item. This is a hard-coded specification for each site.

The second is the "Answers" Folder selected to support Inquiry activity from the Settings>>Inquiries>>Answers screen. The Documents in this folder will be listed in a drop-down list on the screen available for "answering" inquiries.

Locating Existing Documents

When logged on to the "Inside" of the PIER site, you will find that the Documents Tab in PIER is organized by Folder, then separated into 3 columns according to the status of the drafts of the documents. Sub-folders are revealed when you press the "+" icon on the parent folder. You can navigate through the folders to locate documents. If your document has been archived, click under the number in the right column. If your document has a current, published draft, click on the number in the middle column. When your document is under development and has no published drafts, click on the number in the left column.

You may also search for documents by keyword or document number. The search criteria are NOT case-sensitive ("Fire" = "FIRE" = "fire"). The Advanced link allows selection of a "creation date" range.

For the outside of the site, documents can be located in many ways. Normally they are available under the common "News & Information" menu for the site, under folder listings. They can be shared through distribution of the document, distribution of a document URL, placed on the menu with custom links, or linked with documents or other pages on your site.

Additional Information