Building Applications or Batch Programs that Include Group Build Functions

These topics discuss how to:

  • Implement PeopleCode API calls.

  • Implement PeopleSoft Application Engine API calls.

  • Develop client-specific workflow.

This topic discusses what a developer must do to use Group Build in the application that he or she is building. (We refer to this application as the client application.)

Note: Please read this entire topic before performing any steps.

To Implement PeopleCode API calls:

  1. (Optional) Set up a Group Build results table.

    Group Build provides a standard Group Results Table called GB_GRP_RES_TBL. This table contains the results of the groups that you build; its content is managed entirely by the Group Build application. This table provides a central place for storing Group Build results, so the results can be shared by all applications that use Group Build. Do not add, delete or modify rows in this table.

    If you want a table for your application where you can add, delete, or modify rows, you must perform this optional step. Your table will be taken into account for the construction and purge processes of the Group Build application.

    There are two ways to set up your own table:

    1. Log on to PeopleSoft Application Designer and clone the record GB_GRP_RES_TBL into MyClientModuleResultTable.

      This record becomes your client application result table.

    2. Create a new record (MyClientModuleResultTable) into which you insert (at least) the subrecord GB_GRP_RES_SBR (the minimal structure for a modified result table). The modified results table can contain more fields than the one that is defined in the subrecord. However, you can't use the standard query «GB_DEFAULT_QUERY». You must create your modified developer query in which the additional fields appear in the «field tab». For example, if your result table is defined as DEPTID, define your modified query as follows:

      – All fields from GB_QRY_LINK_VW.

      – All of your additional fields.

  2. (Optional) Add two fields on the client application record to store the group ID and group as of date. If you choose not to record this information, you can use a derived/work record (see step 3) or system variables (such as system date).

    In PeopleSoft Application Designer, add two fields to the client application record (MyClientModuleRecord):

    • The field GB_GROUP_ID for storing the Group ID.

      This field should prompt on GB_GROUP_TBL.

    • The field MyAsOfDate for storing the as of date of the group.

  3. In PeopleSoft Application Designer, create a derived/work record to store your group generation button.

    1. Create a new record (DERIVED_MyClientModule) or use an existing derived record.

    2. Create a new field: MyClientModule_GEN_BTN.

    3. To the DERIVED_MyClientModule record, add a new field: MyClientModule_GEN_BTN.

  4. In PeopleSoft Application Designer, Include the work page GB_API_WRK in the client application component.

    1. Open the component (MyClientModuleComponent) that contains the page (MyClientModulePage) from which you'll call the Group Build API.

    2. Insert the page named GB_API_WRK (the Group Build work page) into MyClientModuleComponent and mark it as hidden.

  5. (Optional) Using PeopleSoft Query, define the query that you might want to add to for refining your group - developer query definition.

    1. Insert the view GB_QRY_LINK_VW (required).

    2. Insert the record(s) that are needed for joins and criteria.

    3. Write your query according to the Group Build limitations.

      See Group Build Query Limitations for Developers

    4. Add all necessary prompts on the criteria tab.

      Prompt values are bound using the GB_BIND API call.

    5. Verify that your query is PUBLIC.

    6. Save your query as MyDeveloperQueryName.

  6. Add modified fields on the client application page.

    1. Add the MyClientModuleRecord.GB_GROUP_ID field to MyClientModulePage.

    2. Add the MyClientModuleRecord. MyAsOfDate field to MyClientModulePage.

    3. Add the DERIVED_MyClientModule.MyClientModule_GEN_BTN group generation button to MyClientModulePage.

  7. Add PeopleCode to implement calls to Group Build API.

    Warning! All calls to Group Build API must be done from level 0 of your client application page.

    1. Make calls to Group Build API in the FieldChange PeopleCode event.

    2. Set the PeopleCode Event Properties to Application Server.

    3. Select Application Server on the PeopleCode Event Properties page.

      See PeopleCode API Functions.

  8. Implement PeopleSoft Security to see if a group can be used in the component.

    1. GB_GROUP_ID field must be on the page, and the recordfield properties must be set to prompt table edit on Record GB_GROUP_SEC_VW.

    2. Add DERIVED_XXX.PNLGRPNAME and DERIVED_XXX.OPRID on level 0 of the page. The fields must be display-only and hidden.

