This guide also applies to on-premises implementations

6Help Customization

This chapter contains the following:

Customizing Help: Overview

You can customize help files in Applications Help and help windows, as well as help text that appears on UI elements. The Getting Started work area can also be customized.

Note: To enable help file and Getting Started customization, you or your implementor must select the Help Customization feature choice in your offering configurations.

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 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 name in the global area and select Applications Help.

You have many options to customize 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 customize predefined pages and create pages with your own custom 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 customize 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.

Who can add and manage custom help?

Users with the Customize Help Topics (ATK_CUSTOMIZE_HELP_TOPICS_PRIV) privilege can customize:

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

Source Types for Custom Help: Explained

You have many options to determine the content of custom help, for example by uploading a 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 custom 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 Web site 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.

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.

Page or Section Values: Explained

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 Custom Help 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), or dashboard regions

  • In the Setup and Maintenance work area, next to names of task lists or tasks in tables

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.

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.

Customizing Help

Watch video

Watch: This video tutorial shows you how to add and edit help in help windows.

Customizing Help in Help Windows: Procedure

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

Tip: You can also use:
  • The Customer 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 a help window

Opening the Manage Custom Help Dialog Box

Use the Manage Custom Help dialog box to create and edit help files, or to reorder links:

  1. Click the help icon to open the help window you want to customize. If you don't see any help icons, click Show Help in the global area.

  2. Click Manage Custom Help.

Editing Help Files

To edit help files in the help window:

  1. Open the Manage Custom Help 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 custom version of the predefined file.
  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.

Creating Help Files

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

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

  2. Click Create.

  3. Select a source and enter 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, keywords, and description for your file.

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

  7. Save your work.

Adding Links to Help Windows

To add existing custom help files as links in any help window:

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

  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 existing custom help file, select it, and click Apply.

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

  7. Click Done.

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 area 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 above) to narrow down the list of available page or section values.

    Note: For any help window for task lists or tasks in the Setup and Maintenance work area, select this hierarchy:
    • Hierarchy: Task

    • Level 1: Functional Setup

  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.

Adding Help to the Getting Started Region in Applications Help: Procedure

In Applications Help, users can use the tabs right below the global area to browse help by product family. Every product family tab has a Getting Started region, 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 custom help to the Getting Started region for any product family.

Adding Help to the Region for a Product Family

Follow these steps:

  1. Click your user name in the global area in Applications Help, and select Manage Custom Help.

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

  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 that you want the file to appear under. Optionally select a product in the Level 2 column.

  7. Save your work.

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.

This figure provides an example of related links code.

The letters O, f, a, followed immediately by: RelatedTopics(CREATE_AUTOMATIC_POSTING_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>.

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.

This figure shows an example of code for a glossary term link.

The letters O, f, a, followed immediately by: GlossaryTerm("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 following values.

    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 one next to the Overview page title 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.

Editing Glossary Terms: Procedure

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 area 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 custom version.

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

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

FAQs for Help File Customization

What happens when I edit predefined help?

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

How can I add a Youtube video to custom help?

Create a custom 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.

How can I restrict access to specific help files?

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

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

  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 choice in the Setup and Maintenance work area.

  3. Save your work.

What's the difference between assigning a role and a security group to a help file?

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 custom help in their search results?

If you customized 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.

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.

How can I change the background image on the Applications Help home page?

In the Setup and Maintenance work area, open the Set Help Options task, and upload your own image in the Help Site Customization section. Use an image that's white along the entire left border, like you see in the default image.

Note: If you don't see the Help Site Customization section on the Set Help Options page, check with your implementor about selecting the Help Customization feature choice.

Customization of Getting Started Pages

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 customize the predefined pages or add your own, so that users get content specific to your organization.

Access to Customization

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

Key Customization 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 custom 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 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