Glossary in UPK 3.5

Dirk Manuel

October 2009

A Glossary in UPK effectively associates Web Pages to key terms. UPK will then turn any instance of that key term within a Topic (or other content object) to which that Glossary is assigned into a hyperlink to the associated Web Page. You could do this manually by creating Web Pages (as explained above) and then creating hyperlinks to these manually, but the advantage of using the Glossary functionality is that UPK will 'automatically' find each occurrence of the glossary term and create the hyperlink. I say 'automatically' in quotation marks, as UPK does not do this completely automatically. You have to tell it to go and create the hyperlinks, but once you tell it to do so, it will dutifully go off and find 'every' occurrence of all of the terms in the glossary and create the hyperlinks to the definition.

And I say 'every' in quotation marks, because UPK won't necessarily link every instance of the term. UPK allows you to choose (at the Library level) whether it turns literally every occurrence of the term found in a location into a hyperlink, or only the first occurrence. A location here is effectively a single Bubble or Web Page. One could well ask why UPK doesn't provide the option to create a Glossary link only for the first occurrence of the term in a Topic. The simple answer is that it does not necessarily know which occurrence is the first, because the Topic could include Alternative Paths. So UPK takes an over-cautious approach, and considers each block of information separately.

This option is specified in the Options panel (menu option Tools|Options), under the Content Defaults|Glossary section, as shown in the following screenshot:

Oracle User Productivity Kit 3.5

Creating a glossary

To create a Glossary in UPK, follow these steps:

  1. From the main Library screen, click on the folder within which you want to create the Glossary. You can create the Glossary in any folder, but it makes sense to have a single folder that contains the Glossary file itself, and all of the Web Pages used for the terms.
  2. Select menu option File|New|Glossary.

The Glossary Editor is opened in a new tab within the UPK Developer window, as shown in the following screenshot:

Oracle User Productivity Kit 3.5

To create glossary entries from within the Glossary, follow these steps:

  1. Enter the glossary term in the first free Glossary Term field.
  2. Click in the Definition Link field on the same line. An ellipsis (...) is displayed on the rightmost side of the field.
  3. Click on the ellipsis. The Edit Definition Link dialog box is displayed.
  4. Click on the Create New Web Page field.
  5. The Save As dialog box is displayed.
  6. Navigate to the directory in which you want to save the Glossary definition. Again, it makes sense to save these in the same folder as the Glossary itself.
  7. The Name field will default to the glossary term specified in the Glossary Term field. It is recommended that you keep this default, and use the definition term as the Web Page name. You could use any other name, if you wanted to (UPK does not use this name to locate the definition; it uses its own, internal identifier) but using the same name will allow you to easily locate the term Web Page if you need to.
  8. Click on the Save button. A new tab is opened for the Web Page.
  9. Enter the Glossary description into this page.
  10. The Web Page will use the default font and colors. You can override these defaults, if required.
  11. Close the Web Page by clicking on the x on the rightmost side of the open tab list. You are passed back to the Glossary Editor.
  12. Enter a suitable ToolTip text for the glossary entry in the Tooltip field. This text will be displayed when the user hovers the mouse over the hyperlinked glossary term.
  13. If only whole instances of the glossary term should be turned into hyperlinks (for example, if the term is Order then "Orders" and "Ordering" will not be hyperlinked), then select the Match Whole Word option. Otherwise, make sure that this option is not selected.
  14. If only text that matches the case of the term should be turned into hyperlinks (for example, if the term is Order then "order" will not be hyperlinked), then select the Match Case field. Otherwise, make sure that this option is not selected.
  15. Repeat Steps 1 to 14 for all additional terms that you want to add to the Glossary.

To create a glossary entry that uses an existing Web Page for the glossary term, follow these steps:

  1. Enter the glossary term in the first free Glossary Term field.
  2. Click in the Definition Link field on the same line. An ellipsis (...) is displayed on the rightmost side of the field.
  3. Click on the ellipsis. The Edit Definition Link dialog box is displayed.
  4. Click on the Create Link button. The Insert Hyperlink dialog box is displayed.
  5. Navigate to, and select, the Web Page that contains the glossary description.
  6. Click on OK. The Edit Definition Link dialog box is redisplayed.

    You can edit the Web Page directly from this dialog box, by clicking on the Edit Web Page icon.

  7. Click on OK. You are returned to the Glossary tabbed page.

Once you have defined all required Glossary entries, save and close the Glossary, by following the steps shown below:

  1. Click the Save button to save your changes to the Glossary. The Save As dialog box is displayed.
  2. Navigate to the directory in which you want to save the Glossary.
  3. Enter a suitable name for the Glossary in the Name field.
  4. Close the Glossary Editor by clicking on the x on the rightmost side of the open tab list.

An example of a partially-populated Glossary is shown in the next screenshot:

Oracle User Productivity Kit 3.5

You can see from the Definition Link column above that all of the Glossary definition files are stored in the same, single folder, called Glossary. This is the same folder that the Glossary object itself is stored in. Personally, I find it useful to keep all of the content objects for the Glossary in the same single folder. This is not strictly necessary, but it does keep things organized.