PeopleCode API Functions

This list is a funclib (DERIVED_HR_GB.GB_API FieldFormula) for PeopleCode. Specifies which API group, query name for refinement, and results table to use.

  • Specifies which group, query name, results table to use.

    &ret_bool = GB_DECLARE(group_id, AsOfDate of the group, query_name, result_table_name)

    • The parameter group_id is required.

    • The parameter AsOfDate is required.

    • The parameter query_name specifies a developer query name for refinement. It is optional. The default query name is GB_DEFAULT_QUERY (view PS_GB_QRY_LINK_VW).

    • The parameter result_table_name is needed if the results table has been modified. It is optional. The default result table is PS_GB_GRP_RES_TBL. The result_table_name has to be complete; for example, « PS_MY_RESULT_TABLE ».

  • Binding values.

    &ret_bool = GB_BIND(prompt_code, value)

    • Enables you to bind values if prompts have been defined in the modified query developer. If you're using the standard query GB_DEFAULT_QUERY, then the only value to be bound is the refinement date: use the delivered API, GB_BIND_DATE.

    • The parameter prompt_code must be defined as a prompt in the developer query.

    • The parameter value is required.

  • Binding a date as refinement when you're using the standard query.

    &ret_bool = GB_BIND_DATE(value)

    • Use this function when you use the standard query GB_DEFAULT_QUERY. It enables you to bind a date (value) as a refinement.

    • The parameter value is optional and specifies a refinement date. The default is %date.

  • Generating and executing the SQL statement.

    &group_version_number = GB_EXEC(refresh_flag)

    • This API generates and executes the SQL statement.

    • It returns the version number of the generated group.

    • If the parameter refresh_flag is set to Y, the SQL statement is generated each time you call the function. If the refresh_flag is set to N, the function checks to see if a generated group exists and returns its version number. If the group doesn't exist, the parameter generates it. The refresh_flag is required.

  • Deleting the content of the result table.

    GB_DELETE()

  • Disabling/enabling the generic workflow and the specific workflow.

    GB_SET_JOB_WF(job_name)

    • Disables/enables the generic workflow and the specific workflow according to job_name value. Specifies the job (job_name) to be scheduled in place of the default job name (used for generic workflow), if specified.

    • The parameter job_name is optional.

    • If the job_name is specified, then the job that is named job_name must be defined in PeopleSoft Process Scheduler, as described in the workflow topic.

    • Providing a non-null job_name enables the corresponding workflow. Generic workflow is disabled.

    • Providing a null job_name as parameter enables the generic workflow (workflow by default).

    • On FieldChange PeopleCode event of DERIVED_MyClientModule.MyClientModule_GEN_BTN, add the following code according to one of the two scenarios described below.

Scenario 1

If you implement Group Build calls using the standard Group Result Table and query, the FieldChange PeopleCode for DERIVED_MyClientModule.MyClientModule_GEN_BTN looks like this: 

Declare Function GB_DECLARE PeopleCode DERIVED_HR_GB.GB_API FieldFormula;
Declare Function GB_BIND PeopleCode DERIVED_HR_GB.GB_API FieldFormula;
Declare Function GB_EXEC PeopleCode DERIVED_HR_GB.GB_API FieldFormula;
/* Use this instruction if you plan to use GB_GRP_RES_TBL */
GB_DECLARE (MyClientModuleRecord.GB_GROUP_ID, MyClientModuleRecord.MyAsOfDate, « », « ») ;
/* Bind all parameters for the default Query : The Effdt of JOB */
GB_BIND_DATE(Any Date ) ;
/* Execute the SQL and fill the group result table */
&MyVersion = GB_EXEC ( « Y » ) ;   /* <Y> Forces to rebuild the group even if one is available */
* The list of employees for the group is now available for your own usage */
/* The code presented above populates the Group Result table GB_GRP_RES_TBL */
/* You can now use this record to populate your scrolls or can be used as a join for a SQL Statement */
/* ADD YOUR CODE HERE  */
/* Clear the group result table only in the case you know the group will not be used anymore*/
[GB_DELETE() ;]

Scenario 2

If you implement Group Build calls using your own modified Group Result Table and query, the FieldChange PeopleCode for DERIVED_MyClientModule.MyClientModule_GEN_BTN looks like this: 

