10Define Help Configuration

This chapter contains the following:

Setting Up Help: Overview

Applications Help works 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 on the Edit Features page. 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 Customization

  • Custom Help Security

Help Configuration Tasks

In the Setup and Maintenance work area, use these tasks in the Application Extensions functional area to configure Applications 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.

  • 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 configure 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

Setting Up for Creating and Editing Help: Procedure

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 steps in the specified order.

Enabling Features

Perform these steps:

  1. In the Offerings work area, select your offering.

  2. Click Opt In Features.

  3. On the Opt In page, click the Features icon for your offering.

  4. On the Edit Features page, leave the Local Installation of Help feature enabled.

  5. Enable the Help Customization feature.

  6. Enable the Custom Help Security 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.
  7. Save your work.

Setting Help Options

Perform these steps:

  1. Click Navigator > Setup and Maintenance.

  2. On the Setup page, select your offering.

  3. Select the Application Extensions functional area and then the Set Help Options task.

  4. Optionally set options in these sections:

    • Help Site Customization:

      • Determine how users can identify files in Applications Help that were added or edited.

      • Upload your own image to use as the background picture on the Applications Help home page.

    • Oracle User Productivity Kit: Add a link in the Navigator in Applications Help to your User Productivity Kit library.

    • Privacy Statement: Add a link to your own privacy statement. To see this link, users click their user name in the global header of Applications Help.

  5. Save your work.

Providing Users Access to Create and Edit Help

Only users with job roles containing the 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 selected the Custom Help Security feature, then open 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

When do I link to the Oracle User Productivity Kit library from Applications Help?

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.

What's the URL for my Oracle User Productivity Kit library?

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

Who can create, edit, and manage help?

Users with the Customize Help Topics (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

Creating Help Security Groups: Worked Example

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. Open the Edit Features page for your offerings in the Offerings work area.

  2. Make sure that the Location Installation of Help feature is enabled.

Creating the Help Security Group

  1. Click Navigator > Setup and Maintenance.

  2. On the Setup page, select your offering.

  3. Select the Application Extensions functional area and then the Manage Help Security Groups task.

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

  5. 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

  6. Click Save.

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

  8. Select PER_HUMAN_RESOURCE_SPECIALIST as the role name.

  9. Click Save and Close.

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

Help File Customization

Help File Customization: Overview

If you have the appropriate roles, then you can customize the 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 tabs a file belongs to in Applications Help.

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

  • Custom:

    • Create, duplicate, edit, and delete

    • Set status (Active or Inactive)

  • Predefined:

    • Duplicate

    • Edit (which is really creating a custom version of the predefined file)

    • Set status

Navigation

This table describes where to go to customize help.

Help Customization Task Navigation

Create or edit help for a specific help window.

Click the Manage Custom Help 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 customization task, including managing a set of help (such as all help for a product)

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

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

Create a configuration package then use the export and import feature in the Setup and Maintenance work area.

  • The configuration package must use a source implementation project that contains the Define Help Configuration task list.

  • Select the following objects to export:

    • Help Configuration

    • Help Topic

Help Types: Explained

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. When you read help and 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.

Assigning Help Locations: Procedure

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 Custom Help page in Applications Help, not the Manage Custom Help 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 Custom Help.

  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.

Links in Custom Help: Points to Consider

When you create or edit custom 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 custom 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 right title IDs. To find title IDs, search for the help files on the Manage Custom Help 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 Custom Help 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.

Customizing PDF Guides: Worked Example

This example demonstrates how to customize 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 customized guide appear in any help window?

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

Which products and tasks should the customized 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 customized guide?

No, same as the original guide

Do you want to tag the customized 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. Create a custom version of the original help file, with your new PDF as the help content.

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.

  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 customized 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 enter the values listed in the following 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.

Adding Custom User Productivity Kit Content to Help: Worked Example

This example demonstrates how to add a custom 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 custom 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, click and drag the Document ID column header and drop it 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 the custom 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 under the Deployment check box group.

  4. In the Player section, select the Include HTML Web Site check box. Your custom 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 Custom Help File for the Topic

  1. Open the Scheduled Processes work area.

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

  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 Customization

What happens to my custom help after an upgrade for Applications Help?

Nothing happens to your custom help files. Upgrades affect only predefined help files, active or inactive.

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

  • Activate the updated version.

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

Embedded Help Customization

Customizing Help That Appears on the Page: Highlights

You can customize help that you see on the page, for example hints for check boxes 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