You will also note that the Tooltip is the same in every case. I tend to always use the tooltip Glossary so that the user knows that the hyperlink links to the Glossary, and not to another form of Web Page.

Assigning a Glossary to content objects

Creating a Glossary is only half the story. You need to manually assign the Glossary to each object that you want to use that Glossary (that is, for which you want the terms specified in the Glossary to be hyperlinked to the Glossary definitions).

Version Difference

In OnDemand Version 8.7 and earlier, a single Glossary was created for a Title, and was automatically applied to all content objects within that Title. In UPK 3.5, it is possible to have multiple Glossaries within a single Library, so it is necessary to specify which content objects should use which Glossary.

This assignment is done via the content object's Properties, as shown in the screenshot below.

Oracle User Productivity Kit 3.5

The Glossary property is available for Modules, Sections, Topics, and Web Pages. This means that you could potentially assign one Glossary to a Module, another Glossary to a Section within this Module, and a third Glossary to a Topic within that Section. Not that you're very likely to want to do this. But you could.

The further implication of the requirement to assign a Glossary to each content object individually is that you can define multiple Glossaries, and assign different Glossaries to different objects. I'd question the wisdom of assigning one glossary to a Module, and then an entirely different Glossary to a Topic within that Module, but I can certainly see the benefit of having multiple Glossaries available in a Library that contained (for example) simulations for multiple applications; you could create application-specific Glossaries (as you no doubt do at the moment) and then assign each Glossary to only the content objects for the relevant application.

The downside (for those of us who favor modularization and reuse) is that it is only possible to assign a single Glossary to any given object. So it is not possible to, say, create a company-wide Glossary and separate application-specific Glossaries, and then assign the company-wide Glossary and the relevant application-specific glossary to a single Topic. But more resourceful readers will have already worked out how to get around this limitation. Need a clue? Glossary entries are just Web Pages, and any given Web Page can be reused in multiple places. Need more help? A Web Page can be included in more than one Glossary. So you should first define Web Pages for all of your Glossary terms. You can then create multiple Glossaries (for example, one for each application), and include whichever terms' Web Pages you need to in each of the glossaries. If a term applies to two applications, then simply include the Web Page for that term in the Glossaries for both applications. Simple! Of course there is some slight duplication of effort as you need to create the entry in the actual Glossary content object twice (once in each glossary), but you are reusing the individual definitions, so it could be worse.

Unfortunately, unlike Templates, it is not possible to specify a default Glossary in your user defaults. This means that this assignment must be done separately for each content object. However, there are a couple of shortcuts that UPK provides which avoid the need to assign the Glossary to content objects one by one. First, if you select multiple content objects (Modules, Sections, Topics, or Web Pages) and display the Properties pane, then you can assign the Glossary to all of the selected objects in one fell swoop. Second, if you assign a Glossary to a Module, then any new Sections or Titles that you create within that Module – that is, from within the Outline Editor – will inherit this Glossary assignment. However, it is important to note that this will only apply to new content objects. If you assign a Glossary to an outline element and then insert pre-existing content objects into this outline element, then these pre-existing content objects will not inherit the Glossary assignment.

Regenerating the Glossary links

Glossary links are not created (or updated) automatically. You need to tell UPK to go and search through your content objects and turn any instances of the Glossary terms into links to the Glossary definitions. This is good in that you can at least have control over when it does this, but bad in that it is easy to forget to do so.

Updating Glossary links after updating the Glossary itself

When you close (not save) an existing Glossary, having updated it (for example, to add or remove terms), UPK will prompt you to re-generate the Glossary links by displaying the following message:

Oracle User Productivity Kit 3.5

Click Yes. UPK will update all of the content objects that the changed Glossary has been assigned to. It will hyperlink all occurrences of the glossary terms with hyperlinks to the associated definition Web Pages. Furthermore, if you have removed any Glossary terms from the Glossary, then UPK will also remove any hyperlinks for these terms.

Version Difference

In OnDemand Version 8.x and earlier, if you removed terms from the Glossary then any hyperlinks to these terms would not automatically be removed when you re-generated the Glossary. This is a huge improvement in OnDemand 9.x / UPK 3.x.

Once the Glossary has been updated, the following message is displayed:

Oracle User Productivity Kit 3.5

Note the text "any documents that were changed were automatically checked out to you". It is important to note that if you are working in a multi-developer environment then any content objects that have now been hyperlinked to your new glossary entries will have been checked out. You will need to check all of these in again (typically, when you check in the updated glossary). You should, therefore, click on the View activity log link and make a note of the changed documents. Alternatively, you can choose to Check in all when you check in the glossary, although you should be warned that this will check in all content objects that you have checked out which may be more than just those objects changed by the Glossary link update.

An example of the Activity Log is shown in the following screenshot.

Oracle User Productivity Kit 3.5

Note that the Activity Log lists all of the content objects that have been examined – even if they have not been updated. Also note the message "Document has been checked out to update glossary links". You will need to check back in all of these content objects.

It is also important to note that if UPK attempted to update the Glossary links in a content object that is currently checked out to another user, then it will not be able to. In this case, you will see a warning message similar to the one shown below when the update completes:

Oracle User Productivity Kit 3.5

You can identify these documents in the Activity Log, as shown in the following screenshot:

Oracle User Productivity Kit 3.5

You should make a note of these unprocessed content objects. You will need to run the Glossary update again once they are checked in. Bear in mind that UPK will have identified the content object based on the most recently checked-in version of the object. The developer could well have removed the text that would have been hyperlinked to the Glossary in their edits. Conversely, it is possible that UPK did not identify a content object for Glossary updates based on the most recent version, but a developer had the object checked out and added the Glossary terms (that are eligible for hyperlinking) whilst they had the object checked out. For these reasons, you should run the Glossary update periodically, and definitely run it immediately before publishing your content (when all of the content objects should be checked in, anyway).

Manually regenerating the Glossary links

You can regenerate Glossary links whenever you want to, by following these steps:

  1. Select the objects for which you want to update Glossary links, in the Library. You can either select one or more specific objects, or you can select a folder, in which case all of the objects within that folder (and any subfolders) will be updated.
  2. Select menu option Edit|Update Glossary Links.

It is advisable to always regenerate the Glossary links immediately prior to publishing your content. It certainly does no harm to regenerate the Glossary links at any other time, but bear in mind that it could take a while if you have a lot of content objects and/or a lot of glossary terms. Also, bear in mind that UPK will check out every object that it updates the Glossary links in, so you will need to manually check all of these back in again which can also take time. This may also be inconvenient if you have developers working on the content objects (or are working on the content objects yourself) at the time that you want to regenerate the Glossary links.

Generating a stand-alone Glossary

After seeing the usefulness of a Glossary, you're no doubt wondering if it is possible to either include a complete Glossary in an outline, or publish a Glossary to a stand-alone document that you could (for example) hand out during training. Unfortunately, UPK does not provide this capability (although it crops up reasonably often on the Feature Request forum, so there is a distant possibility that UPK may add this functionality in a future release). However, with a bit of effort there is an acceptable workaround.

This workaround relies on the fact that a Training Guide will include a Glossary table that contains Glossary entries (term/definition) for each Glossary term hyperlinked in the course (or other selected outline element). So to generate such a table that includes all Glossary entries, you simply need to publish a Training Guide for an outline element that contains all of the Glossary terms. How to create and publish an outline element specifically for this purpose is explained below:

To create a Word-format, complete Glossary, and carry out the steps described below:

  1. Open your Glossary in the Library.
  2. In the Glossary Editor, click on the first Glossary term, to select it.
  3. Scroll down to the bottom of the Glossary, and Shift-click on the last Glossary term, to select the full range of Glossary entries in the Glossary. Your selection should look as shown in the following screenshot:

    Oracle User Productivity Kit 3.5

  4. Copy (Ctrl+C) this information to the clipboard.
  5. Close the Glossary Editor.
  6. Create a new Web Page and open it for editing.
  7. In the Web Page Editor, paste (Ctrl+V) the contents of the clipboard into the Web Page. This will be pasted as pure text, which will include the full file path of the Web Page, the Tooltip, and so on. But most importantly, it includes every glossary term in your Glossary. Don't worry about editing or formatting this Web Page; we will not use it in this form. Your Web Page will look similar to the example in the following screenshot:

    Oracle User Productivity Kit 3.5

  8. Use the Properties pane to assign your Glossary to this new Web Page. This is very important; the glossary links will not be updated if you don't assign the Glossary to the Web Page.
  9. Save and close your new Web Page.
  10. Back in the Library, click on your new Web Page, and then select menu option Edit|Update Glossary Links. This will turn all of the Glossary terms in the Web Page into hyperlinks to the associated Glossary entries.
  11. Create a new outline element (Module or Section) and attach this new Web Page to this element as the Concept.
  12. Publish this outline element as a Training Guide.

Once the publishing process is complete, open the generated Training Guide. At the bottom, you will find a section labeled Glossary that contains a table with all of your glossary terms and definitions in it. You can then reformat this, or extract it and copy it to somewhere else, or do whatever else you want with it.

Note that this is a one-time (one-way) activity. Any new terms that you add to the Glossary will not automatically be included in your dummy Glossary outline element. However, assuming that you just want to generate a quick and simple Word-based Glossary, for example for distributing during your initial training, then this is an adequate solution in the absence of any official functionality from UPK.


Although recording a simulation is just a matter of clicking the Record button, running through the task in the system, and you're done, producing quality training material is not really this simple. Yes, the simulation may work (if you're lucky), but it won't be of a particularly high quality. Producing high-quality training material in UPK requires a lot more work.

Providing an on-line Glossary can improve the quality of a Topic.

This thing is the bell and whistle that improve the trainee's experience. Because it is an 'add-on' to the basic recording, some developers may choose not to use them (or find that their project management has not allocated them enough time to add them). However, taking the time to add this level of features will greatly improve the overall usability of your exercises, and you will certainly see an increase in trainee satisfaction (assuming that you take post-training feedback—which you should).


If you have read this article you may be interested to view :

You've been reading an excerpt of:

Oracle User Productivity Kit 3.5

Explore Title