Declare Function GB_DECLARE PeopleCode DERIVED_HR_GB.GB_API FieldFormula;
Declare Function GB_BIND PeopleCode DERIVED_HR_GB.GB_API FieldFormula;
Declare Function GB_EXEC PeopleCode DERIVED_HR_GB.GB_API FieldFormula;
/* Give your result table name to GB_DECLARE  (STEP 1 must have been previously performed) and your Query Name if  you created one */
GB_DECLARE (MyClientModuleRecord.GB_GROUP_ID, MyClientModuleRecord. MyAsOfDate, « MyDeveloperQueryName », «MyClientModuleResultTable ») ;
/* Bind all parameters for MyDeveloperQueryName */
/* Each prompt in MyDeveloperQueryName must be binded */
GB_BIND (« :1 », MyClientModuleRecord.MyField1) ;
[…]
GB_BIND (« :n », MyClientModuleRecord.MyFieldn) ;
/* Or use local variable for binding */
GB_BIND(« :n », &MyLocalVarn) ;
/* Execute the SQL and fill the group result table */
&MyVersion = GB_EXEC ( « N » ) ;   /* <N> Don't rebuild the group if it is available */
/* Employee group is now available for your module */
/* This populates the group result table MyClientModuleResultTable  */
/* You can now use this record to populate your scrolls or work on this table… */
/* ADD YOUR CODE HERE  */
/* Clear the group result table only in the case you know the group will not be used anymore*/
[GB_DELETE() ;]

Group Build Query Limitations for Developers

Following are some limitations to the standard use of PeopleTools Query:

  • Developer queries need to be defined as PUBLIC queries.

  • You can't use unions.

  • You can't use aggregates.

  • You can't use Tree Option as an expression.

  • You must include the view GB_QRY_LINK_VW in the query.

  • Records that you add in QUERY must have at least one criterion.

  • Prompts can be used as expressions to bind variables.

This topic discusses what a developer has to do to use Group Build in the application that he or she is building, using PeopleSoft Application Engine. (We refer to this application as the client application.)

To implement PeopleSoft Application Engine API calls:

  1. In PeopleSoft Application Designer, create a Run Control page.

  2. Create a new Run Control record or use an existing one.

    In this record, add:

    • The parameters GB_GROUP_ID, GB_EFFDT, and GB_REFINE_DATE.

    • The field VERSIONGBQDM.

  3. In PeopleSoft Application Engine, create a new program .

    This program must contain:

    • A retrieval of parameters.

      Step01.SQL:
      %Select(AE_GBP002_AET.GB_GROUP_ID, AE_GBP002_AET.GB_EFFDT, AE_GBP002_AET.GB_REFINE_DATE)  SELECT GB_GROUP_ID  , GB_EFFDT  , GB_REFINE_DATE  FROM PS_RUN_CNTL_HR  WHERE OPRID = %Bind(OPRID)  AND RUN_CNTL_ID = %Bind(RUN_CNTL_ID)

    • A call to Group Build PeopleCode API.

      Step02.PeopleCode:
      Declare Function GB_DECLARE PeopleCode DERIVED_HR_GB.GB_API FieldFormula;
      Declare Function GB_BIND PeopleCode DERIVED_HR_GB.GB_API FieldFormula;
      Declare Function GB_RESET PeopleCode DERIVED_HR_GB.GB_API FieldFormula;
      Declare Function GB_BIND_DATE PeopleCode DERIVED_HR_GB.GB_API FieldFormula;
      Declare Function GB_SET_PANELGROUP PeopleCode DERIVED_HR_GB.GB_API FieldFormula;
      GB_SET_PANELGROUP("APPENGINE");   /* This is due to a tools issue and will disappear as soon as the TPRD is closed */
      GB_RESET();
      &RET = GB_DECLARE(AE_GBP002_AET.GB_GROUP_ID, AE_GBP002_AET.GB_EFFDT, "", "");
      &RET = GB_BIND_DATE(AE_GBP002_AET.GB_REFINE_DATE);
      AE_GB_API_AET.REFRESH_SW.Value = "N";   /* You can see that the REFRESH_FLAG is set to "N"  Equivalent to GB_EXEC("N"). As we can't call a section with direct parameters, we must use the cache record of the AE API to perform this operation */

    • A call to Group Build AE API GB_EXEC.

      Step02.Call Section:
      Call the section GB_API.GB_EXEC. You must not call GB_EXEC_LIB.GB_EXEC Directly. You will always use the GB_API AppEngine Lib.

    • Version number of the group.

      Step01.SQL:
      UPDATE PS_RUN_CNTL_HR  SET VERSIONGBQDM = %Bind(AE_GB_API_AET.VERSIONGBQDM)  WHERE OPRID = %Bind(OPRID)  AND RUN_CNTL_ID = %Bind(RUN_CNTL_ID)

      Note: Perform your own Application Engine processing using this group.

  4. Create reports, based on the group that you just created, by setting up a JOB.

    When the system launches the SQR, you get the GB_GROUP_ID VERSIONGBQDM (version of the group) from the Run Control record. This enables you to retrieve the group from the Group Results Table and print or perform processing on it.

