PubMan™ User Guide

Updated 2009-06-02

Show Contents    Hide Contents

1. Overview

Organizations that create or acquire large amounts of content need to move beyond the use of file names and folders or directories to keep track of materials. They need a Content Management System (CMS) to house and manage their most important asset: information.

A CMS will consist of these basic components or functions:

• A Database to store and keep track of the content.
• A User Interface (or UI) to interact with the database and make the content accessible.
• User management and workflow for checks and balances on who is allowed to work on files and in what order.
• Locking to ensure that documents are changed by only one authorized user at a time.
• Versioning provides safety, accountability, and change tracking capability by maintaining each successive version of Documents.

PubMan is a powerful, user-friendly Content Management System (CMS) that stores, organizes, and provides easy access to collections of digital resources. It is used predominantly by various types of publishers for storage of textual assets.

PubMan stores content in a database accessible to authorized users over the internet. It organizes each discrete piece of content within the database and tracks it from creation to publication. In addition, metadata (descriptive information) associated with the content is stored—work history, relationships to other content, etc. Each time changes are made to content, the previous version of it is stored, providing a safe means to revert to an earlier state if necessary, or review changes between versions.

PubMan allows users to create, search, view, extract, edit, and manage textual content in a non-proprietary, self-describing format, XML (eXtensible Markup Language). Administrative users have tools to manage users, workflow, perform advanced content management tasks, and create reports.

What You Will Need to Know 

Certain assumptions have been made about PubMan users. All should be computer literate, with the ability to understand the operation of a web browser, use of menus and dialog boxes, and other basic editing or word processing functions. Users also need to know how to download, save, locate, and upload files from their computer.

To use PubMan, you will need:

• Internet Explorer 7.0 (or later). Other web browsers may work, but are not guaranteed to provide all PubMan functionality.
• High-speed internet access.

Certain browser and computer settings are necessary for PubMan to work properly:

• Add the web address for your PubMan site to your browser's list of trusted sites.
• Add the address to your list of sites that permit pop-ups. Do this in any other pop-up blocking application you utilize as well.
• Allow active content from the PubMan site because certain functions may cause your browser to display a warning about 'active content' the first time you use them.

For a full listing of all browser settings recommendations, see Browser Settings for PubMan™

To edit textual content you have extracted from PubMan, you will need:

• An XML editor.
• Some basic XML skills.

How This Guide is Organized 

Chapters covering three skill levels—Basic, Intermediate, and Advanced—begin the guide. A chapter on Administrative Functions follows, and various Appendices provide reference materials. The Basic PubMan Skills chapter is essentially a tutorial, designed to get new users up and running quickly with core PubMan skills and terminology. Subsequent chapters are less tutorial-like, providing a guide and reference to specific features and functions.

2. Basic PubMan Skills

Document Organization Basics 

PubMan uses a simple two-tier organization of content in which a Title is the top level and a Document is the second. Each Title is simply a collection of Documents. Each Document you create or work on will belong to a Title. Title Groups are collections of like Titles.

Understanding Access Control: Permissions Basics 

What a user is allowed to do within PubMan is controlled by administrative settings referred to as Permissions. Your administrator has configured each user's account with Permissions that determine whether they can see (view) or make changes to (edit) Documents within a given Title. Permissions will be covered in more detail further on but for now all you really need to know is that anything you can see you have either a View (V) or Edit (E) permissions setting for. A 'V' setting means you can look at a document but not make changes to it. An 'E' setting means you may view and edit a document. While most of the options you are presented with during your PubMan session are controlled by these settings—meaning PubMan does its best to not show you that which you do not have permissions for—you may receive a message at some point that you have asked for something you do not have permissions for. For example, you will be denied any function that would allow you to make a change to a document for which you only have 'V' permissions.

Safeguarding Content: Locks, Check Out, and Check In 

One of PubMan’s primary functions—along with controlling who has access to what—is to play traffic cop to a large number of users accessing the same content, keeping everyone from running over each others work. You will frequently see the term “Lock” in this manual, which refers to the ownership of a document or documents by a particular user. When someone “locks” content they take ownership of it, usually for the purpose of making changes. The act of locking content is most often a part of the “Check Out” process, which is how users extract content from the CMS. PubMan keeps track of who is working on what, and will prevent other users from making changes to this content until the user who created the lock returns it to PubMan. When the content is returned via the “Check In” function, the lock is released.

With the basics of PubMan's content safeguards and organization in mind, you're ready to log in and put it to work.

Logging In 

Using the information provided by your PubMan administrator:

• Launch your web browser and open the url for your PubMan site.
• Log in using your user id and password.

Figure 2.1: The PubMan Login Page

Locating Documents 

PubMan functions are grouped into Actions, Lists, CSA, and Filters in the navigation bar on the left side of the web pages. Menu functions related to locating, viewing, and editing Documents are:

Under Lists:

• Titles displays a list of Titles and information about them.
• Documents displays the list of Documents from the current Title.
• Locks lists all locked Documents.

Under Actions:

• Check In allows you to upload files containing new or previously locked Documents to PubMan.
• Check Out allows you to download content (by request) from PubMan.

Under Filters:

• Title Group allows you to restrict your lists and menus to Titles in a selected group.

The first time you log in, the Titles page will appear. From this page, selecting a title (click on either the tag or name) will bring you to a Documents page listing all of the Documents in the current Title. The listing breaks them down into groups of 20. In this chapter we'll cover the basics of navigating this list and viewing the documents in it.

Figure 2.2: The List Titles page

PubMan is all about maintaining order, and to do that with a collection of documents you have to have a way to sort them. PubMan uses something we call a “sortkey”. Sortkeys are covered in detail further on in this guide, but for now you need to know that this key is either an alphanumeric string (just a group of a-to-z or numeric characters without space) or a date. PubMan sorts either in ascending order.

Figure 2.3: The List Documents page

To move through a Document listing you can use either the Go to: box or the page navigation arrows at the upper right-hand corner of the list.

• To use the Go to: box to find a document: enter a partial sortkey (or a whole one if you know it) into the box and press Enter. PubMan will find the closest match to the key you entered, i.e. if you type “ja” and press Enter you'll go to the sortkey “jack” if that's first key beginning with “ja” in the current Document list.
• To use the arrows:
  • << takes you to the beginning of the list
  • < takes you to the previous page
  • > takes you to the next page
  • >> takes you to the end of the list

Viewing Documents 

To view a Document, select it from the Documents list by clicking on any hyperlinked part of the listing (the sortkey or name). This opens a Document display page that displays the Document and a whole plethora of information about it:

• A main document frame will display the text of the document.
• A Versions list will show all of the previous versions of a document, listed by the user who worked on them and a time/date stamp.
• A Linked To list will show all of the documents this document has links to.
• A Linked By list will show all of the documents this document is linked from. (More on links later.)
• An Also Found In list will show other documents in the CMS bearing the same sort key (sorted by the current title first).

While there are plenty of functions to choose from here, we'll look at most of them further on. For now the most useful to point out is that you don't need to return to the Documents list to make your way to a different Document. There's a Go to: box here that works just the same as the one on the Documents listing, as well as Prev and Next links that will scroll you through the Documents in the list you entered from.

Figure 2.4: The Document Display page

Editing Documents 

There are several ways to extract documents from PubMan depending on whether you intend to change them or not, and how many you wish to extract. You can extract documents by:

• Checking out a document via the C/O button in a Document listing or the Check Out link on the Document display page is the best option when you are working on an individual document.
• Checking out documents via the Check Out form (launched by selecting Check Out from the Actions list on the left hand side of a page) is best if you are going to work on several documents and they fall within a sequential range of sortkeys.
• The Check Out form is also the best means of extracting content for purposes other than editing. We will go over options for extracting content in different formats later, so for now just remember when that need comes about this is your best bet.

The Check Out form lets you submit a request for a range of documents, and has the following fields:

• A pulldown for selecting the Title (or Package—more on those later) to retrieve the Document(s) from
• A text box to enter the first sortkey in the range
• A text box to enter the last sortkey in the range, or...
• A text box to enter the number of documents to extract (starting from the first sortkey)
• An option button for selecting whether to lock the document(s) or not
• If you choose not to lock the document(s) you will be presented with additional format options.

Figure 2.5: The Check Out form

Any time you make a request to Check Out content it will be delivered to you as a file. When prompted to download, select the Save button on the File Download dialog and store the file on your hard drive.

Figure 2.6: The Check Out download prompt

Once you have saved the extracted content locally, if you have locked it for editing you can make alterations to it via whichever application you use to do so. In the case of XML content, this is generally an XML editing application. It is assumed that you have been trained in whatever applications are employed by your company, so the editing part of things is beyond the scope of this manual. Let's move to returning content to PubMan.

Returning content to the system is quite simple:

• Select Check In from the Actions list
• Select the browse button from the pop up form
• Locate and select your file.
• Select any Packages you want your document to be a part of.
• Click the Upload button

Figure 2.7: The Check In form

Once PubMan has uploaded the file and put away the Document(s), a message will confirm that check in is complete. In a subsequent chapter, we'll look at how to handle any errors that may occur on check in.

More About Locks. . . . 

You may at some point make a request for a Document that has been locked by another user but PubMan does its best to advise you about any Documents that are locked:

• The Document listing will not display a C/O button for a Document that is locked, instead shows the name of the user who has it locked.
• The Document display page will not offer a Check Out link for a document that is locked.
• If you make a request to check out a range of documents containing one or more locked documents, you will be given all the documents you requested except those that are locked. A message on the Check Out form will tell you which documents you did not receive.
• Pubman will proactively let you know that you have locks on documents by highlighting, in red, the "Locks" menu item in the Lists section on the left hand side menu.

You can always refer to the Locks page to see which Documents are locked at a given point. It lists all of your locks along with a set of information about them. This page has some endearing features should you have a file management mishap:

• Sometimes you forget the name of the file you downloaded when you checked out content. The locks listing provides you with that filename. If you didn't change it when you saved the file, this is what you're looking for. Likewise, if you saved it to a location you do not remember you can run a ‘find’ (Start->Search) on this filename and locate it.
• You may lose (temporarily we hope) a file you have downloaded and be unable to check it in and release the lock. In any event that requires you to release a lock without returning the content, you may release your own locks (but no one else’s) via the button in the Rel column of the lock listing. Releasing a lock can also be handy if you managed to completely dismiss a Check Out request without downloading a file. (It happens.) You can remake the request if you release the lock your first request created.

Note also that you can use the button under the C/I column of the lock listing to check in a specific file of documents.

Figure 2.8: The Locks Listing page

Filtering Your Session Using Title Groups 

When a system contains a number of Titles it is helpful to classify them according to their nature and/or the groups of users that most frequently interact with them. PubMan™ uses Title Groups to do this, and you can filter the options PubMan™ presents you with by selecting which Title Group you would like to see during your session. The default setting is “all”, meaning you will be presented with options for all Titles you have permissions to. You can narrow this down by selecting Title Group under Filters, and selecting the group of titles you want to work within. Once you have selected a group, your Titles list, search options, check out options, etc. will only show members of this group.

Figure 2.9: Selecting a Title Group

Putting it to Work 

Hopefully, to this point you've been playing along and exploring the pages and functions covered in this chapter. If you have the opportunity, now is a good time to try out the document navigation functions we've covered and move documents out of the system and back in. Users with access to a live PubMan system usually have test Titles—we sometimes refer to them as a “sandbox”—which they can use to learn PubMan skills. These Titles contain only copies of data and aren't “live” so you can practice without fear of damaging valuable content. If you have access to such a Title try checking out a document, making some changes, and putting it back in. Review how your work affects the appearance of the different pages we have used.

Creating New Documents 

Creating new Documents in PubMan is done by using a template. Templates may be provided within PubMan itself, or for use within an external XML editor.

To create a Document from within PubMan:

• Select New Doc from the Lists menu on the left. This will open the New Document page.
• From the Title dropdown list, select a Title to create the new document in.
• From the Template dropdown list, select a template to use.
• Fill in the Doc Name, Guide Word, and Sort Key fields. If you want, you may use the Gen. Sort Key button to create a sortkey for you.
• Fill in any additional fields that you are familiar with.
• When you are done filling in the form you can choose to:
  • Select Save to save the new document and move on to other work.
  • Select Save and Edit to save the new document and open it in an editor (either Quick Edit or Quick Edit XMAX).
  • Select Save to save the new document, then Clear to clear the form so you can create more new documents.

Figure 2.10: The New Document Page

To create a document with an external editing application:

• Create a new Document from a template provided for a specific Title.
• Load the document into PubMan via Check In.

If you are unable to locate a specific template that you need, contact your system administrator.

Where to Get Help 

If you need help, the latest version of this manual is always available from the Help link in the system functions residing at the upper right-hand corner of almost every PubMan page. Along with the tutorial and explanatory sections of the guide there is also a chapter on trouble-shooting that contains materials based on issues we most frequently receive questions on. If you need support there is a Support link in the same location that will open a form for you to submit a support request with.

Exiting PubMan 

To end your PubMan session select Logout from the system commands at the upper right hand part of any page.

The balance of the chapters that follow are written less in a tutorial manner and more of an explanatory manner. They assume you are comfortable with PubMan basics, and acquaint you with more advanced functions the system has to offer. If you have any trouble understanding PubMan terminology (we’re sometimes a little free with our words), we’ve put together a Glossary at the end of this manual.

3. Intermediate PubMan Skills

Packages 

In PubMan, Packages are lists of Documents with some special properties:

• Each item in the list is a link (sometimes we call it a “pointer”) to the current version of a Document (not an actual Document). This makes Packages dynamic.
• The Documents listed in the Package can be from more than one Title.
• The Documents listed do not have to be sequential.
• The Package list can be sorted independently without affecting the parent Title(s).
• Deleting a Document from a Package list does NOT delete it from the parent Title.
• Packages have their own Permissions.
• Packages can be shared among users.

Generally, Packages are used to:

• Create groups of documents for checkout, review, workflow tasks, or derivative publications
• Store search or report results
• Assign permissions at the document level

When you create a Package you will be prompted to give it a name and then set permissions for it. You are considered the “owner” of the Package, and by default the owner is—at least initially—the only one who can edit the Package list.

The permissions settings of Packages control who is able to see the list or make changes to it, and the changes you are allowed to make to permissions or other Package settings are further regulated by your type of user account. A non-administrative user can only set permissions for a Package to ‘V’ (View) or ‘N’ (None). Administrative users can set Package permissions to ‘N’, ‘V’, or ‘E’ (Edit), giving them the capacity to control document access at a more granular level than via Title permissions.

To accomodate the variety of uses a Package may be used for, there are three types of Packages:

• Private packages are for the use of the individual who created them. The creator of the package is the owner and the only one who can see the contents and change permissions.
• Shared packages are used when you have created a list of documents to be that you want other users to be able to view or edit. It is important to emphasize that when we say “edit” here we mean the list, not the documents within it. If you set a package to be shared:
  • Users who you share the package with will be able to add or delete documents from the package list.
  • Users who you share the package will not be able to see documents in the list that they do not have permissions to.
  • The creator is still the owner of the package, and the only one who can change permissions settings for it.
