6Help Content Management

This chapter contains the following:

Managing Help Content: Overview

You can add and edit help files in Applications Help and help windows, as well as help text that appears on UI elements. You can also tailor the pages in the Getting Started work area.

Note: To allow help file and Getting Started changes, you or your implementor must enable the Help Content Management feature in your offering.

Help Files

A help file, such as an FAQ or example, provides information about a specific topic. You can find help files in:

  • Help windows: Which can contain informational text as well as links to help files. Click a help icon next to, for example, a page or section title to open the help window and find information about that page or section.

  • Applications Help: The help site which contains all help files, including help files found in help windows. To open Applications Help at any time, click your user image or name in the global header and select Applications Help.

You have many options to manage help files, including:

  • Creating help files with your own content and adding them to help windows

  • Editing the content in predefined help files

Getting Started Pages

The Getting Started work area contains a set of pages that provides information for new users. To open this work area, select Getting Started from the Navigator. You can modify predefined pages and create pages with your own content.

Embedded Help

Help text might appear when you hover over or click certain UI elements on the page. For example, hint text can appear when you put your cursor in a specific field. The help text you see on the page is called embedded help. To manage embedded help, you can, for example:

  • Edit the help text that appears for a specific check box.

  • Add help text that appears when users hover over a specific tab.

Users with the Manage Help Content (ATK_CUSTOMIZE_HELP_TOPICS_PRIV) privilege can create and edit:

  • Help in Applications Help and help windows

  • Pages in the Getting Started work area

This privilege is assigned by default to the administrators for product families. Your security administrator can define which users have job roles with this privilege.

Help Files Management

If you have the appropriate roles, then you can add and edit help files in Applications Help and help windows (which users open using help icons on the pages they work in). You can also determine which help files appear in which help windows, and which product family page a file belongs to in Applications Help.

What you can do to a help file depends on whether it's added or predefined.

  • Added:

    • Create, duplicate, edit, and delete

    • Set status (Active or Inactive)

  • Predefined:

    • Duplicate

    • Edit (which is really creating a copy of the predefined file that you can modify)

    • Set status

Navigation

This table describes where to go to manage help.

Help Management Task Navigation

Create or edit help for a specific help window.

Click the Manage Help Content link in the help window.

Edit any help file, including glossary terms.

Open the file in Applications Help and click the Edit link.

Perform any help file management task, including managing a set of help, such as all help for a product.

Go to Applications Help and click your user image or name in the global header to select Manage Help Content.

Make a copy of all added help for testing, migration, or other purposes.

Create a configuration package then use the export and import in the Setup and Maintenance work area. The configuration package must include either:

  • The Application Extensions functional area

  • A source implementation project that contains the Define Help Configuration task list, with the following objects selected to export:

    • Help Configuration

    • Help Topic

You have many options to determine the content of a help file, for example by uploading a local file, specifying a URL, or typing in the text. When you create help files, you first select a value for the Source list, to indicate how to provide your content.

Desktop File

Upload a file of any type from your computer.

Oracle User Productivity Kit

Identify the Oracle User Productivity topic to use as help.

Text

Use a rich text editor to enter the content of the help file.

URL

Enter the full URL to a website or a file of any type.

Video URL

For a video to play in the help windows assigned to the help file, enter the full URL to the video on YouTube or elsewhere.

Applications Help has many types of help content: examples, FAQs, glossary terms, help topics, PDF guides, and videos.

Example

Examples can provide:

  • Real use cases to illustrate how and when to do something

  • Scenarios to explain abstract concepts

Worked examples show exactly what you do to achieve a specific result. They emphasize decisions that you make and values that you enter.

FAQ

FAQs, or frequently asked questions, provide brief answers to questions that you might have about a task or page. For example, they can explain:

  • What a term means

  • Why something happened

  • How you can perform an action

  • What happens if you perform the action

Glossary Term

Glossary terms provide definitions for words or phrases used in help content. In a help file, terms that have glossary definitions are presented as links. When you see terms underlined with dots, you can hover over the term to see its definition. To see the whole glossary, select Glossary from the Navigator menu in Applications Help.

