Creating Custom In-Product Help

As an AAI administrator or supervisor, you can customize the in-product AAI Help to display your own custom help content to users in your organization. You can embed links to other resources that you want to direct your users to, including links to videos, or even completely replace the existing content with content of your own creation. You do this with Broadcom's own Integrated Content Experience (ICE) Admin tool. This topic describes your customization options and how to create and manage your own custom, in-product help for AAI.

Understanding Custom Help Content

By default, AAI provides in-product help, called AAI Help, that appears in a panel when a user clicks the question mark (?) icon in the upper right corner of a page or dialog in AAI. If you want to enhance the default help with content that is specific to your organization, you can do this by creating Custom Help that appears to your users when they call up the AAI Help instead of the default content.

Examples of custom content that you could provide include the following:

• Custom steps with specific values that your users need to enter for various fields, instead of the default help that offers all possible options

• A card with naming convention guidelines on pages where your users add new jobstreams, business areas, or schedulers

• Links to company-internal web pages or to videos that contain helpful support information

• Links to third-party tools that your company uses

You create and manage Custom Help with Broadcom's Integrated Content Experience (ICE) Admin tool. In the ICE Admin tool, you create custom content in chunks called "Cards" which you associate with the location in AAI where you want the content to appear when a user calls up AAI Help.

Using the ICE Admin tool to create cards, you can customize the in-product AAI Help, in several ways:

• Creating Custom "Cards"

  In-product AAI Help provides content that helps you use the page that you are currently viewing. In addition to help topics that tell you about your current page and how to use it, each help pane also provides access to content from other sources when there is relevant content available. By adding a custom card, you can share best practices or policies that are specific to your organization or call out differences in your processes from standard AAI examples.

• Linking Custom Videos

  You can create custom videos that walk users through the use of a page that conforms to your own standards and policies. You can host these videos on your local Google Drive and link to them in the custom card.

• Completely Replacing the Content

  If you have your own comprehensive set of content for using AAI, you can replace all of the content that we create with your own custom content and link it to the appropriate pages in AAI.

To create and manage your own custom content in AAI Help, involves the following steps.

• Requesting Access to ICE Admin

• Accessing Your Custom Content Configuration

• Creating Custom Help Cards, which you can also do by Copying Custom Content from Another Configuration

• Deleting Custom Cards

• Deleting URLs in the ICE Admin Tool

Requesting Access to ICE Admin

You configure the content that displays within the AAI UI in the Integrated Content Experience (ICE) Admin tool.

To request access to the ICE Admin tool:

Before you begin, be sure you have the URL and subscription ID for each AAI subscription that you want to create Custom Help for.

1. Go to https://support.broadcom.com/ and log in. For more information about creating an account, see this Knowledge Base article.

2. Select My Cases in the navigation pane on the left.

3. Click the menu icon in the upper left of the page, next to the Broadcom logo, and select Create Case.

4. Complete the following fields:

   • Product:Select AAI as your product.

   • Subject : Enter "Request tool access for Custom Content for In-Product Help" in this field.

   • Description: Enter the URL and Subscription ID for each AAI subscription that you want to create Custom Help for. Each AAI subscription requires its own configuration.

     If you have multiple subscriptions, please include a parenthetical description of the subscription to clarify which is which.

Accessing Your Custom Content Configuration

After you submit your Broadcom Support case, you will receive an onboarding email that contains access credentials that let you log into the Integrated Content Experience (ICE) Admin tool where you can add and manage your custom content.

When you log into the ICE Admin tool, you will see a list of configurations that have been created for you based on the subscriptions that you included in your Support request.

To access a configuration:

1. Go to https://admin.ipce.broadcom.com/ after you receive an onboarding email from Broadcom.

2. Login using the credentials that you use to access Broadcom Support.

3. On the home page, under Products, select AAI to open the configurations that are assigned to you.

   

4. In the Configurations pane, select the configuration that you want to view.

   

Creating Custom Help Cards

A custom card contains custom content for your organization that can appear in the AAI Help panel for a specific page in the UI.

For example, the help for the Jobstream Runs - Grid View contains a brief description followed by cards called The Grid View Page, The List of Jobstream Runs, Creating and Using Saved Views, Filtering the Jobsteam Runs Grid View. You can add additional cards for your Custom Help content for this page. For example, here you could add a card called "Our-Company's Jobstream Naming Conventions" that contains guidance about naming new jobstreams. The title of the card and the content that displays is up to you.

To create a custom card:

1. Log into the ICE Admin tool at https://admin.ipce.broadcom.com/.

2. On the home page, under Products, select AAI to open the configurations that are assigned to you.

3. In the Configurations pane, select the configuration that you want to update.