• Admin packages are used to control permissions to documents. They may not be shared. Only administrators can create or modify these packages.

Packages can be created by:

• Clicking the Packages navigation link and from the Package list window and selecting the New Package link at the bottom of that page. Filling in the form creates an empty Package for you to populate.
• Saving Search or Report results as a Package.
• Selecting Documents via the checkbox at the left of a Document list and selecting <New Package> from the Add to Package dropdown menu selection.

Figure 3.1: The New Package page

You can add documents to an existing Package by selecting Documents via the checkbox at the left of any Document listing and using the Add to Package dropdown menu to select the package you wish to add them to.

You can delete documents from a Package by selecting their checkbox on the Package documents list, and clicking on Remove selected docs.

The use of Bulk Package Operations—accessed via Bulk Operations on the Package document list page—is covered in the Advanced PubMan Skills chapter.

Figure 3.2: The Package Document List, Detail

Where Package Functions are Located 

The Package link under the Lists function group on the left side of every PubMan page opens up the Packages listing page. This page lists all of your Packages, and any shared with you by other users. On the Packages page:

• All live, i.e. hyperlinked column headings indicate the list may be sorted by clicking on them.
• Selecting a live item in the listing will bring up the listing of Documents in the selected Package
• You may multiselect Packages to use the Delete Selected Packages function
• Selecting the button under Details will open a Package Details page, showing: ownership, name, date created, a notes field, any workflow tasks associated with the Package, and the permissions settings for the Package. You may alter the Package properties here, and there are command buttons for saving or cancelling those changes. You may also delete a Package from this page.
• Selecting the button under C/O column lets you check out (and lock) all the Documents in a Package at once. This option will not be available if any of the Documents in the Package are already locked.

Other places you will see functions for working with Packages:

• Most pages listing Documents with have an Add to Package dropdown.
• The Check Out page will let you request documents from a Package.
• On the Search page. When results sets are displayed you can save them as a Package.
• On certain Report forms, where you can request report results as a Package.

Figure 3.3: The Package List Page, detail

A Note About Editing Permissions Settings 

On every page where you can set permissions, there is a time-saving feature you can use to spare yourself from having to set each user's permissions individually. The Copy from Package: pulldown lets you copy the permissions settings from another Package. If you have to use the same settings frequently, you can set up generic Packages bearing these settings and keep them for the purpose of copying them. (Just remember when you change the base settings it does not update any Packages you have already applied them to.)

Understanding Links 

While the details of how links—also called references, hyperlinks, etc.—vary between installations (and then sometimes further between document types), now is a good time for you to understand the basics of what they are and how they work if you don’t already.

The process of enriching content (usually) at some point requires you to establish relationships between certain elements it is composed of. The most basic of these relationships is a one-to-one reference between two elements, such as a cross-reference between dictionary entries, where one entry references another containing information related to or mentioned by content in the first. This implies a set of terms we use in PubMan to describe two such elements: one is a pointer, and one is a target. The pointer is a reference to the target. So far so good.

Now, there is one property a link must have to work and that is that the target must be uniquely identifiable. Otherwise, who’s to know what you’re pointing at? So, we'll hit you with another term you need to know: unique identifier, also sometimes referred to as ID or UID.

Problems with links happen when:

• There is more than one link target with the same UID.
• There is a pointer that does not have a corresponding target.

PubMan has many powerful features that manage identifiers, track links, and provide functionality based on the relationships they establish. Having this baseline understanding of them will help you capitalize on the features described in the balance of this guide.

Any training for creation of links within your specific editorial environment is outside of the scope of this manual, but it is likely your administrator will see to it that you receive it.

Where You Can Find Link Information 

If your PubMan system has been configured to keep track of links, you’ll see information about them on the Document display page. PubMan scans a Document for link information each time it is checked in, storing what if finds out about link targets and pointers, as well as automatically assigning identifiers to link targets that are new.

Your stylesheets may be configured to display or act on links in a certain fashion within the Document display frame, and at the very least there will be a Links To list that shows references from the Document and a Linked By list showing links to the Document. These listings are active links that will take you to any Document you select from them.

This is good information to have prior to making changes to Documents, since without it you might make alterations that could adversely effect—or even break—references between Documents.

If you need more detail about linking information, you can select the Show all links option. This will open a new page with a table you can use to list three kinds of related documents, using the Show documents drop down menu:

• referenced by this one—lists all documents the current document links to
• which reference this one—lists all documents that link to the current document
• with the same name—lists documents in other Titles which have the same document name

Other functions available on the Show all links page:

• You can sort the document listing by any of the hyperlinked column headings: Link type, Title, Sort Key, or Doc Name.
• You can view a document in the listing by selecting its Sort Key or Doc Name. Any of the available display options will be given in the Format: dropdown.
• You may add a displayed document to a package using the Add to package: function.

Figure 3.4: Show All page

PubMan also has reporting features that check up on links and any issues there may be with them, which are covered in the Advanced PubMan Skills chapter.

Using Quick Edit 

Quick Edit is an option on the document display page that allows you to lock, edit, save, and unlock a document right in the browser, without any need to download the file locally or upload when your work is done.

There are three different in-browser editing applications available. PubMan™ loads the appropriate one depending on the type of document you are editing and on system-wide configuration settings. If the document is in XHTML, your editing environment will be a special-purpose XHTML editor. If you are editing any other document type, and if you have a PubMan™ installation that is configured to use XMetaL® Author ActiveX (XMAX), your in-browser editing environment will be a full featured, validating XML editor. Otherwise, your editing environment will be a non-validating, plain text editor.

The three environments are described as Quick Edit/XMAX, Quick Edit/XHTML, and Quick Edit/Plain Text in the following sections. Read whichever is pertinent to your situation. If you have any questions as to whether you have XMAX®, contact your system administrator.

Quick Edit / XMAX® 

To use Quick Edit / XMAX:

• Select the Quick edit link at the upper right hand corner of the Document display frame on any Document display page. The Document will be locked and a page will open with the Document in an XMAX® editing control. If you are an XMetaL® Author user (most PubMan™ users are) the environment will look familiar.
• Make your changes to the Document. You may save your changes at any time by using File->Save to Temp File.
• Use the File->Check In Changes menu selection to end your editing session and check in the document, or File->Discard Changes menu selection to exit without saving changes and release the lock. You will be asked to confirm that you wish to discard changes.

Figure 3.5: The Quick Edit / XMAX® page

Quick Edit / XHTML 

To use Quick Edit / XHTML:

• Select the Quick edit link at the upper right hand corner of the Document display frame on any XHTML Document display page. The Document will be locked and a page will open with the Document in an XHTML editing control.
• Make your changes to the Document.
• Use the Save Changes button to store your changes, or Cancel Edit button to exit without saving changes.

Figure 3.6: The Quick Edit / XHTML page

Quick Edit / Plain Text 

Using the non-validating, plain text version of Quick Edit comes with a couple caveats:

• If you are uncomfortable editing raw xml, please do not use this feature.
• Do NOT cut-and-paste text from other applications into Quick Edit. You run the risk of introducing improperly encoded characters into your xml.

  Note: Whether this is a risk or not is determined by the type of character encoding is in use. Your administrator may tell you this is acceptable behavior.

To use Quick Edit / Plain Text:

• Select the Quick edit link at the upper right hand corner of the Document display frame on any Document display page. A page will open with the Document in a text editing control.
• Make your changes to the Document.
• Use the Save button to store your changes, or Cancel button to exit without saving changes.

More About Sortkeys 

In the Basic PubMan Skills chapter sortkey essentials were covered. Here we elaborate on them a bit.

If a Title has more than one Document using the same sortkey there could be what we call a “sortkey conflict”. This is usually resolved by adding a numeric suffix to the sortkey. This suffix is usually in the '000' format counting by fives, and will be used to sequence Documents with the same (root) key. For example, a dictionary may have more than one entry (Document) for “dog”, and in that event the sortkeys “dog”, “dog005”, “dog010”, etc. could be used. (We count by fives so you can always squeeze one more in where you want it.)

If there is an existing sort key with the value you need to assign a new Document, add a numeric suffix to the key. This may not be necessary if you know for fact that your PubMan is configured to deal with these conflicts for you (read on).

You will get an error if you check in a new Document with a sortkey conflicts with an existing one, i.e. a Document is already stored in that Title with the same sortkey. You will need to alter the sortkey (most likely by adding a suffix) and go through the check in process again. Most PubMan systems are configured to work around this by adding a suffix automatically if necessary—so instead of getting an error you'll just need to be aware that a suffix may be added on the way in. (Handy knowledge next time you go looking for the Document).

You can alter existing sort keys (assuming you have proper permissions) by editing them within PubMan or within your XML editing application. In PubMan there is an 'E' button next to the sortkey on any Document Listing page for doing this.

Document Properties You Can Change Within PubMan 

On any Document listing page with PubMan, if a column entry has a small E button next to it, this indicates that you can edit this property without checking out the document. Just click on the button and enter the desired text in the prompt that pops up. When finished click on the OK button.

Figure 3.7: Detail from Document Listing page showing editable properties

Note that Package listings allow you to edit the Package name in the same fashion.

Searching 

To search in PubMan™ for documents meeting a certain criteria, select PMSearch from the Actions list. PMSearch offers you three types of searches:

• Full-text. Finds a word, words, or phrase anywhere within the full text of a document. This search is not case-sensitive, and ignores punctuation, i.e. a query for computer failure will draw a hit on . . . computer? Failure . . ..
• Words ... within. Finds a word or words appearing within select XML elements or attributes. Enter the terms you wish to search for in the Words text box, and a list of the elements or attributes you wish to search within (separated by spaces) in within. Precede attribute names with a '@' character. This search is case-sensitive (both terms and element names).
• XQuery. Performs an XQuery search. XQuery is a language designed specifically for querying XML documents.

  Note: XQuery search is primarily aimed at advanced users. Most basic or intermediate users will use XQuery searches that have been pre-built for them.

The PMSearch form has three areas: Find, Results, and Queries, which are used to enter queries, list results, and manage queries respectively.

Figure 3.8: PMSearch Find Area

To run a search:

• Decide which of the three types of queries you will use. In the Find area, enter the words, string, and any elements you will restrict the query to.
• Use the Look In list to select the Title(s) or Package(s) you wish to run the query over. You can use the Titles or Packages link to toggle between the two, and Select All and Clear All functions are also available.
• If you are going to restrict the search to a certain range of documents, use the First Sort Key and Last Sort Key boxes for doing so.
• Use Run Query to start the search. The Results area will list documents that met your search criteria. Results are shown in a document list similar to any other in PubMan. You can view a document from the list by selecting it. It will appear in a popup page that gives you a choice of the formats you would like to view it in, and a Highlight terms option that highlights search hits.

  Note: For Words ... within and Full-text searches, the Highlight terms form will automatically fill itself in with your search terms and highlight them. For XQuery searches—where it is not possible for the program to accurately separate the search criteria from the query syntax—this is not done automatically. All you need do though is enter any words you want highlighted in the Highlight terms text box, and hit Go.

• You can use Save As Package on the Results area to save a results list as a Package.

Figure 3.9: PMSearch: Results Area

Figure 3.10: PMSearch Results: View Document

Each time you use PMSearch is considered a “session”. During your session:

• Clear Fields can be used to clear all of the search form fields in the Find area.
• All of your queries will be automatically saved for you, and they will be listed in the Queries area.
• Save Query can be used at any time to save the query entered in the Find area—even when it has not been run.
• New Session will clear all areas on the page. Any queries you have not chosen to save will be erased.

The Queries area lets you manage your queries.

• Load will reload the query, which permits the user to alter it before rerunning.

  Note: This feature allows you to set up templates for frequently used searches, which can be modified to suit.

• Clicking on the small E button next to the query allows you to change its title. Just click on the button and enter the new query name in the prompt that pops up. When finished, click on the OK button
• You can save a query for yourself by clicking the save query button in the Find Area or by toggling the Per (permanent) column setting to Y. A saved query will persist across sessions, remaining available until you delete it.
• You can share a query with others by toggling the Pub (public) column setting to Y.
• You can delete a query using the Del button.

Figure 3.11: PMSearch Query Area

Search Details: Full Text Searches 

In addition to its word search capability, Full-Text search has the following advanced features:

• Phrase search: Matches an exact word or a phrase. To perform a phrase search, use quotes around your query. Ex.: "ice hockey"
• Prefix search: Use '*' to find all forms of a word or phrase with a certain prefix. Use quotes around this type of search too. Ex.: "mono*" will find monographic, monotone, etc.
• Proximity: Use '~' to find one term near another. Ex.: apple ~ pear or apple NEAR pear find 'apple' near 'pear'.
• Booleans: AND, OR, AND NOT. Use booleans to add conditions to your query. Ex.: acts AND "first session"; abridgement OR analyze; grapefruit AND NOT tangelo

  Note: You may also use & for 'AND', | for 'OR', and &! for 'AND NOT'

• Inflectional search: Broaden a query for a word to find inflections. Ex.: FORMSOF (INFLECTIONAL, act) will find 'acted', 'acting', etc.
• Weighting: You can specify a weight value for each word or phrase in a query to affect the rank of result documents. A number between 0.0 and 1.0 is used as a weight value. Ex.: ISABOUT (act weight (.8), abridgment weight (.4))
• Thesaurus: If you have a thesaurus you wish to use to map replacements or expansions for words, please contact us and we can assist in integrating it into your PubMan system.

Search Details: Words/Within Searches 

Here are examples of the two types of search you can use Words/Within for, searching within a particular XML element, or within a particular XML attribute:

• To search within an XML element: Words: Mazzei Within: name would search for documents where “Mazzei” occurs within the XML element name, i.e. it would bring a result for a document containing . . . <name>Phillip Mazzei</name> . . . anywhere within it.
• To search within an XML attribute: Words: Letter Within: @docClass would search for documents where “Letter” appears in the value of the XML attribute docClass, i.e. it would bring a result for a document containing . . .<doc docClass="Letter">. . . anywhere within it.

If your XML uses namespaces to qualify elements (ask your administrator if you are not sure), you need to use the appropriate prefix when forming Words/within or XQuery requests. If there is no namespace prefix on element(s) you wish to search within, use the form *:elementname when listing them in the within text box. If there are namespace prefixes in the data, use them when you list your elements to search within, i.e. you would enter mods:title to search within the <mods:title> element

Search Details: XQuery Searches 

XQuery searches allow you to locate documents meeting certain criteria in PubMan™ using a subset of the XQuery language. You can construct a path expression using any of the supported expressions, functions, or operators, and any Documents that answer positively (true) to the path expression will be listed in the results.