Help Topic

Help topics can:

  • Explain key concepts

  • Tell you the steps to follow to perform tasks

  • Help you make decisions by explaining points to consider or describing the options you have

  • Show you how application components work together

  • Provide reference, overview, and other information

PDF Guide

PDF guides provide information in a book format. The guides in Applications Help contain content that you usually can't find in other help types.

Note: Most of the examples, FAQs, and help topics in Applications Help are also in guides. To see these guides, select Documentation Library from the Navigator menu in Applications Help.

Video

Videos, or tutorials, show you how to complete a short task or part of a task. Videos can also give you an overview of complex dashboards and work areas.

The Page or Section value represents where users can click a help icon to open a help window that can contain links to help files. Use this value on the Manage Help Content page in Applications Help to:

  • Search for help that appears in a specific help window.

  • Add help files to the help window.

Where Help Windows Are Found

In most cases, the page or section value corresponds to a page or section header that has a help window. Help windows are also available:

  • On specific tabs, dialog boxes (windows), panel tabs, or dashboard regions

  • In the Setup and Maintenance work area, for example within the table of tasks on the Setup page

  • In the Offerings work area, for example within the table on the Edit Features page

  • In the Learn More column in the New Features work area

How to Read the Values

The page or section value reflects the logical navigation to the help window. For example, Process Details window, Output tab doesn't mean that the help window is in two different places. It's in the Output tab within the Process Details dialog box.

For objects in the Setup and Maintenance, Offerings, and New Features work areas, the page or section value reflects the object that the help window is for. These values end with offering, functional area, feature, task list, or task, for example, Set Help Options task.

When the Same Help Window Is On Multiple Pages

In some cases, a page or section value does represent a single help window that appears on multiple pages. If the value is:

  • For example Create and Edit Message pages, then the same help window is on both the Create Message and Edit Message pages.

  • Just a region name without a page or window name, then the same help window is in a section or dashboard region that appears on multiple pages.

Managing Help in Help Windows

Video

Watch video

Watch: This video tutorial shows you how to add and edit help in help windows. The content of this video is also covered in text topics.

When users click help icons on a page, they open help windows that provide information on how to use the page or part of the page. Help windows have informational text, links to help files, or both. Use the Manage Help Content dialog box to edit those help files, create new files to appear in the help window, or change the order of links in the window. To restrict access to any of those help files, use the Manage Help Content page in Applications Help to assign a help security group to the help file.

Tip: You can also use:
  • The User Interface Text tool to edit the informational text that appears in a help window

  • Page Composer to hide the More Help link at the bottom of help windows

Opening the Manage Help Content Dialog Box

Use the Manage Help Content dialog box to create and edit help files, or to reorder links, for a help window:

  1. Click the help icon to open the help window. If you don't see any help icons, click your user image or name in the global header and select Show Help Icons. To display help icons by default for all users when they sign in, use the Set Help Options task in the Setup and Maintenance work area.

  2. Click Manage Help Content.

Creating Help Files

To create a help file that appears in the help window (and also Applications Help):

  1. Open the Manage Help Content dialog box for the help window.

  2. Click Create.

  3. Select a source and, for any source other than Text, enter information that points to the content of the help file.

  4. Select the help type, which corresponds to the Help Type filter in Applications Help.

  5. Enter the title, which is the text of the link that appears in the help window.

  6. Enter keywords to help users find your file in Applications Help.

  7. Enter a description for your file, which users can see in the help window or in Applications Help search results before they open the entire file.

  8. If the source for your file is Text, enter the help content in the rich text editor.

  9. Optionally select a language, country, or role, which correspond to filters in Applications Help.

  10. Save your work.

  11. To verify your work, click the title of your new help file in the help window.

  12. Click the More link at the end of the description to see the entire help content. If your new file is an FAQ, you can then click the Related FAQs link to see the FAQ in Applications Help along with other, related FAQs.

Editing Help Files

