10Define Help Configuration

This chapter contains the following:

Applications Help and help windows work without you having to set anything up. You can do the optional setup, mainly if you want to create and edit help. Enable the help features you want, perform tasks in the Application Extensions functional area, and create and edit help content.

Help Features

In the Offerings work area, enable help features at the offering level. The features determine:

  • What's available in Applications Help

  • What you can configure to set up help

The first feature for help is Local Installation of Help, and you must leave it selected. Other features are:

  • Access to Internet-Based Help Features

  • Help Content Management

  • Security for Added Help

Help Configuration Tasks

In the Setup and Maintenance work area, use these tasks in the Application Extensions functional area to set up help for all users:

  • Set Help Options:

    • Determine if certain aspects of Applications Help are available to users.

    • Control how aspects of Applications Help work.

    • Determine if icons for help windows are shown by default on the pages where they're available.

  • Assign Help Text Administration Duty: Contact your security administrator to determine who can create and edit help.

  • Manage Help Security Groups: Set up security to limit access to certain help files.

Help Content

After you set up help, you can review the predefined help and see if you want to add or edit any content. You can also modify help text that appears on the page, for example hints.

Set Help Options

Showing Help Icons by Default

Video

Watch video

Watch: This tutorial shows you how to set help options so that help icons are shown by default for all users.

Procedure

In the Setup and Maintenance work area, use the following:

  • Functional Area: Application Extensions

  • Task: Set Help Options

On the Set Help Options page, select the Show help icons by default check box in the Show Help section. You just need to do this setup for one offering, and the setting applies to all users.

Every time users sign in, they can see help icons wherever available on the pages they use. To hide the icons, users can still click their user image or name in the global header and select Hide Help Icons, as well as select Show Help Icons to display the icons again.

You can determine the websites that users can access from Applications Help. Enable the features that make this access possible, and select the websites to make available to users.

Enabling Features

In the Offerings work area:

  • Leave the Local Installation of Help feature enabled at the offering level.

  • Enable the Access to Internet-Based Help Features feature at the offering level to allow access to websites from Applications Help. For example, some help files link to guides on the Oracle Help Center; this access is necessary for those links to work.

Selecting Websites

In the Setup and Maintenance work area, use the following:

  • Functional Area: Application Extensions

  • Task: Set Help Options

In the Web Sites Available from Help Site section on the Set Help Options page, select the sites to link to. These links would appear in the Navigator menu in Applications Help.

Users with the appropriate roles can edit predefined help or add their own files to help. To enable and set up for creating and editing help, do the following in the specified order.

Enabling Features

In the Offerings work area, configure the following features at the offering level.

  • Leave the Local Installation of Help feature enabled.

  • Enable the Help Content Management feature.

  • Enable the Security for Added Help feature if you want certain help files to be available only to a restricted set of users.

    Caution: Don't enable this feature if you don't have this requirement, because the feature can affect performance.

Setting Help Options

Optionally set any of the following help options according to your requirements:

  1. In the Setup and Maintenance work area, go to the following:

    • Functional Area: Application Extensions

    • Task: Set Help Options

  2. On the Set Help Options page, in the Help Site Appearance section, provide a source name and image used to identify files in Applications Help that were added or edited.

  3. In the Oracle User Productivity Kit section, add a link from the Navigator in Applications Help to your User Productivity Kit library.

  4. In the Privacy Statement section, add a link to your own privacy statement. To see this link, users click their user name in the global header of Applications Help.

Providing Users Access to Create and Edit Help

Only users with job roles containing the Manage Help Content (ATK_CUSTOMIZE_HELP_TOPICS_PRIV) privilege can create and edit help. The Assign Help Text Administration Duty task is a reminder for you to follow up with your security administrator. Make sure that users who want to create and edit help have the access to do so.

Setting Up Help File Security

If you enabled the Security for Added Help feature, then use the Manage Help Security Groups task in the Setup and Maintenance work area. Select job roles to include in help security groups. When you or other users then create or edit a help file, they can select a group to determine which job roles have access to the file.

FAQs for Set Help Options

What's available on the page depends on the help features that you enable in the Offerings work area. This table describes the correlation between features and specific sections on the Set Help Options page.

Help Feature Section on Set Help Options Page

Local Installation of Help

None, but without enabling this feature, you can't enable the other help features

Access to Internet-Based Help Features

Web Sites Available from Help Site

Help Content Management

Help Site Appearance

Oracle User Productivity Kit

Privacy Statement

Security for Added Help

None

If you license Oracle User Productivity Kit and have your own User Productivity Kit content to share with your users. Topics that you add as help files in Applications Help are available only in the See It mode. However, in the library, users can see the same topic in other modes. If you have User Productivity Kit versions earlier than 3.6.1, then you can't add User Productivity Kit topics as help files. So the link to the library is the only way users can get your User Productivity Kit content from Applications Help.

The full path from the Web server where you're hosting your Oracle User Productivity Kit content to the index.html file that opens the table of contents for the library. For example, http://<your domain>.com/MyContent/PlayerPackage/index.html.

In this example, you or your administrator published one player package that contains all the content to be linked to from Applications Help, including the index.html file, and placed the PlayerPackage folder in a folder called MyContent on the Web server.

FAQs for Assign Help Text Administration Duty

How can the icons for help windows be shown by default?

In the Setup and Maintenance work area, use the following:

  • Functional Area: Application Extensions

  • Task: Set Help Options

On the Set Help Options page, select the Show help icons by default check box in the Show Help section. You just need to do this setup for one offering, and the setting applies to all users.

Every time users sign in, they can see help icons wherever available on the pages they use. To hide the icons, users can still click their user image or name in the global header and select Hide Help Icons, as well as select Show Help Icons to display the icons again.

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.

Manage Help Security Groups

This example shows how to create a help security group, which contains a set of job roles. You can later assign the help security group to particular help files so that only users with any of the included job roles have access to the help.

The following table summarizes key decisions for this scenario.

Decisions to Consider In This Example

What type of users do you need to limit help access to?

Human resources (HR) specialists

Is there a specific time period for which this access is needed?

No, the help files should always be viewed only by the HR specialists

Where do you want this group to appear in the list of values for help security groups?

First

Define a help security group and assign a job role to the group.

Prerequisites

  1. In the Offerings work area, make sure that the Local Installation of Help feature is enabled at the offering level.

Creating the Help Security Group

  1. In the Setup and Maintenance work area, go to the following:

    • Functional Area: Application Extensions

    • Task: Manage Help Security Groups

  2. On the Manage Help Security Groups page, add a new row.

  3. Complete the fields, as shown in this table. Leave the start and end dates blank.

    Field Value

    Help Security Group

    HR

    Meaning

    HR Only

    Description

    Viewing by HR specialists only

    Display Sequence

    1

  4. Click Save.

  5. With your new help security group selected, go to the Associated Roles section and add a new row.

  6. Select PER_HUMAN_RESOURCE_SPECIALIST as the role name.

  7. Click Save and Close.

    To assign your new help security group to help files, you must create or edit help using the Manage Help Content page, not help windows.

Help File 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

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.

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.

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.

FAQs for Help File Management

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.

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