Creating good Descriptions and Short Descriptions

Rule forms and data instance forms contain a Description field, also known as its label. Internally, the Description field corresponds to the @baseclass.pyLabel property. (On some rule forms, the field is labeled Description rather than Short Description.)

Take a few seconds to choose the text you enter in this field as you save each rule. Your choice can enhance your personal productivity, the productivity of your development team, and affect the usability of your application.

Short Description text is used as follows:

• As user prompt text
• As documentation
• Supporting rule searches and Explorer displays
• Supporting the application menu on the Designer Studio

While most Description text is less than 30 characters long, enter more than 30 characters when necessary. (The limit is 64 characters.)

Description text as user prompts

In important special cases, Description text is visible to application users. Choose text meaningful to such users:

• Flow action rules — Description text appears as selection text in selection lists on user forms, or as button labels. See More about flow actions.
• Certain class rules — The Description text of certain Work- classes (those that correspond to class groups) appear as work pool names. The current application name controls the scope of many portal functions. See work pool name, work pool, and More about Classes.
• Certain flows that create work items — For flows with the Creates a new work object? checkbox selected, the Short Description text appears in as a selection in the New selection box in the Process Work layout. See More about Flows and WorkManager and WorkUser portal basics — Using the Process Work workspace.
• For Single Value properties, the Description text appears in certain Report Viewer and Report Wizard lists.

If a standard flow action, flow, or class rule meets your application needs except for its Description text, you can override only the Description with the Localized Label field in a field value rule.

Changes you make to the Description text of a checked-out rule may become visible only after you check in the rule.

Description text as documentation

For Descriptions on other rule types, enter a sentence or phrase that describes how you expect the rule to be used. You need not enter your name, the RuleSet, any key part, or the date, as these facts are present (and searchable) elsewhere in the rule.

The value you enter appears on reports, lists, and SmartPrompt ToolTips. Choose a value that helps you or others select a rule of interest from a possibly long list.

Current application name on Designer Studio Application Menu

The text in the Description field of an application rule appears as the current application on the Designer Studio Application menu. The name also appears in the Switch Application menu list. Enter a unique, meaningful name. Include a version number if users have access to multiple versions using the same description.

Supporting rule searches and Explorer displays

Choose Description text that support searches. Longer, specific words (such as Mortgage) are more useful when searching than common short words. To search for a rule based on its Description:

1. Perform any search. From the results panel, select Show Settings.
2. Select the Rule checkbox, the Content radio button, and the Starts With radio button
3. Enter a new search in the form pyLabel:Text, where Text is the initial portion of the label in the rule you are searching for, containing no spaces or special characters. Enter the text in the exact case.
4. Press Enter.

For class rules, if you set the Explorer preference Display Type as Label, the Description of each class appears in the Explorer tree displays. To do this, select Preferences from the Designer Studio profile menu and the select the View item. Change the Display Type to Label and click  Save  . This mode is most useful for custom work types — the concrete Work- classes in your application.

Lookup Cache supports SmartPrompt ToolTip display

Short Description or Description text appears as a ToolTip on SmartPrompt displays, when the developer holds a pointer on a row of the selection list. (SmartPrompt displays are primarily accessed by developers, not by application users.)

In some cases, after you update the Short Description or Description of a rule, an internal cache that supports SmartPrompt may become stale; the ToolTip display presents the prior value. To remedy this, delete the on-disk cache using the System Management application:

1. Select> System > Tools > System Management App to start the System Management application. Authentication may be required.
2. On the System Management application window, select a node.
3. Select the Advanced > ETier Static Content Management menu item.
4. Click  Delete LookupList Cache.

PDN Resources

See PDN article 26160 Standards for Class Names and Rule Names.

	lookup list, personal RuleSet
	Choosing rule and data instance names

Designer Studio basics