To edit help files in the help window:

  1. Open the Manage Help Content dialog box for the help window.

  2. Click the title of the help file.

    Note: If you're updating a predefined file, then you see the Create Help dialog box because you're really creating a copy of the predefined file that you can then edit.
  3. Change the title or content of the help file as needed, as well as the status.

    Setting the status to Inactive hides the file in the help window and in Applications Help.

  4. Open the More Details section if you need to update more aspects of the help file, including fields that correspond to the following filters in Applications Help:

    • Help Type

    • Role

    • Language

    • Country

  5. Save your work.

  6. To verify your work, reopen the help window.

  7. Click the title of the updated help file.

  8. Click the More link at the end of the description to see your changes in the entire help file.

Reverting to Predefined Help Files

When you edit a predefined help file, you're actually creating a new file and inactivating the predefined file. To discard your changes and revert back to the predefined file:

  1. Open the Manage Help Content dialog box for the help window.

  2. Click the title of new help file that was created when you edited a predefined file.

  3. In the Edit Help dialog box, click Delete.

  4. Reopen the Manage Help Content dialog box for the help window.

  5. Click the title of the predefined help file, which is appended with (Inactive).

  6. Select Active as the status.

  7. Save your work.

Adding Links to Help Windows

To add links in the help window to any help file that was already created:

  1. In Applications Help, click your user name in the global header and select Manage Help Content.

  2. In the search, select the page or section that corresponds to the help window.

  3. Click Search.

  4. In the search results toolbar, click Select and Add to Help Location.

  5. Search for the help file that was already created, select it, and click Apply.

  6. Repeat the previous step for all the help files you want to add.

  7. Click Done.

To determine which help windows your help file appears in, assign the appropriate help locations to the file. You also use help locations to define where help files appear in the Task and Product filters in Applications Help, as well as which product family tabs the files belong to. Help locations include:

  • Task hierarchy for the Task filter and product family tabs

  • Product hierarchy for the Product filter and product family tabs

  • Page or section values for help windows

Help locations are available only on the Manage Help Content page in Applications Help, not the Manage Help Content dialog box from help windows. When you create help from the help window, the help files are automatically assigned to the help window and task hierarchies associated with the window.

Determining Where Help Appears in the Task Filter, Product Filter, and Product Family Tabs

Enter at least one hierarchy, as many as you need:

  1. In Applications Help, click your user name in the global header and select Manage Help Content.

  2. Find the help file to edit or duplicate, or click Create.

  3. Enter or update the general information for the help file.

  4. In the Help Location section, add a row if there isn't already a blank one, or edit an existing row.

  5. Select Task or Product for the hierarchy type.

  6. Select nodes for as many levels of the hierarchy as you need, starting with level 1. If the Task hierarchy nodes you're assigning are at level 4 or lower, then click the Details icon to assign nodes.

  7. Add more rows as needed.

  8. Save your work.

Selecting Help Windows

Every page or section value is associated with a specific node in the Task hierarchy. When users click More Help from a help window, they get all the help files that are assigned to the same Task node as the page or section value.

To determine the help windows that a help file appears in:

  1. Enter the Task hierarchy that's associated with the help window, as described in the previous procedure, to narrow down the available page or section values.

    Note: For any help window for specific objects in the Setup and Maintenance, Offerings, and New Features work areas, select this hierarchy:
    • Hierarchy: Task

    • Level 1: Functional Setup

    Such objects include offerings, functional areas, features, task lists, and tasks.

  2. Select the page or section in the same row.

If you know the exact page or section you want, then you can select the value without entering a Task hierarchy. The associated hierarchy automatically fills in the rest of the row.

In Applications Help, users can use the springboard or filmstrip to open landing pages for specified product families. Every product family page has a Getting Started panel, which contains guides and videos to help new users. Users can also find help topics for new users in specific roles. You can add your own help to the Getting Started panel for any product family.

Adding Help to the Panel for a Product Family

Follow these steps:

  1. Click your user name in the global header in Applications Help, and select Manage Help Content.

  2. Create or edit the help file you want to add to the Getting Started panel.

  3. In the General Information section of the Create Help or Edit Help page, click the Getting started check box.

  4. Make sure that the help file has either or both of the following:

    • Help type of PDF guide or Video

    • One or more roles assigned

  5. In the Help Location section, enter at least one row with Product in the Hierarchy column.

  6. In the Level 1 column, select the product family for which you want to add your help file to the Getting Started panel. Optionally select a product in the Level 2 column.

  7. Save your work.