Differences Between PeopleCode and Application Engine APIs

Question

Answer

What are the differences between a PeopleCode API and a PeopleSoft Application Engine API?

For building a group, there are not many differences between the two APIs.

  • In both APIs, you use the PeopleCode function GB_DECLARE, GB_BIND, or GB_BIND_DATE.

  • In the PeopleCode API, you call GB_EXEC("Y") with a REFRESH_FLAG ("Y" or "N") as parameter, and the function returns the VERSION of the group.

  • In the PeopleSoft Application Engine API, you call a section GB_API.GB_EXEC. The refresh flag is set before this call by updating AE_GB_API_AET.REFRESH_SW, and you retrieve the version of the group in the cache record AE_GB_API_AET.VERSIONGBQDM.

Why can't we use the PeopleCode API directly in a PeopleSoft Application Engine PeopleCode step?

There is a PeopleTools limitation:

The CallAppEngine() function is not intended to be inserted into an Application Engine PeopleCode step. If you need to call an Application Engine program from another Application Engine program, you must use the Call Section Action.

This topic provides the additional steps that must be performed for implementing workflow. This specific workflow is an enhancement to the generic workflow that is provided by default by the Group Build application. Workflow must be fully implemented by the client application developer. This topic discusses the main differences between the Group Build workflow and the standard way of implementing workflow.

Although the business process diagram looks like the Group Build generic workflow business process, you have to develop a business process for each client application to enhance the information that is provided by the Group Build generic workflow. The reasons for this are:

  • The worklist routing to enhance user information should branch the user directly to the calling-client application page.

  • The business event is triggered from the client application page.

The worklist record table has to contain key fields for accessing the client application page, so map those fields to the appropriate client application page fields (the workflow is triggered from the calling page).

The Message Agent is responsible for entering data on the client application page for triggering the specific workflow. The Database Agent executes a query that retrieves the values that are passed as Message Agent input fields. Therefore, the Database Agent query should retrieve the necessary key values, plus the condition for triggering the workflow.

You have to define a new client-specific table record (MySpecificWorkflowTable). This record stores all client application key fields, the group ID (GB_GROUP_ID) field, and the version (VERSIONGBQDM) field. Populate the MySpecificWorkflowTable after you call Group Build (to get the version number).

Summary

As a client application developer, you have to:

  1. Define a new table (MySpecificWorkflowTable) for storing the page key, group ID, and version number fields.

  2. Define a new worklist table record.

  3. Define a derived/work field that is responsible for triggering the workflow.

  4. Add this field to the client application page as a hidden field.

  5. Provide PeopleCode for storing page key values before calling Group Build.

  6. Define a Database Agent query for retrieving the key field values: group ID, version number, and user ID.

  7. Design the business process (activities, steps, business event, worklist routing, email routing, Database Agent, and Message Agent) and define the necessary attributes and field mappings.

  8. Define a new process for the modified Database Agent (MyDBAGProcess) in PeopleSoft Process Scheduler.

  9. Define a new job (MySpecificJobName) that serializes PeopleSoft Application Engine, calling the section GB_EXEC in Application Engine GB_API and the modified Database Agent process (MyDBAGProcess).

  10. Pass the new job name to Group Build as a parameter through a new API function, GB_SET_JOB_WF(MySpecificJobName), which passes the new job name to be scheduled, enables the specific workflow, and disables the generic workflow. The call to this function must be done before the call to GB_EXEC.

  11. Add PeopleCode to save the necessary information in MySpecificWorkflowTable (see the following procedure).

