Creating guides

Process for creating a guide

When creating guides, it is helpful to plan them out first. Use the following steps before you begin creating active link or filter guide objects.

1. Plan the guide.
   • What will the guide be used for? To lead users through a form? To invoke a dialog box? To create a computational subroutine? To specify an entry point guide in the Application List field used on a home page form?
   • What class of user will it guide? Advanced users? Or will you have to guide novice users step-by-step through a form?
   • What will the guide form look like? Will you have to create a simple form for novice users?
   • Will the guide be shared among multiple forms?
   • Will your guide function as an access point for applications?
2. Design the guide.
   • How many steps or dialog boxes will the guide require?
   • What will be the order of workflow in the guide and are there points where the guide should take different actions, depending on conditions?
   • If you are using dialog boxes, plan the layout of forms, fields, and buttons.
   • Will you require data validation?
   • What will your prompts say if it is a navigational or training guide?
3. Create the active links or filters that you want to use within the guide.
   • Use only one active link or filter for each step.
   • Identify what guide actions you will need to use to control the order of workflow. Actions specific to guides are Call Guide, Exit Guide, Goto Guide Label, and Wait. For information about these actions, see Using-buttons-and-menu-bar-items-to-execute-active-links.

   • Identify where you will need to enter Guide labels and keep track of any Goto Guide Label targets used.

     If you reuse or copy active links or filters for your guide that were designed for other applications, make sure they do not have any Execute On conditions and that the actions, associated forms, and other specifications are appropriate for use in the guide.

4. Create the guide.
   1. Set the appropriate specifications for the guide as described below.
   2. Add the appropriate active links or filters to the guide as described in Adding-workflow-to-the-guide.
   3. If you are using the Go to Guide Label active link action, add the labels needed for Go To targets.
   4. Specify the appropriate guide permissions.
   5. Specify the appropriate guide change history.
   6. Create or modify the help text for a guide.
      For more information about permissions, building and using change history, and creating help text, see Working-with-objects.
5. Debug your guide before sending it to your users.
   • Use active link logging to generate a list of active links that are executed and the order in which they are executed.
   • You can create a log file of active link activity that includes all of the active links in a guide. This option logs information about active link activity for each operation, including which active links executed and whether active link execution was successful.
   • Use filter logging to generate a list of filters that are executed and the order in which they are executed.
   • Provide visual cues as the guide executes, so users knows what actions to expect.
   • Make sure the entry point guide appears on the Application List field on your home page form and that the link starts the guide.
   • Create Message active link actions as temporary placeholders to understand how your guide works.

To define basic settings for active link guide or filter guide

1. From the All Objects list, open an existing active link guide or filter guide, or create a new one.
2. In the Associated Forms panel, click Add.
3. In the Form Selector dialog box, select the appropriate form, and then click OK.
   To locate a form quickly in the list, use the Filtering Options or the Locate field in the Form Selector dialog box. See To filter the contents in an object list.
   The form or forms that you associate with the guide determine which active links or filters you can include in the guide.
   You can associate a guide with more than one form. If so, the guide is considered shared, and special considerations apply. See Shared-workflow.
4. If you associated the guide with more than one form, select the correct primary form from the Primary Form list.
   The primary form is the reference form for the guide.
5. (Optional) In the Display panel, enter the Application List Label for the guide.
   Make the Application List Label descriptive and indicative of the guide's function. Application List Labels can be as many as 255 bytes.
   • For an active link guide that acts as an entry point, the Application List Label appears in the Application List on the home page form, and as the name of the entry point in the server object list in the web client.
     If you do not supply an Application List Label, the guide name is used as the guide label.
   • For filter guides and active link guides that are not entry points, the Application List Label appears only in Developer Studio, for example, in the Guide Selector dialog box when you create a Call Guide action.
6. (Optional) In the Description field, enter a description of the active link guide suitable for users. You can enter a maximum of 2000 bytes.
   • For filter guides and active link guides that are not entry points, the contents of the Description field appear only in Developer Studio, as with the Application List Label field.
7. (Optional, active links only) For active link guides that will be an entry point, open the Entry Point panel and enter values to define the entry point:
   • In the Application List Display Order field, enter a numerical value. This value determines the location of the guide in the Application List on the home page form.
   • In the Start Active Link field, select the starting active link for the guide. This active link can use different actions, but it should at least use the Open Window action.
   • Entering values in these two fields in the Entry Point panel has the effect of making an active link guide an entry point. Entering a value in one of these fields makes the other field required.
     For more information about using entry points in an application and about the home page, see Creating-and-managing-fields.
8. Assign the appropriate permissions for the guide. See Assigning-groups-or-roles-access-to-objects.
   For active link guides, you must assign Visible permission to the access control groups, roles, or users that are allowed to view and execute the active link guide. The same groups, roles, or users must also have permission to execute the active links contained in the active link guide. (Filter guides run filters, which execute on the server with administrator-level permissions, so you do not assign permissions to filter guides.)
9. Save the active link guide or filter guide, supplying a name for the guide.
   The guide name appears in the following locations:
   • In the server Object List in Developer Studio.
   • For active links that are entry points with no Application List Label defined, the guide name appears in the Application List on the home page and in the object list.
     Guide names must be unique on each AR System server. There is no enforced convention for specifying guide names, but it is helpful to make the name descriptive and indicative of the guide's function. Guide names can be up to 80 characters, including spaces. Names can include double-byte characters, but avoid using numbers at the beginning of the name.