Developing Custom Action Buttons

The activity guide subbanner in fluid activity guides or the navigation frame of the classic WorkCenter provide default navigation buttons to allow a user to move to the next or previous action item. You can create additional navigation buttons to be displayed in these same locations—for example, to allow a user to manually mark an action item as complete or to cancel the activity guide instance altogether. custom action buttons are defined on the Pagelet Options page for a template or instance. Additionally, custom action buttons can be defined per action item on the Configure Related Data page—for example, to add a Submit button to the final step of a sequential activity guide.

Note:

For classic activity guides, Oracle recommends that you add no more than two additional custom action buttons.

Important:

In custom action buttons, do not attempt component buffer access, use think-time functions such as MessageBox, WinMessage, or others, or use system variables.

Reserved Method Names

Certain reserved method names are recognized for use with guided activity guides. For some reserved method names (for example, MarkComplete and SubmitAGProcess), you must implement custom PeopleCode to perform the designated operation. In other cases (for example, PTAI_NAV_SAVE and PTAI_NAV_AUTO_SAVE), specifying the reserved method name will invoke delivered functions subject to the implementation requirements.

Method Name Function How to Implement

ExitAGProcess

Use this method to render a custom Exit button to run PeopleCode (for example, to display a warning message) prior to exiting the activity guide.

Implement the ExitAGProcess method as custom PeopleCode. See PTAI_UTILITIES:Utilities for an example.

MarkComplete

Use this method to render a custom Mark Complete button to allow a user to manually mark an action item as complete.

Implement the MarkComplete method as custom PeopleCode. See PTAI_UTILITIES:Utilities for an example.

ReturnToQuestionnaire

Use this method to render a custom Return to Questionnaire button to delete the current activity guide instance and return the user to the questionnaire page using the default answers defined in the template properties.

Implement the ReturnToQuestionnaire method as custom PeopleCode. See PTAI_UTILITIES:Utilities for an example.

SubmitAGProcess

Use this method to render a custom Submit button that must be placed on the final step of sequential activity guides. When a user clicks this Submit button, two operations occur in this order:

  1. Data added and modified by the user is submitted and then committed to the database.

  2. Your custom SubmitAGProcess program is executed. This method must set the activity guide instance status to complete and then save the instance.

Implement the SubmitAGProcess method as custom PeopleCode. See PTAI_UTILITIES:Utilities for an example.

PTAI_NAV_AUTO_SAVE

Use this method to introduce auto-save functionality for the built-in Next and Previous buttons for non-sequential, guided fluid activity guides.

Note: Auto-save is enabled for sequential and single unit of work activity guides automatically.

No additional implementation is required.

PTAI_NAV_SAVE

For classic activity guides only, use this method to render a custom Save button to invoke the transaction page’s Save button to save the current action item.

  1. At the template level, define PTAI_NAV_SAVE as a configurable field on the Template Properties: Advanced Options page.

  2. For each action item that requires this save functionality, you must map the HTML field ID of the Save button on the page to the configurable field.

    Use your browser’s built-in web developer tools to determine the HTML field ID. For pages that display the standard PeopleTools Save button, the HTML field ID is #ICSave.

    Then, specify this field ID as the value of the PTAI_NAV_SAVE configurable field on the action item’s Configure Related Data page.

PTAI_NAV_SAVE_NEXT

Use this method to combine the save action into the Next button, which invokes the transaction page’s Save button to save the current action item and then display the next action item.

Note: Use this method in classic activity guides only.

  1. At the template level, define PTAI_NAV_SAVE_NEXT as a configurable field on the Template Properties: Advanced Options page.

  2. For each action item that requires this save functionality, you must map the HTML field ID of the Save button on the page to the configurable field.

    Use your browser’s built-in web developer tools to determine the HTML field ID. For pages that display the standard PeopleTools Save button, the HTML field ID is #ICSave.

    Then, specify this field ID as the value of the PTAI_NAV_SAVE_NEXT configurable field on the action item’s Configure Related Data page.

PTAI_NAV_SAVE_PREV

Use this method to combine the save action into the Previous button, which invokes the transaction page’s Save button to save the current action item and then display the previous action item.

Note: Use this method in classic activity guides only.

  1. At the template level, define PTAI_NAV_SAVE_PREV as a configurable field on the Template Properties: Advanced Options page.

  2. For each action item that requires this save functionality, you must map the HTML field ID of the Save button on the page to the configurable field.

    Use your browser’s built-in web developer tools to determine the HTML field ID. For pages that display the standard PeopleTools Save button, the HTML field ID is #ICSave.

    Then, specify this field ID as the value of the PTAI_NAV_SAVE_PREV configurable field on the action item’s Configure Related Data page.

PTAI_GRANT

Use this method to render a custom button that allows a user to grant contributor access to the current step to other users and roles who have contributor access to the instance. Once access has been granted in this manner, only an instance administrator can revoke the grant using the Manage Activity Guide Instances page.

Note: Use this method in fluid activity guides only.

Note: Do not configure the grant action for activity guides that do not support multiple users such as single unit of work and restartable activity guides. Also, the grant action does not make sense for self-service processes when all of the steps in the process are to be performed only by the one user.

Other than specifying the label for the button, no additional implementation is required.

Important: In the current release, if an application package and class has not been specified for another custom button, you must specify a placeholder application package and class in order to be able to save the configuration. However, you do not need to implement the PTAI_GRANT method in this class. Therefore, you can use PTAI_UTILITIES:Utilities as a placeholder.

PTAI_NOTIFY

Use this method to render a custom button that allows a user with contributor access to the instance to send ad hoc notifications to other users by user ID, role, or email address.

Note: Use this method in fluid activity guides only.

Other than specifying the label for the button, no additional implementation is required.

Important: In the current release, if an application package and class has not been specified for another custom button, you must specify a placeholder application package and class in order to be able to save the configuration. However, you do not need to implement the PTAI_NOTIFY method in this class. Therefore, you can use PTAI_UTILITIES:Utilities as a placeholder.

PTAI_OVERVIEW

Use this method to render a custom button that allows a user to view an overview of the activity guide steps along with their status.

Note: Use this method in fluid activity guides only.

Other than specifying the label for the button, no additional implementation is required.

Note: In the current release, if an application package and class has not been specified for another custom button, you must specify a placeholder application package and class in order to be able to save the configuration. However, you do not need to implement the PTAI_OVERVIEW method in this class. Because PTAI_UTILITIES:Utilities has a sample implementation, do not use it as a placeholder. Moreover, steps can be hidden from display in the process overview depending on business logic. See PTAI_UTILITIES:Utilities for an example how to do this.

Custom Exit Button

In the following example for a classic activity guide, the Exit button that invokes this custom method exits the activity guide and the WorkCenter and returns the user to his or her default homepage.

Note:

Exit is not a reserved method name and is different from ExitAGProcess, which is a reserved name.

Declare Function getHomepageURLForPortal PeopleCode FUNCLIB_PTBR.FUNCLIB FieldFormula;

method Exit
   /+ &list_id as String +/
   /+ Returns String +/
   Return getHomepageURLForPortal(%Portal);
end-method;

Related Topics