When you create or edit help, follow best practices when you include links to help files or other content. If you're duplicating a predefined help file, then you may see existing links. The types of links that you can work with include:

  • Related help links

  • Standard hypertext links

  • Links to documentation library content

  • Glossary term links

For all link types, except the standard hypertext links, you must create or edit help with a Text or Desktop File source type. For standard hypertext links, the source type can also be URL.

Related Help Links

Related help is the section at the end of help files that contains links to other help files. The syntax for related help contains a comma-separated list of title IDs that represent help files, for example:

OfaRelatedTopics(CREATE_AUTOMATIC_CRITERIA_S_0000, JOURNAL_ENTRIES_HOW_THEY_RE_RECORDE_0000)

In this example, the help file has two links to related help.

  • To remove all related help, delete this code.

  • To remove individual links, delete only title IDs (for example, CREATE_AUTOMATIC_POSTING_CRITERIA_S_0000).

  • To replace existing links or add new links, retain the code syntax and enter the appropriate title IDs. To find title IDs, search for the help files on the Manage Help Content page. Show the Title ID column in the search results if the column is hidden.

Standard Hypertext Links

You can create standard hypertext links to any file or Web site as long as you make sure that the links are valid and stable. These links can appear anywhere in the body of your help file as long as they come before any related help links.

If you're working on a help file with the Text source type:

  1. In the Help Content section of the Create or Edit Help page, highlight what you want to use as link text.

  2. Click the Add Link icon.

  3. Enter the full URL, for example http://www.oracle.com.

Tip: To find the URL for a help file that you want to link to, open that help file in Applications Help, and click the Bookmark link.

Links to Documentation Library Content

The syntax for links to HTML files in documentation libraries is:

<span class="HP_topic-link_bridgeDocument-linkToSTDoc_"><?ofa linkToSTDoc(WCSUG4636) ?><span class="HP_topic-linktext_">Understanding Tags</span><?ofa endLink ?></span>.

In this example, WCSUG4636 is the anchor ID and Understanding Tags is the link text. You can:

  • Change the link by replacing the existing anchor ID, editing the link text, or both.

  • Remove the link by deleting all the code for it.

  • Create links to documentation library content by following the same syntax. These links can appear anywhere in the body of your help file as long as they come before any related help links.

Note: To ensure that you're linking to a supported documentation library, enter anchor IDs only from documentation libraries that are linked from predefined help.

Glossary Term Links

Glossary term links provide definitions in a note box when users hover over the term in help files. The syntax for glossary term links is:

OfaGlossaryTerm("accounting period", ACCOUNTING_PERIOD_0001)

In this example, accounting period is the link text, or glossary term, and ACCOUNTING_PERIOD_001 is the identifier, or title ID.

  • To remove the link but retain the text, delete all the code except the term itself.

  • To add glossary term links, you must follow the link syntax and use the correct title ID for the glossary term. To find title IDs, search for the glossary terms on the Manage Help Content page. Show the Title ID column in the search results if the column is hidden.

If your help file has the Desktop File source type, then make sure before uploading that the quotes around glossary terms are actual quotation marks in raw HTML, not &QUOT. Otherwise, quotation marks will appear when users view the help file.

This example demonstrates how to modify a PDF guide that came with Applications Help. This guide is currently not available from any help window.

The following table summarizes key decisions for this scenario.

Decisions to Consider In This Example

What changes do you need to make to the guide?

Change the title of the guide and hide all the content that's not about a particular subject

Should the modified guide appear in any help window?

Yes, the help window for the Manage Administrator Profile Values page

Which products and tasks should the modified guide be assigned to?

Same as the original guide, plus the task associated with the help window

Do you want to limit access to the modified guide?

No, same as the original guide

Do you want to tag the modified guide with a role for the Role filter?

Yes, the Application Administrator or Implementor role

For this scenario:

  1. Edit a copy of the original PDF guide.

  2. Edit the help file to replace the original PDF guide with your modified guide.

