Conditional help in SAP Companion

The 3.1.28 release of SAP Companion has introduced the most significant piece of new functionality in a long time – Conditional Help. In this post, we’ll look at what Conditional Help is, and how you can use it.

Conditional Help is, as you would expect from the name, help that is displayed to a user depending upon a specific condition. This means that you can display help content that is tailored to an individual user. Currently, this can be done for individual Help Topics (individual tiles in the Carousel) – including Link Tiles and Guided Tours as a whole, but not for individual Steps in a Guided Tour (but I would expect this functionality to be added in a (near-)future release).

Conditions are defined via a new Topic-level menu option (displayed when you click on a Help Topic in Edit mode), of Set Conditions:

Three types of conditions can be defined:

• Element conditions
• URL conditions
• API conditions

You specify which one of these condition types you want to define in the first field of the Conditions dialog box.

Additional fields will be added to the right of this selection as you define the condition, and depending upon the condition type. You can also ad multiple conditions (of different types) by clicking the Add Condition button, and choose whether all (AND) or any (OR) of these conditions should be met for the help to be displayed.

Element Conditions

An element condition allows you to make the display of the help tile to be conditional on the state of some specific element on the screen. This can be the same element as the one to which the Help Topic is assigned (via a Hotspot), but could be any other condition on the screen. Possible use-cases are displaying help when a field contains a specific value (for data validation), or when a field is empty (to hide help when a field has been completed), and so on.

When you define an element condition, the following fields and options are available (from left to right in the Conditions dialog box):

1. Condition type: Element
2. Element Selection: Which element to base the condition on. You can select Use Assigned Hotspot to base the condition on the element to which the Help Topic is assigned (via a Hotspot), or use choose Select Element to use any other element on the screen. In this latter case, a Select Hotspot indicator is shown to the immediate right of this field (as shown in the example above); you need to click on this and then select the required screen element (using the existing Hotspot functionality).
3. Criteria: Choose the comparison criteria to use. For example, “contains”, “is blank”, “is less than”, and so on.
4. Value: Depending upon the criteria type, specify the value to be used for the condition.

URL Conditions

URL conditions apply to the URL of the current browser page. You can define a condition based on all or part of the URL, which can be very useful where additional information is coded into the URL (for example, by way of parameters). For example, in SAP Companion you could set a condition to see if the parameter editor=true is set, and then show additional help tiles that are only applicable to help content creators – such as writing guidelines.

When you define a URL condition, the following fields are available (from left to right in the Conditions dialog box:

1. Condition type: URL
2. URL Selection: Choose which portion of the URL you want to base the condition on. Choices are:
   • Full URL: The complete URL as displayed in the browser address bar
   • Domain: The domain portion of the URL (for example, enablenowexpert.com)
   • Hash: Everything after any ‘#’ in the URL. This is usually an anchor location on a web page or – for Fiori applications – the application name.
   • Query: Any parameters included in the URL. Parameters are introduced by a ‘?’ and are separated by ‘&’s. Parameters are typically name-value pairs, and you can set a condition on the name, value or combination.
   • Pathname: Anything between the end of the domain name and the parameters or hash. This is typically sub-directories on the web server (for example, in a URL of enablenowexpert.com/posts/post.php, the Pathname is posts).
3. Criteria: Choose the comparison criteria to use. Options are, contains, does not contain, starts with, does not start with, ends with, does not end with.
4. Value: Depending upon the criteria type, specify the value to be used for the condition.

API Conditions

API conditions leverage the SAP Companion API (Help4), and allow you do display help based on any parameter stored within this. These parameters need to be set by the application, so are most useful for third-party application integration, but hopefully SAP will start providing certain parameters – for example the user’s role for SuccessFactors, and so on.

When you define an API condition, the following fields are available:

1. Condition Type: API
2. Field: The list of defined condition fields will be available on the drop-down, or you can enter the field name directly.
3. Criteria: Choose the comparison criteria to use. Options are is, is not, contains, does not contain, true, false.
4. Value: For all criteria types except true and false, specify the value to be used for the condition.

Although you will need to rely on the field/value being set by the application, you can test API conditions yourself, by setting the field/value in the Developer Console in the Browser. Just enter a command of:

Help4.API.setCondition('<field>','<value>');

for example:

Help4.API.setCondition('userRole','Manager');

Validation

Regardless of the type of condition you specify, an indicator is shown on the far right of the condition, indicating whether or not the condition is currently met (see the examples, above). This is a useful check to see if you have entered the condition correctly.

The same indicator will show a warning icon (see the first screenshot above) if the condition is not correctly or fully specified.

Summary

By using Conditions you can add a great deal of flexibility to your help, and make it even more responsive to the user’s situation and the values they enter (or don’t enter) on the screen. There’s truly a lot of possibilities, and as SAP adds API values to their applications, this will only grow in usefulness.