Modify the Help command to use URLs defined in a Preference

The Help command in the Active Workspace Client (AWC) provides a link that is hard coded into the client source files and set to take users directly to the Siemens Online Help Documentation for the version installed.

This is not preferred due to the fact that most users do not have access to the online help, but rather a local version of that help.

Why modify the Help Command?

This use case provides a method of customizing the Help command to retrieve URLs from Teamcenter and Active Workspace Preferences, allowing for the easy administration of the URL to point to either local or external sources.

The Help command in Teamcenter's Active Workspace Client (AWC).

Are there alternate approaches to take without customization?

Yes. Customization always poses a risk. Alternate methods and approaches include manipulating Tiles to expose URLs, however these are not tailorable to utilize Preferences for "easy" modification of the URLs and include additional maintenance, while the Help command provides the ability to dynamically pull this information; not only by Preference but also by Active Workspace location.

What skills or knowledge are required to deploy the modification?

The primary topics (or prerequisites) for fully understanding the process to enable this embedded help and to override the Help command include:

• Using Teamcenter's Active Workspace software at a core level.

• Understand how to work with Preferences (in Teamcenter or Active Workspace).

• Understand Active Workspace Client (AWC) development practices.

• Have an understanding of the locally installed online help location (at your company) to provide links to the configured Preferences.

Demonstration

Process: Modify the module.json file in the Stage\Repo directory

Open the module.json file in the %TC_ROOT%\Aws2\Stage\Repo\tc-aw-framework directory in a text editor.

In the module.json file, locate the showHelp action.

In the showHelp action, modify the navigateTo value to match the following code.

Caution. It is extremely important to note that any modifications to files in the Stage\Repo directory must be documented and tested after each patch or upgrade. This is due to the patches and upgrades may override these settings.

"showHelp": {
        "actionType": "Navigate",
        "navigateIn": "newTab",
        "navigateTo": "{{ctx.preferences.AW5_help_url[0]}}",
        "navigationParams": {}
      },

Tip. The AW5_help_url value is a custom preference. This preference does not exist yet. The value may be different if you use a different name for your custom preference. In a later step we will create the preference. As an example, the string could be "navigateTo": "{{ctx.preferences.MYCUSTOMPREF[0]}}",. The biggest thing is no spaces and remember the value. No matter what, [0] will be at the end.

Save and close the module.json file.

Open an Administrative Command Prompt (or Terminal in Visual Studio Code) and change the directory to:

%TC_ROOT%\Aws2\Stage

Run the awbuild.cmd command.

Verify the Active Workspace Client (AWC) build completes successfully.

Tip. The output of the command will be similar to the image (below).

Process: Create the custom preference

The process to create the custom preference is performed using the Preferences location in the Active Workspace interface in this example. This process may also be executed in the Rich Client, but we are sticking to Active Workspace for the tutorial.

In Active Workspace, switch to the Active Admin Workspace.

Tip. The Active Admin Workspace may only be available if you are in the dba Group and DBA Role.

Click the Preferences Tile on the Home page.

On the Preferences location, select the Site organization element.

With the Site element selected, choose New > New Preference from the Primary Toolbar.

In the New Preference panel, fill in the values for the new preference.

Note. In this example, we use the AW5_help_url value which was referenced in the module.json file as the name of the preference. This value needs to match the value inputted into the navigateTo field in the showHelp action.

In the example, we chose the following values:

• Name: AW5_help_url

• Product Area: Active Workspace

• Description: Help URL for Help Command.

• Protection Scope: Group (this could be set to site if you do not want to override the preference for specific groups).

• Environment: Enabled is not checked.

• Type: String

• Values: https://www.awtoolbox.com/copy-of-topic-courses (this value may be any URL you use for the help that is accessible).

Click Add located at the bottom of the New Preference panel.

Verify the new preference is added.

Process: Add the custom preference to AWC_StartupPreferences

In the Preferences location, locate and select the AWC_StartupPreferences preference.

Tip. Search for the value AWC_Startup in the search field above the preferences table.

Click Edit in the work area.

In the preference definition, in the Values field type AW5_help_url.

Click off of the value to apply the value, or press Enter.

Input the AW5_help_url into the AW5_help_url preference.

In the Values field, scroll to the bottom of the list to verify the new preference is added, then click Save.

Verify the AW5_help_url preference is added in the Values list for the AWC_StartupPreferences preference.

Process: Verify the customized Help link functions as expected

In Active Workspace, click the Help > Help command.

The Active Workspace Help command. The command opens the Active Workspace online help documentation by default.

Verify the URL entered into the custom preference value opens in a new tab.

Tip. You may need to refresh the browser or log out and log back into Active Workspace to get the result to display on the first test.