Copying and Editing the PDF Guide

  1. Open the original PDF guide in Applications Help and save a copy to your desktop. Leave the help file for the guide open.

  2. Using a PDF editor application, change the title of the guide wherever it appears. Delete the content you want to hide from users.

Replacing the Original PDF Guide

  1. In the help file that you still have open for the original PDF guide, click the Edit link. You automatically create a copy of the predefined help file that you can edit.

  2. On the Create Help page, use the default values except where indicated.

  3. Update the title to the name that you want to display to users.

  4. In the File Name field, browse for and select your modified guide.

  5. Delete any keywords or parts of the description relevant to the content you removed from the PDF guide.

  6. From the Roles list, select Application Administrator or Implementor.

  7. Add a row in the Help Location table.

  8. Click the icon in the Details column for the new row, and complete the fields, as shown in this table.

    Field Value

    Hierarchy

    Task

    Level 1

    Functional Setup

    Level 2

    Perform Functional Setup

    Level 3

    Set Application Options

    Level 4

    Define Profiles

  9. Click OK.

  10. Select Manage Profile Option Values page in the Page or Section column.

  11. Click Save and Close. The help file for the original PDF guide is automatically set to inactive.

This example demonstrates how to add an Oracle User Productivity Kit topic as a video help file in Applications Help.

Note: Your topic must be made with User Productivity Kit 3.6.1 or later to be added as help.

The following table summarizes key decisions for this scenario.

Decisions to Consider In This Example

What User Productivity Kit content do you want to add to help?

One topic from a module with five topics

Should the topic appear in any help window?

Yes, the help window for the Overview page in the Scheduled Processes work area

For this scenario:

  1. Generate a report of User Productivity Kit document IDs, to identify the User Productivity Kit topic when you create your help file.

  2. Publish the module as a player package.

  3. Create a help file for the User Productivity Kit topic.

Generating a User Productivity Kit Document ID Report

  1. In the User Productivity Kit Developer, select Details View.

  2. Right-click any column header, for example Name, and select Column Chooser.

  3. In the Column Chooser dialog box, move the Document ID column header after the Name column.

  4. Close the Column Chooser dialog box.

  5. From the File menu, select to print, and save the output as a Microsoft Excel file to your desktop.

Publishing the Module as a Player Package

  1. From the Developer, make sure that the topic that you want to add as a help file has the See It play mode. The topic can also have other modes, but only the See It mode is included in your help file.

  2. Publish the module, specifying any location for the output and selecting to publish the selection only.

  3. In the Formats section of the Publish Content window, select the Player check box in the Deployment check box group.

  4. In the Player section, select the Include HTML Web Site check box. Your help file includes a text-only version of the User Productivity Kit topic.

  5. Finish the publishing process, after optionally setting other options.

  6. Go to where you specified the output to be generated.

  7. In the Publishing Content folder, copy the PlayerPackage folder and add it to the Web server where you store User Productivity Kit content.

Creating a Help File for the Topic

  1. Open the Scheduled Processes work area.

  2. Open the help window for the Overview page, and click Manage Help Content.

  3. Click Create.

  4. In the Create Help dialog box, complete the fields as shown in this table.

    Field Value

    Source

    Oracle User Productivity Kit

    File Location

    The full URL of the player package folder on the Web server, for example, http://<your domain>.com/MyContent/PlayerPackage.

    Document ID

    The document ID of the User Productivity Kit topic to add to the help window on the Scheduled Processes Overview page. Copy and paste this ID from the Microsoft Excel file that you generated earlier.

    Help Type

    Video

    Topic Title

    The name of the User Productivity Kit topic.

    Keywords

    Terms relevant to the topic.

    Description

    Summary of the topic.

  5. Click Save and Close.

You can edit the glossary terms in the Applications Help glossary. These are the same terms that users might find as links in help topics. The links provide definitions when users hover over the terms.

Procedure