4. Select the Custom Content tab.

   

   If you have defined custom content for other pages in AAI, the URLs for the defined content display in the Select Where Custom Card Will Appear field. Select any of these locations to update existing custom content.

   

5. To create content for a new location in AAI, select Add New Custom Content from the Select Where Custom Card Will Appear field.

6. Enter the URL for the AAI page in the Add Product Area URL field, using the following guidelines:

   • Do not enter the fully-qualified URL. Enter only the unique portion of the URL that follows the host and port, starting with /aai/web/v2/ and then whatever follows.

     In our example before these steps, the URL is /aai/web/v2/jobstreams/runs/grid.

   • Some pages the show information that is specific to a certain object instance or specific to the creation user. For these pages, a portion of the URL is a unique ID for an object instance. In these cases, use an asterisk (*) as a wildcard for that portion of the URL.

     For example, if you are creating a custom card for a Job Status data insight, the URL will look something like https://[host:port]/aai/web/v2/insights/AWLlGkZAQIY=/jobstatus. To add a card that appears for any Job Status data insight that your users opent, enter "/aai/web/v2/insights/*/jobstatus".

   • Some pages have tabs or views with their own identifying URL. To add a card for one of these, make sure to take the URL of the tab or view. For example, Tabs and views Some URLs reflect the filters that are applied to the page. These appear in the URL starting with a question mark.

     For example, the Alerts tab of a jobstream's details page has the URL /aai/web/v2/jobstreams/AXrQ8bPkpVE=/alerts. To add a card for this tab, enter "/aai/web/v2/jobstreams/*/alerts". (The asterisk (*) is the wildcard for any jobstream.)

     Similarly, to add a card for the SLA Graph view of the Run Details tab of any jobstream's details page, you enter /aai/web/v2/jobstreams/*/run-details/sla-graph.

   • Some URLs reflect the filters that are applied to the page. These appear in the URL starting with a question mark.

     For example, /aai/web/v2/jobstreams/runs/timeline?businessArea=All%20Jobstreams. To have your custom card appear for that page, regardless of which filters are applied, exclude the question mark and everything to the right of it. In this example, enter "/aai/web/v2/jobstreams/runs/timeline".

   • You can also create cards for a specific instance of an object. For example, if you wanted to have cards for a specific Trending Jobs data insight, keep its unique ID in the URL that you enter.

     For example, enter /aai/web/v2/insights/AZLPiOVmGMM=/trendingjobs, with no wildcard.

   Note:

   Every page and tab on a page in AAI has a unique specific URL or URL pattern, that typically reflects the name of the page or tab.

   However, dialog windows, also called "modal dialogs," do not have unique URLs. Instead, they use the same URL as the main page or tab from which you called up the modal dialog. Adding custom content for these dialogs is not currently supported.
   

   For more information, see Tips for Entering URLs and Example URLs.

7. Select a viewing priority of how your custom card should appear in relation to the default AAI Help cards.

   • Prioritize Default Cards: Your cards appear below the standard cards in the AAI Help panel.

   • Prioritize Custom Cards: Your cards appear above the standard cards in the AAI Help panel.

   • Hide Default Cards: Only your custom cards display. All standard AAI content is hidden.

8. Click the + Create a card button.

9. Select the icon that you want to use for your card from the Icons list.

10. Enter the title that you want to display on your custom card in the Title field.

11. Enter a description for your custom card in the Description field.

    The description displays below the title in the custom card.

12. Define the content of the card :

    • Create a card that links to a specific URL outside of AAI:

      Enter the target URL in the Link with URL field.

      For example, you can use this option to link to your organization's content repository or to a YouTube video or playlist.

    • Create a card that displays content in the AAI Help panel:

      Enter the desired content in the Display Information field.

      You can enter this content as text, but your formatting options are limited. You can also enter this content as HTML and tag it accordingly.

    • Create a card that displays content in the Help panel and includes a link to an external source after the displayed content:

      Enter the target URL in the Link with URL field.

      This link appears at the bottom of your custom content.

      Enter the desired content in the Display Information field as text or HTML.

      Important!

      If you are linking to a YouTube video, you must use the embed URL rather than the watch URL. For example:

      Use
      https://www.youtube.com/embed/TAB_brAvKo8?si=WkxhwX-4ISFt5kOS" title

      Instead of
      https://www.youtube.com/watch?v=TAB_brAvKo8&list=PLynEdQRJawmzUQCBNZROx4cDIAc6ytjFO&index=1&pp=iAQB

13. To add another card to display for this page in the AAI Help panel, select Create another card.

    Note:

    To change the order in which your cards appear in the AAI Help pane, drag and drop your them in the preview pane into the sequence you want .

14. Select Update Configuration to save your changes.

    Your changes will be available in the product within five minutes of updating the configuration.