The path expressions should always begin with the // expression, which will locate a node no matter where it appears in the document hierarchy. From there, the path is built out with further expressions. For example:

//featureRef

would bring back all documents (in the selected Title(s) or Package(s) containing the featureRef element. Note that this is a question about the structure of the document, not its actual text content. Using XQuery searches we can combine both, for ex.:

//name[@type = "recipient"][contains(.,"George")]

would bring back all documents where George appeared within <name type="recipient">. . .</name>.

The contains() function is probably one of the most frequently used when writing XQuery searches in PubMan™. Remember when you are using it or any other XQuery expression that looks for phrases, that the XML may contain multiple white space characters between the words in the phrase. To make sure you get a hit regardless of this, use the xs:token() function to tokenize the value being searched, as in:

//div2[@type = "enclosure"]/note[contains(xs:token(.),"American Biography")]

Which will find any <note> that is a child of <div2 type="enclosure"> that contains the phrase “American Biography” regardless of whether it appeared as:

. . . <note>American Biography</note> . . . 

or

. . . <note>American 
      Biography</note> . . . 

in the XML.

The broad variety of expressions supported in PubMan mean you can do things with mathematical expressions, like:

//entry/hg[count(pos) > 1]

(which would find every <hg> that is a child of <entry> and has more than one child <pos>), and use sophisticated data type casts to work with dates, as this expression does:

//@*:docDate[xs:dateTime(concat(string(),"T00:00:00Z")) = xs:dateTime("1779-06-03T00:00:00Z")]

A full discription of the support in PMSearch for XQuery can be found in the Microsoft® SQL Server documentation. Specific points of interest:

• Path Expressions
• Comparison Expressions
• Logical Expressions
• XQuery Functions against the xml Data Type
• Type Casting Rules

Search Tips and Tricks 

• Searching within results is accomplished by saving a results set as a package, the running a query over it. This can be used to do compound searches where you may need to use one type of search to qualify a results set, then run a second type of search over it.
• For complex queries, build query templates that you can re-use yourself and/or share with other users. For example, craft an XQuery you may frequently use with slightly altered criteria, and use a generic text string in it like “NameToSearchForHere” that prompts you on where to change the criteria before running the search. Save the query, then reload it and alter as needed each time you use it.

Messaging 

PubMan’s messaging functions, available from the Msgs link at the top right of your screen, are designed for communications about content within PubMan and are very similar in functionality to common email systems. Messaging provides an effective means of exchanging (non-annotative) information and insuring it has been read by its recipients. It also provides the means to archive and organize these work-related messages into folders for later review or action.

Whenever a user opens (or is already working in) a PubMan session and has unread messages, the Msgs link will be red and the number of unread messages will be displayed. Clicking on Msgs brings the user to the Messages page. The default message list is the user’s inbox, and unread messages will be in bold.

Figure 3.12: The Messages page

The Display Folder dropdown menu allows the user to view other folders and the Compose New Message link opens a blank message.

Figure 3.13: The New Message form

The message list shows the following fields:

• From. The sender of the message (shown in the first column of the Inbox folder).
• To. The recipient(s) of the message (shown in the first column of the Sent folder).
• Subject. The topic of the message.
• Title. The Title the message is associated with if this option was used by the sender.
• Sent. The date and time the message was sent.

You can sort by any of the column headings that are linked on the Messages page, and a checkbox next to each message listing allows you to select it to apply an action via the Move To Folder dropdown menu.

Clicking on the subject name of a message will display the message on a page with options to Reply, Reply to All, Forward, or Done to close the message.

The message display page also has a Move to Folder dropdown. Here or on the message list page users can create their own folders by selecting (New) from this menu.

Figure 3.14: The Message Display page

4. Advanced PubMan Skills

The Concept Scheme Application (CSA): Organizing Documents by Subjects 

To respond to the need to organize documents by subject, PubMan now has a Concept Scheme Application, or CSA for short. The CSA allows users to:

• Define Collections of subject classifications. These classifications are organized into Groups.
• Assign Properties to each subject, such as a name, description, dates, annotations.
• Link documents to subjects.
• Browse documents by subject.
• Import and export XML definitions of subject classifications and the documents they link to. The import feature allows loading any such existing information, and the export feature allows publication of the subject classifications, which may be used to drive web portal features.

CSA Browsing and Editing

To best understand use of the CSA it helps to have some familiarity with how a taxonomy works. Wikipedia has some most helpful text in its definition of 'taxonomy':

Originally the term taxonomy referred to the science of classifying living organisms (now known as alpha taxonomy); however, the term is now applied in a wider, more general sense and now may refer to a classification of things [such as documents], as well as to the principles underlying such a classification.
The term taxonomy may also apply to relationship schemes other than parent-child hierarchies, such as network structures with other types of relationships. Taxonomies may include single children with multi-parents, for example, "Car" might appear with both parents "Vehicle" and "Steel Mechanisms"; to some however, this merely means that 'car' is a part of several different taxonomies. . . .

We’ve highlighted “network structures” in the preceding, as that is precisely how the CSA lets you organize your subjects. Rather than being stuck in a parent-child hierarchy of subjects, where each subject can have only one broader association, in the CSA each subject can have multiple links to broader, narrower, and related subjects, allowing you to build a web of subjects. For example, a subject of 'Pablo Picasso' might have multiple broader associations to subjects like 'Spanish Artists', 'Collage', or 'Surrealism', which may in turn have their own sets of associations, forming a semantic web of subjects and related documents. The CSA Browse/Edit tools are used to browse and edit your subject webs.

Browsing Documents by Subject

• Select Browse/Edit from the CSA list, which will open the CSA Browse/Edit page.
• From the Collection dropdown list, select the subject Collection you wish to work within. When you select a Collection, the subject Groups associated with that Collection will populate the Group list. Use that list to select the subject Group you wish to work within. On selection of a Group it will load into the the three list areas that show the Current subject (center), its Broader subject associations (left), its Narrower associations, and its Related associations (center beneath). When first loaded, the [Top Level] will be listed as the current subject.

  Note: [Top Level] serves as the “root” of the subject web, and has no broader subject associations.

• To navigate the subject web, you just double-click on a subject in the Broader or Narrower subject area. The subject you select will become the Current subject. All documents linked to the Current subject will be listed in the Documents area. If you have a subject highlighted in the Broader or Narrower areas, you may also use Select to load it as the current subject.

Figure 4.1: PubMan CSA Browse Edit Page Detail: Subject Group Selected, Top Level Loaded.

Figure 4.2: PubMan CSA Browse Edit Page Detail: Subject and Document Links Displaying.

Viewing and Editing Document Links

As shown in the preceding figure, documents linked to the Current subject are displayed in the Documents list. The count of the documents within the subject is also displayed.

• As with most PubMan document lists, you can use the Go to: box to find a document: enter a partial sortkey (or a whole one if you know it) into the box and press Enter. PubMan™ will find the closest match to the key you entered, i.e. if you type “ja” and press Enter you'll go to the sortkey “jack” if that's first key beginning with “ja” in the current Document list.
• You can view any of the documents in the list by clicking on their Sort Key or Name.
• To remove documents from the list—unlinking them from the subject—select them and click on Remove checked documents.
• To link documents to the subject, click on Add documents. This opens the Add Document Link page, which has the familiar PubMan document list displays and option. Locate the documents in a Title or Package you wish to link to the current subject. You can either
  • use the check boxes to select individual documents, then click on Link checked documents; or . . .
  • . . . if you are working with a Package document list, use Link entire package to link all documents within it to the current subject.

  Note: You may already have realized that using saved search results and Link entire package is a powerful means of performing bulk linking of subjects and documents.

• Dismiss this page when you are done.

Figure 4.3: PubMan CSA Add Document Pointer Page

Editing Relationships Between Subjects

• To remove a broader or narrower subject relationship, select the subject you wish to remove from list of associations to the Current subject, and use Remove.
• To add a subject relationship, select Add from the Broader or Narrower area. The will open the Add Subject Link page.
  • If there is an existing subject you wish to create a link to, use Browse Subjects to locate it. Load the target subject as the current subject and select Link. You can repeat this process if there are multiple links to be made.
  • The New Subject area lets you create a new subject. Enter a Name for it, and click on Create, which will create the new subject and make the link.

    Note: You can edit the properties of your new subject using the Subject Details page. See Viewing or Editing Subject Information below.

  • Dismiss this page when you are done.

  Note: On returning to the CSA Browse/Edit page, click on Refresh Links if your new subject associations are not shown.

Figure 4.4: PubMan CSA Add Subject Link Page

Viewing or Editing Subject Information

• To view the details (properties) of a subject: In Browse/Edit, select the subject as the Current subject (if it isn't already). Click on Details, which will open the Subject Details page. This page lists all of the properties of a subject along with their value and type. Functions are available to add/delete properties and edit their values.
• To add a property to the subject, select from the Add Property list and click on Add.

  Note: The list of available subject properties is managed via the CSA Management page. See CSA Management Essentials below.

• To delete a property use Del.
• To edit a property’s value, click on Edit. The Value column will open into an editable text form. When you are through entering or changing a value, use Save or Cancel to either save or discard your changes (respectively).

  Note: When changing the value of a property, make sure to enter it in the correct form, i.e. Y/N for boolean types, ISO dates in the form YYYY-MM-DD for date types.

• Dismiss this page when you are done.

Figure 4.5: PubMan CSA Subject Details Page

Figure 4.6: PubMan CSA Subject Details: Editing a Property

CSA Management Essentials.

Since it is possible to have multiple product lines in the CMS, and multiple Titles within those product lines, it is necessary to have a way of associating certain subject classifications with certain collections of documents. This is what the CSA Management page assists you with. It also has tools for creating and managing the properties you will give to your subjects.

Figure 4.7: PubMan CSA Management Detail

Collections.

• To create a Collection: In the Collections Select: list, select '<new collection>'. Enter the Name and Description of your Collection. Use the two lists to the right, Available Groups and Member Groups, to control which subject Groups are used by this Collection. When you are through click on Save Changes.
  • Use Delete Collection to remove a Collection.
  • You may edit the properties of an existing Collection by selecting it in the Select list, making changes, and clicking on Save Changes.

Groups.

• To create a Group: In the Groups Select: list, select '<new group>'. Enter the Name and Description of your Group. When you are through click on Save Changes.
• You may import Group information in XML using the Import Group from XML file and Export Group to XML File functions. Documentation of the XML format can be found here.

Properties.

• To create a new subject Property: In the Properties Select: list, select '<new property>'. Enter the Name, Type, and Description of your property. When you are through click on Save Changes.
  • Use Delete Property to remove a Collection.
  • You may edit the properties of an existing Property by selecting it in the Select list, making changes, and clicking on Save Changes.
• Property types are as follows:
  • Text. The property will be populated with text.
  • Date. The property will be populated with an ISO Date in the YYYY-MM-DD form.
  • Boolean. The property will be a yes or no (Y/N) setting.

Bulk Operations with Titles 

Manipulation of large numbers of Documents can be handled within a Title using Bulk Operations, which are available from a Title Document listing. A Bulk Operations link appears at the bottom of the Document listing

• Delete Documents from this Title performs a bulk deletion of a sequential range of documents. You are required to enter the first sortkey in the range, and then either the last sort key or a maximum count to define the end of the range. This function is available to administrative users only.

  Warning: Documents you delete in the fashion are not recoverable. You will be warned by PubMan™, and you've been warned here . . . so use with caution.

• Refresh metadata and link info for this Title. Changes are sometimes made to the routines PubMan performs when Documents are checked in (often referred to as “load routines”), usually to modify the way Document metadata and/or link information is recorded. When this is done, the changes do not affect Documents until they are run through the load routine again. Rather than have to go through a check out/check in cycle, this utility lets you choose a range of documents to process through the load routine and refresh the metadata stored for them.
• Copy document list from Title. This function copies the specified Document range from its source (the selected Title or Package chosen in the dropdown menu) to the current Title.
• Copy document list to Package set. This allows a user to break up a specified Document range into manageable Packages. The request form allows the user to enter a prefix that will be applied to each Package and to assign the maximum size for each Package.

Figure 4.8: The Titles Bulk Operations page

Bulk Operations with Packages 

There are also bulk operations for Packages, accessible from the Bulk Operations link on a Package Documents listing.

• Export Document list to a comma-delimited file does just what it says. The list can then be opened in a spreadsheet application of your choice, or edited manually in a text editor.
• Import Document list from a comma-delimited file accepts a comma-delimited file as input and creates a Package list from it. PubMan users often combine the above function with this one, using system functions (such as saving a search results set as a package) to initially create a package, exporting it, editing the list, then reimporting it to modify the Package list.

  Note: If you want the gory details of the format used for Document list imports and exports, export a package and open the file you receive in a text editor. Advanced users can use this as a guide for producing lists manually or programmatically.

• Remove documents will remove listings for the specified Documents from the current or selected Package. It does NOT delete the Documents.
• Refresh metadata and link info for this Package. See the description for this in Bulk Operations with Titles.
• Copy Document list from package. See the description for this in Bulk Operations with Titles.
• Copy Document list to package set. See the description for this in Bulk Operations with Titles.

Figure 4.9: The Packages Bulk Operations page

Workflow 

PubMan's workflow functions allow users to breakdown content preparation into Jobs and Tasks. Within PubMan, a Job is a component or stage of work such as an editing or review stage. A given Job may take one or more users to complete so Jobs are broken down into manageable pieces called Tasks. Each Task is given a description, (optionally) associated with a Package of documents, and assigned to a user. For example: Given a publication consisting of many documents, the Job of editing could be broken down into Tasks that several users are assigned. Each user would get a Package of certain documents to perform the same Task on. Each Task is given a due date and (optionally) a priority. It remains “open” until it has been completed and marked done. Tasks may have their descriptions changed, and may be reassigned, allowing a user to alter the Task and pass the work through to the next production stage on completion.

Selecting Jobs under Lists will bring you to the Jobs page:

The Jobs page has the following features and functions:

• A listing of all Jobs, sortable by column heading.
• Selecting a Job by its Name will move you to the Job Tasks page, which lists every Task associated with the Job and their properties:
  • Package: A Package of documents associated with the Task, if any.
  • Assignee: The user assigned the Task is assigned to.
  • Assigned: The date and time the Task was created.
  • Due: The due date for this Task.
  • Pri: Priority, an integer from 1-9.
  • Done: The date Task was completed, or a button to mark the Task as done.
• Details will display the Job details in an editable form: Job Name, Title, and Instructions. You may change any of these properties and Save Changes, Delete Job, or just Cancel. Create New Job opens a new job in the same editable form.
• You may edit the properties of a given task by clicking on its name to open the Task Details page. At the bottom of the Task list, the Create New Task link allows you to create a new Task. Both Edit and Create New Task use the same form that to allows you to view, create, or alter the properties of a task:
  • Job Filled in by the system when you create the Task.
  • Assigned to pick user name from pulldown.
  • Package (Optional) pick Package name from pulldown, if desired.
  • Priority assign an integer from 1-9.
  • Due Date Date Task is due to be completed.
  • Assigned on Filled in by the system when the Task is created.
  • Completed on Filled in by a assigned when Task has been marked complete.
  • Reviewed on Filled in by a supervisor when Task has been reviewed.
  • Instructions A description of the task.

Figure 4.10: PubMan Jobs Page

Figure 4.11: PubMan Job Tasks page

Figure 4.12: PubMan Task Details page

Any Task assignments you create will show up in the Tasks page of the assignee, who will be notified of the assignment via the Tasks link in the top navigation bar of PubMan. (The assignee will also receive an email notifying them of the assignment.) Selecting the Tasks link opens the User Task Listing page.

• Tasks may be sorted by clicking on any one of the column headings.
• Clicking on the Task listing will open a the Task Details page (see above).
• Clicking on the Done button marks a Task as complete and date stamps it. It will no longer appear in your Tasks page listing, unless Include Completed Tasks is selected, but will appear in the pages for assigning tasks, and in Workflow reports.

Figure 4.13: PubMan User Task Listing

Utilities 

The Utilities page (accessed via the Utilities link under Lists in the navigation menu) is an access point for both standard and client-specific utility applications such as reports. The standard reporting utilities are used for gathering information about content or workflow operations. Report results are delivered in one of two ways, depending on the Report and/or the user’s request: a spreadsheet or a Package. Having results delivered as Packages is handy when you’ve generated a report on a type of error (since you have to fix them), and spreadsheets results are used for things like workflow information. Where a choice between the two is logical and useful, it will be offered on the request form.

Figure 4.14: The Utilities page

Report utilities are customizable among different PubMan installations, and you may have additional options beyond the standard ones listed here:

• Broken Links Searches for link references (pointers) with no corresponding target. Builds either a list of such links or a package populated with the Documents which contain them.
• Document List Produces a spreadsheet file containing the sort keys and names of Documents in a Title or Package.
• Documents Changed Identifies the Documents in a Title or Package which were modified within a given date range. The report may be further restricted by user.
• Duplicate Targets Searches for duplicate link target identifiers (UIDs). Builds either a list of such IDs or a Package populated with the documents which contain them.
• New Documents Identifies Documents created within a specified date range. May be further restricted by user.
• Parse Errors Identifies Documents which have XML validation errors.
• PubPrep An external application that handles large data transfer and processing requests.
• Valid Links Builds a spreadsheet or an HTML page showing all of the valid links from or to a set of Documents, allowing quick checking of links for semantic validity.
• Workflow tasks Lists outstanding or completed tasks by user and/or date range.

All reports have forms for submitting your request, which should be fairly plain to the user. Contact support if you have questions.

Be aware that large report requests can have high system overhead, which can adversely affect performance and/or run time for the request. We recommend that requests involving more than 5000 Documents be run in smaller batches to avoid any performance loss.

Documentation for custom (client-specific) utility applications is outside of the scope of this manual, and is usually included with a client's documentation set. If you have any questions on how to find information on custom utilities, contact your system administrator.

5. Administrative Functions

Users with administrative level access to PubMan have different responsibilities and access to additional functions in the system. Administrative users will be responsible for managing user accounts, permissions, locks, and Titles.

Management of Users and Permissions 

Selecting Users from the navigation menu opens a User Accounts page listing all users, information about their accounts, and functions for creating and managing accounts. PubMan gives users a simple two-tier status—they are either administrative or not. Those that are made “Y” under their Administrative setting have access to the capabilities listed in this section of the User Guide. Those that are set to “N” will not see administrative functions they cannot use when they are logged in. Each user has an Active status of either “Y” (active) or “N” (inactive), allowing accounts to be created in advance, or made dormant for periods of inactivity. You can choose to view all users or just those that are active simply by toggling the Show Inactive Users check box to the upper right of the list. In addition, you can view all users at once on a single page by toggling the All On One Page checkbox.

Figure 5.1: The User Listing page

Permissions for users are assigned on a per Package or per Title basis. Package permissions are managed from the Packages page using Admin Packages (see note below, and the section in this guide on Packages). For each Title a user can be assigned permissions as follows: “N” (for None), “V” (for View), or “E” (for Edit) rights.

Figure 5.2: The User Permissions page

For each user on the User Accounts page, a Perms button provides access to a Permissions page where these settings are managed. The page contains a listing for each title, and a Perm column listing the current permissions setting. Permissions can be changed:

• via the active link in the Perm column
• by using the facility to copy permissions settings from another user

  Note: This makes it possible to use user account templates.

• by using the facility to set permissions for all titles in a group

The User Accounts page also has an Edit button for each user listing that lets you change the account properties. The Create New Account link opens a page for setting up new user accounts.

Locks 

In the normal process of checking in and checking out Documents or Packages, PubMan automatically locks and unlocks files as required. However, in the event of a system error, or human error in which someone locks files and then does not or cannot unlock them, users may access a list of files that are locked and unlock them by using the Locks page. Users with non-administrative access may release their own locks, and administrative users have the power to release any user’s locks.

Management of Titles 

On the Titles page, non-administrative users are limited to selecting a Title to see the Documents it contains. Administrative users are allowed to edit the properties of Titles and user permissions from this page, as well as create new Titles.

Figure 5.3: The Title Details page

Each title has the following properties, accessed on the Edit Title page via the Edit button:

• Title Tag, a unique Title identifier that will be used in content to assign membership to this title. (Req.)
• Full Name, the full name of the Title, which will be displayed in any listings. (Req.)
• Title Group, the Title Group the title belongs to.
• Content Type, distinguishing whether the content is XML or Binary (Req.)
• Uses Unicode, a Y/N flag determining whether the Title uses Unicode character encoding. This should always be set to 'Y' for XML Titles.
• XML Doctype, if the Title’s content type is XML, the name of the Document Type. (Req. if XML)
• XMAX® Path, the path to the XMetaL® ActiveX (XMAX) customization file to be used for QuickEdit/XMAX. Not required. If this field is empty the plain text Quick Edit will open when that function is requested by a user.
• XRef Group, a cross reference group used to classify Titles that may link to one another. In an Xref Group with only one member (thus a Title with no links to other Titles), IDs are only required to be unique within that Title. Xref Groups with multiple members require IDs across all Titles within that group to be unique.
• Status, a setting determining whether the Title is Active, Locked (temporarily inactive), or Finished (no further changes may be made). (Req.)
• Notes, an optional field for any administrative annotation that may be helpful.

The Edit Title page also has a Delete function available. Delete completely expunges a Title from the system. Use with the care you would give any such function.

From the Titles page, using the Create New Title link opens an Edit Title page with an empty set of properties (listed above). Populate the form and save when your are done. This creates an empty Title you may populate by either checking in Documents or copying in a list or lists of Documents from other Titles or Packages already in the CMS.

Configuring PubMan to recognize and handle new XML document types will require a support technician to create load and extraction routines for it.

Management of Document Templates 

The Templates page (under Lists) is used to manage templates for creating new documents. PubMan organizes the templates by assigning them to the title they are used for. Each template has a basic set of properties:

• Title: the title the template is used for.
• Name: the name which will appear in the menu the user selects the template from.
• File Path: the path on the server to the template file.
• Description: an optional field for any annotative notes about the template.

The Templates page lists all of the templates for a selected Title, and has the following features:

• The For title: drop down list lets you select a title to list templates for.
• The template listing shows the properties for each template, along with options for editing them (via the Edit button) or deleting selected templates (via Delete selected templates).
• A function for copying templates from another title is provided via Copy templates from:.
• A Create new template function.

Figure 5.4: The Templates Page

To create a new template:

• From the Templates page, select create new template.
• Fill in the form and select Save to save the new template, or Close to exit without saving.

Figure 5.5: The New Template Page

To edit an existing template, select the Edit button next to the template name in the templates list.

To delete templates, select them via the check box next to their listings, the click on Delete selected templates.

To copy template(s) from another Title, use the Copy templates from: dropdown list to select the title you wish to copy templates from, then click on Go.

For Operations Involving Large Amounts of Documents: PubPrep 

PubMan™ has an administrative tool named PubPrep for handling large data processing requests in an asynchronous fashion. You should use PubPrep for:

• Check out of entire titles or packages (anything > 1000 documents)
• Check in of large amounts of data (> 1000 documents)
• Automated preparation of data for check in to PubMan™
• Automated publishing processes of selected titles or packages to prepare the information for internal or public consumption

Full documentation for PubPrep can be found here

User Configurable PubMan Options 

There are several options in Pubman which change the functionality of certain operations and these can be set by a system's administrator: They are:

• Message functions can be enabled/disabled. They are enabled by default.
• Email notifications for Messages or Tasks can be enabled/disabled. They are enabled by default.
• Workflow functions can be enabled/disabled. They are enabled by default.
• Dropdown lists for titles may be sorted by their name or id.
• Document list column headings can be changed from the defaults.
• Document listing page length can be altered. The default is 20 Documents per page.
• File downloads from individual document locking functions can be enabled/disabled. They are enabled by default.
• Toolbars can be enabled on popup windows. They are disabled by default.
• Multiple subdomains can be used for system access
• Links to a user documentation set (in addition to this manual) may be configured.

XML Format for Import and Export of CSA Groups 

• <Scheme> is the root element of the XML structure used to describe CSA Groups.
• A <Scheme> consists of a <Name>, followed by a <Description>, which is then followed by <Concepts>.
  • <Name> is the name of the Group.
  • <Description> is the description of the Group.
  • <Concepts> is a parent for <Concept> elements, which in turn are a container for all of a subject's properties.
• Each <Concept> consists of a <Name>, <BroaderConcepts>, <RelatedConcepts>, <Properties>, and <DocumentPointers> in that order.
• <BroaderConcepts> is a sequence of any links to broader subjects, expressed using the <Link> element. The url attribute of the link element holds the unique id of a concept.
• <RelatedConcepts> is a sequence of any links to related subjects, expressed using the <Link> element.
• An XML schema for use in creating subject group descriptions is available here.
• <Properties> contains a sequence of <Property> elements used to describe a subject’s properties. Each <Property> element has two attributes: type, with possible values of 'Text', 'Date', or 'Boolean'; and name, which is populated with the name of the property.
• <DocumentPointers> contains a sequence of <Pointer> elements that link individual documents to the subject. Each <Pointer> has two attributes, title and url, which are populated with the Title id and unique identifier of the document respectively.

<?xml version="1.0" encoding="UTF-8"?>
<Scheme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://demo.dataformat.com/local/pm 
    http://www.dataformat.com/local/CSA.xsd">
    <Name>Documentation Group</Name>
    <Description/>
    <Concepts>
        <Concept url="1">
            <Name>Public Documentation</Name>
            <Properties>
                <Property type="Text" name="Description"/>
            </Properties>
        </Concept>
        <Concept url="4">
            <Name>User Guides</Name>
            <BroaderConcepts>
                <Link url="1"/>
            </BroaderConcepts>
            <DocumentPointers>
                <Pointer title="PMDocs:1.01" url="4221037"/>
                <Pointer title="PMDocs:1.01" url="4221047"/>
                <Pointer title="PMDocs:1.01" url="4221057"/>
            </DocumentPointers>
        </Concept>
        <Concept url="5">
            <Name>Internal Documentation</Name>
            <DocumentPointers>
                <Pointer title="PMDocsI:1.01" url="4221067"/>
                <Pointer title="PMDocsI:1.01" url="4221077"/>
                <Pointer title="PMDocsI:1.01" url="4221087"/>
            </DocumentPointers>
        </Concept>
        <Concept url="7">
            <Name>Public Developer Docs</Name>
            <BroaderConcepts>
                <Link url="1"/>
            </BroaderConcepts>
            <DocumentPointers>
                <Pointer title="PMDocs:1.01" url="4221097"/>
            </DocumentPointers>
        </Concept>
    </Concepts>
</Scheme>

6. Browser Settings for PubMan™

For Internet Explorer 7.x 

Before using PubMan™ make sure that the settings that follow have been configured in Internet Explorer (IE). To change these settings (in IE), select Tools->Internet Options, then select the Security tab.

First, select the Trusted Sites web content zone. Click on the Sites... button and on the resulting form add the web address (url) for your PubMan™ system to the list of trusted sites (i.e. http://mypubmandomain.dataformat.com). Deselect the option to Require server verification, then click OK.

Next, making sure that Trusted Sites is still selected as the web content zone, click on the Custom Level... button. Use the listings below to select the correct security options.

Under Downloads:

• Automatic prompting for file downloads: Enable
• File download: Enable
• Font download: Enable

Under Miscellaneous:

• Access data sources across domains: Enable
• Allow scripting of Internet Explorer Webbrowser control: Enable
• Allow script initiated windows without size or position constraints: Enable
• Launching programs and files in an IFRAME: Enable
• Use pop-up blocker: Disable

Under Scripting:

• Active scripting: Enable
• Allow programmatic access to clipboard: Enable
• Allow web sites to prompt for information using scripted windows: Enable

If in addition to PubMan™ you use the XMetaL ActiveX editor (XMAX), use the following settings under ActiveX controls and plug-ins:

• Run ActiveX controls and plugins: Enable

7. Glossary

Terms Used in Manual 

8. Troubleshooting

What to Do When You Save Changes You Didn't Want To 

At some time during the course of your work you may end up saving changes you did not wish to save. You might upload a file containing an incorrect version of a document, or one that you find mistakes in later, or have accidentally saved changes in Quick Edit you didn't intend to. However it happens, don't worry. PubMan stores every version and gives your administrator the option to restore prior versions. Contact your administrator with a description of the problem and let them know which version of the document to restore.

Dealing with Errors on Check In 

If for any reason there is a problem with content you are attempting to check in to PubMan, an error file will be returned to you and an error message will be displayed on the Check In page. Download the file—there will be comments within it that explain the errors (if somewhat cryptically). Here are the most frequent issues:

• Sortkey conflicts with another Document. You will have to alter the Document sortkey(s) so they do not conflict with existing Documents.
• Document not locked by you. Examine the Version information for the Document carefully before deciding how to resolve this. If you are absolutely positive the version you are trying to check in is the current and correct one, you can remedy the situation as follows: Lock the Document again but do not download the file you are sent. Check in the existing file. If you have ANY question about how to resolve this situation contact your administrator.
• You do not have permissions to modify this Document. This means just what it says. Contact your administrator.
• One or more required fields missing. Contact support with the issue and email them the file.

What to do if your QuickEdit/XMAX® Editing Session is Unintentionally Closed 

If for some reason your XMAX® editing session is interrupted—there is a page timeout, you accidentally close the browser window, etc.—it is possible to recover changes that you saved during the session. The document will still be locked, and the lock is associated with the temporary file you saved your changes to. All you have to do to recover them is go to the Locks page, locate the lock, and use the Check In button C/I to check the changes in.