Follow these steps:

  1. In the global header of Applications Help, select Glossary from the Navigator.

  2. Find the glossary term.

  3. Click Edit.

  4. Update the topic title (the term) or definition as needed.

  5. Optionally change the assigned hierarchies.

    • The last node of each hierarchy appears after the term's definition in the glossary.

    • Glossary terms don't appear in the Task or Product filter.

  6. Save your work.

Predefined Glossary Terms

When you edit a predefined glossary term:

  • You're actually creating a copy, and the original term becomes inactive.

  • The glossary in Applications Help shows your copied version.

  • In help files, existing links to the glossary term automatically point to your version.

Note: If you later inactivate your glossary term, make sure to activate the original term so that the links still work.

FAQs for Help Files Management

You're actually creating a new help file based on the predefined file. The new version replaces the original, which becomes inactive and hidden from users. You can display both versions by reactivating the original file.

Create a help file using the URL to the YouTube video.

  1. Find the video in YouTube.

  2. Click the Share button.

  3. Click the Embed button.

  4. Copy the URL within the embed code, for example http://www.youtube.com/embed/<unique ID>.

  5. Open the Create Help page from a help window or from the help site.

  6. Select URL as the source, or Video URL if you want the video to play within help windows.

  7. Paste your copied URL in the URL field.

    Tip: If you selected Video URL, change your pasted URL to start with https so that users don't need to adjust browser settings to play the video in the help window.
  8. Enter other information, and click Save and Close.

You must create or edit help from the Manage Help Content page.

  1. In Applications Help, click your user name in the global header and select Manage Help Content.

  2. As you create or edit a help file, select a help security group, which represents a set of roles that have access to the help.

    The predefined groups are:

    • Unsecured: Anyone can view the help.

    • Secured: All internal employees and contingent workers have access (unless this group was edited).

    If you don't see the Security Group field, then you or an administrator can enable this feature in the Offerings work area.

  3. Save your work.

When users filter or browse for help files by role in Applications Help, they get the help files tagged with the role.

The help security group hides the help file completely from users who don't have the roles defined in the group.

Why can't users find my help files in their search results?

If you created or edited those help files recently, they might not be indexed yet for the search in Applications Help. The indexing process runs on a defined schedule. Users can still find your help files by browsing, for example using the Task or Product filter.

Nothing happens to the help files you create or edit. Upgrades affect only predefined help files, active or inactive.

Take a look at any inactive predefined file that's updated to see if you want to:

  • Activate the updated version.

  • Make similar edits to your version of that file, if any.

Getting Started Pages Management

Overview

The Getting Started work area provides pages of information to introduce new users to the application. If you have multiple cloud services, you get a separate set of pages for each service. You can edit the predefined pages or add your own, so that users get content specific to your organization.

Access

Open the Getting Started work area, and, if you have multiple sets of pages, select the set to modify. You then see the Edit Getting Started link if you have the appropriate roles.

Key Tasks

You can:

  • Create and edit pages using a rich text or HTML source code editor

  • Reorder the pages

  • Activate or inactivate any page

    Tip: To hide the link to a set of Getting Started pages, inactivate all pages within that set. Users with access to edit Getting Started pages can still see the link, but everyone else can't.

    If you inactivate all sets except one, then users land on the first page of the active set when they open the Getting Started work area.

  • Delete added pages (not predefined ones)

How can I add a YouTube video to a Getting Started page?

Create or edit a page in the Getting Started work area, and include a piece of code from YouTube.

  1. Find the video in YouTube.

  2. Click the Share button.

  3. Click the Embed button.

  4. Copy everything in the text box.

  5. Back in the application, open the Getting Started work area.

  6. If you have multiple sets of Getting Started pages, select the set you want to add the video to.

  7. Click the Edit Getting Started link.

  8. Open an existing Getting Started page or create a new one.

  9. Click Source Code Editing Mode in the toolbar.

  10. Paste in the code you copied from YouTube.

  11. Click Save and Close.

Embedded Help Management

Managing Help That Appears on the Page: Overview

You can create, edit, or delete help that you see on the page, for example hints for buttons or text in help windows. There are different types of such embedded help. Embedded help doesn't include help that you open using links in help windows, or help that you find in Applications Help.

Creating, Editing, or Deleting Embedded Help