Tips for Entering URLs and Example URLs

The value that you enter in the Add Product Area URL field depends on where you are in AAI and when you want your custom card to show up in the AAI Help panel.

Typically, when you create a custom card you want it to appear for every instance of an object. For example, you would create a card for all business areas, rather than for each specific business area. Therefore, as a general rule, in cases where the URL contains a unique ID for the specific object instance, replace that with an asterisk (*) as the wildcard character, so that the custom card appears for all instances, in our example, for all business areas.

However, if you want a custom card to appear for only one specific instance of an object, for example, for a specific data insight, then you should leave the unique ID specific object instances. You want to use URLs with these unique IDs instead of the wildcard character (*) only in very specific circumstances, as you see among the examples in the table that follows.

Example URLs to enter in the Add Product Area URL field

The following table contains examples of URLs as you would enter them in the Add Product Area URL field for various areas in AAI, that is, not as a fully-qualified URL and with the necessary wildcards as described in the table. The second column, Where the Card Appears, describes where the user is in AAI when the user clicks the question mark to open the AAI Help.

URL	Where the Card Appears
/aai/web/v2/jobstreams/	In the AAI Help panel for the Jobstreams Definitions page.
/aai/web/v2/jobstreams/runs/grid	In the AAI Help panel for the Jobstreams - Grid page
/aai/web/v2/jobstreams/runs/timeline	In the AAI Help panel for the Jobstreams - Timeline page, regardless of business area filter
/aai/web/v2/jobstreams/runs/timeline?businessArea=All%20Jobstreams/Finance	In the AAI Help panel for the Jobstreams - Timeline page for the Finance business area only
/aai/web/v2/dashboard/*	In the AAI Help panel for the Dashboard in general, regardless of which dashboard tab the help is opened on
/aai/web/v2/jobstreams/*/run-details/relative	In the AAI Help panel for the Relative to SLA view of the Run Details tab of any jobstream definition.
/aai/web/v2/jobstreams/AZMcvu3RZLo=/run-details/relative	In the AAI Help panel for the Relative to SLA view of the Run Details tab of the jobstream with an internal ID of AZMcvu3RZLo.

Copying Custom Content from Another Configuration

If you have access to multiple configurations, you can copy your existing custom content from one configuration to another to save time and ensure consistency across configurations.

For example, if you have created Custom Help content for your test environment, you can copy that content to your production environment rather than re-creating that content manually.

To copy custom content:

4. Log into the ICE Admin tool at https://admin.ipce.broadcom.com/.

5. On the home page, under Products, select AAI to open the configurations that are assigned to you.

6. In the Configurations pane, select the configuration that you want to update.

7. Select the Custom Content tab.

8. Select Copy Custom Content at the top of the page.

   

9. In the dialog that opens, in the Select Source Configuration field, select the configuration that you want to copy content from.

   

10. Select one of the following options:

    • Merge: Selecting this option copies all custom cards from the source configuration and leaves the existing cards in your current configuration in place, merging the two together. If you copy a card with the same title for the same Product Area URL, and the content for that card is different, the copied card is added to the Product Area URL rather than replacing the existing card.

    • Replace: Selecting this option removes all existing custom content in your current configuration and replaces it with the custom content from the source configuration.

    A confirmation dialog appears that provides details of the merge or replace.

11. Review the details and select Confirm.

Deleting Custom Cards

You can delete custom cards by selecting Delete on a card.

Ensure you select Update Configuration to save your changes.

To delete a custom card:

4. Log into the ICE Admin tool at https://admin.ipce.broadcom.com/.

5. On the home page, under Products, select AAI to open the configurations that are assigned to you.

6. In the Configurations pane, select the configuration that you want to update.

7. Select the Custom Content tab.

8. Select the URL for the custom content from the Select Where Custom Card Will Appear field.

9. In the tile for the card you want to remove, click the Delete trash can icon.

   

10. Select Update Configuration.

    Your changes will be available in the product within 5 minutes of updating the configuration.

Deleting URLs in the ICE Admin Tool

If you no longer need custom content for a specific URL, you can delete the entire URL and all associated cards from your configuration.

To delete a URL:

4. Log into the ICE Admin tool at https://admin.ipce.broadcom.com/.

5. On the home page, under Products, select AAI to open the configurations that are assigned to you.

6. In the Configurations pane, select the configuration that you want to update.

7. Select the Custom Content tab.

8. Select the URLfor the custom content from the Select Where Custom Card Will Appear field.

9. Select Delete on the bottom left corner to delete the URL and all associated custom cards from this configuration.

   

10. Select Update Configuration.

    Your changes will be available in the product within 5 minutes of updating the configuration.

 

See also:

Getting In-Product Help in Using Help