To add PeopleCode to save the information in MySpecificWorkflowTable:

  1. Design MySpecificWorkflowTable so that all the key fields that are necessary for accessing your client application page will be recorded.

    1. Add two key fields, GB_GROUP_ID and VERSIONGBQDM, to your record.

    2. Add a workflow flag, WF_FLAG.

  2. Design MySpecificWorkflowDerived/Work.

    1. Add two fields: GB_TRIGGER_WF (responsible for triggering the workflow) and OPRID (important for routings).

    2. Make the fields invisible.

  3. Define a worklist record, MyWorklistRecord, for routing to the calling client application page.

    BUSPROCNAME, ACTIVITYNAME, EVENTNAME, WORKLISTNAME, INSTANCEID, and TRANSACTIONID are standard, required fields for a worklist record.

    Add all of your page's key fields, plus the GB_GROUP_ID and VERSIONGBQDM fields.

  4. Define the Database Agent (DBAG) query.

    The DBAG query is responsible for calling the client application key field values: group ID, group version number, and user ID.

    1. In PeopleSoft Tree Manager, add MySpecificWorkflowTable to the HR ACCESS GROUP, as follows:

    2. Go to PeopleSoft Query.

    3. Join MySpecificWorkflowTable and GB_GENERICWF on group ID and version number to return specific key values: group ID, group version number, workflow triggering flag, and user ID.

    4. Include in your criteria prompts on group ID and version number.

    5. Save your query as a public database agent query named "_DBAG__MySpecificWorkflowQuery".

  5. Design the MySpecificBusinessProcess.

    1. In PeopleSoft Application Designer, define a business process.

      MySpecificBusinessProcess has two activities:

      MySpecificWorkflowModule

      MySpecificWorkflowModuleResult

      Each activity has only one step branching to the client application page:

    2. In the MySpecificWorkflowModule activity, add a business event, a worklist routing, an email routing, a database agent, and links.

    3. Define each item and its required attributes.

      The business event is triggered from the MySpecificWorkflowDerived/Work record.

    4. Add workflow PeopleCode, using the button Edit Business Rules and write the code as displayed, providing the condition for calling the TriggerBusinessEvent function. Write the correct parameters: business process, activity, and business event to trigger.

    5. On the Worklist Attributes page, select the record defined in step 4 as the worklist record. Specify the Business Process, its activity that works the worklist (MySpecificWorkflowModuleResult).

    6. On the Field Map page, specify the mapping between the worklist record fields and your client application page keys.

    7. For the OPRID field, select the role name Roleuser by Oprid Qry, binding the OPRID query variable to the MySpecificWorkflowDerived/Work.OPRID field.

    8. For the email routing, define the field map between your email fields (SUBJECT, NOTETEXT, TO, CC, and BCC) and your application fields.

    9. Define the Database Agent items:

      Define the target component on the Message Attributes page and provide the path to your client application component.

      In the Query Name field, enter the database agent query defined in Step 5.

      Define the mapping between the query selection fields (second column) and your client application page fields (last column).

  6. Go to PeopleSoft Process Scheduler and define MySpecificWorkflowDBAGProcess

    1. Add a new process of type Database Agent on the Process Definitions page.

    2. On the Process Definition Options page, override the parameters list in Append mode, specifying the following as parameters:

      E100 -T -L /A MySpecificWorkflowModule /MD MyDatabaseAgentName

      kbind1=:DERIVED_HR_GB.GB_GROUP_ID2 -kbind2=:DERIVED_HR_GB.VERSIONGBQDM

      /A stands for Activity Name

      /MD stands for Message Definition

      -kbind1 and −kbind2 are bind variables from the API work page.

  7. In PeopleSoft Process Scheduler, define MySpecificWorkflowJob.

    Add a new job serializing the Group Build Application Engine process (the one that calls GB_API.GB_EXEC) and MySpecificWorkflowDBAG database agent process.

  8. Add calls to Group Build API on your client application.

    On the FieldChange PeopleCode event of your Group Build calling button, use Group Build API as described at Step 7 in the first topics of this documentation. Don't forget to call the GB_SET_JOB_WF function to activate your specific workflow and disable the generic workflow.

  9. Add PeopleCode to store the necessary information in MySpecificWorkflowTable.