Building Applications or Batch Programs that Include Group Build Functions
This appendix discusses how to:
Build applications or batch programs that include group build functions.
Work with group versions.
Building Applications or Batch Programs that Include Group Build Functions
This section discusses how to:
Implement PeopleCode API calls.
Implement PeopleSoft Application Engine API calls.
Develop client-specific workflow.
Implementing PeopleCode API Calls
This section 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 section before performing any steps.
To Implement PeopleCode API calls:
(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:
Log on to PeopleSoft Application Designer and clone the record GB_GRP_RES_TBL into MyClientModuleResultTable.
This record becomes your client application result table.
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.
(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.
In PeopleSoft Application Designer, create a derived/work record to store your group generation button.
Create a new record (DERIVED_MyClientModule) or use an existing derived record.
Create a new field: MyClientModule_GEN_BTN.
To the DERIVED_MyClientModule record, add a new field: MyClientModule_GEN_BTN.
In PeopleSoft Application Designer, Include the work page GB_API_WRK in the client application component.
Open the component (MyClientModuleComponent) that contains the page (MyClientModulePage) from which you'll call the Group Build API.
Insert the page named GB_API_WRK (the Group Build work page) into MyClientModuleComponent and mark it as hidden.
(Optional) Using PeopleSoft Query, define the query that you might want to add to for refining your group - developer query definition.
Insert the view GB_QRY_LINK_VW (required).
Insert the record(s) that are needed for joins and criteria.
Write your query according to the Group Build limitations.
See Group Build Query Limitations for Developers
Add all necessary prompts on the criteria tab.
Prompt values are bound using the GB_BIND API call.
Verify that your query is PUBLIC.
Save your query as MyDeveloperQueryName.
Add modified fields on the client application page.
Add the MyClientModuleRecord.GB_GROUP_ID field to MyClientModulePage.
Add the MyClientModuleRecord. MyAsOfDate field to MyClientModulePage.
Add the DERIVED_MyClientModule.MyClientModule_GEN_BTN group generation button to MyClientModulePage.
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.
Make calls to Group Build API in the FieldChange PeopleCode event.
Set the PeopleCode Event Properties to Application Server.
Select Application Server on the PeopleCode Event Properties page.
See PeopleCode API Functions.
Implement PeopleSoft Security to see if a group can be used in the component.
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.
Add DERIVED_XXX.PNLGRPNAME and DERIVED_XXX.OPRID on level 0 of the page. The fields must be display-only and hidden.
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 section.
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.
Implementing PeopleSoft Application Engine API Calls
This section 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:
In PeopleSoft Application Designer, create a Run Control page.
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.
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.
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.
|
|
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. |
Developing Client-Specific Workflow
This section 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 section 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:
Define a new table (MySpecificWorkflowTable) for storing the page key, group ID, and version number fields.
Define a new worklist table record.
Define a derived/work field that is responsible for triggering the workflow.
Add this field to the client application page as a hidden field.
Provide PeopleCode for storing page key values before calling Group Build.
Define a Database Agent query for retrieving the key field values: group ID, version number, and user ID.
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.
Define a new process for the modified Database Agent (MyDBAGProcess) in PeopleSoft Process Scheduler.
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).
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.
Add PeopleCode to save the necessary information in MySpecificWorkflowTable (see the following procedure).
To add PeopleCode to save the information in MySpecificWorkflowTable:
Design MySpecificWorkflowTable so that all the key fields that are necessary for accessing your client application page will be recorded.
Add two key fields, GB_GROUP_ID and VERSIONGBQDM, to your record.
Add a workflow flag, WF_FLAG.
Design MySpecificWorkflowDerived/Work.
Add two fields: GB_TRIGGER_WF (responsible for triggering the workflow) and OPRID (important for routings).
Make the fields invisible.
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.
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.
In PeopleSoft Tree Manager, add MySpecificWorkflowTable to the HR ACCESS GROUP, as follows:
Go to PeopleSoft Query.
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.
Include in your criteria prompts on group ID and version number.
Save your query as a public database agent query named "_DBAG__MySpecificWorkflowQuery".
Design the MySpecificBusinessProcess.
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:
In the MySpecificWorkflowModule activity, add a business event, a worklist routing, an email routing, a database agent, and links.
Define each item and its required attributes.
The business event is triggered from the MySpecificWorkflowDerived/Work record.
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.
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).
On the Field Map page, specify the mapping between the worklist record fields and your client application page keys.
For the OPRID field, select the role name Roleuser by Oprid Qry, binding the OPRID query variable to the MySpecificWorkflowDerived/Work.OPRID field.
For the email routing, define the field map between your email fields (SUBJECT, NOTETEXT, TO, CC, and BCC) and your application fields.
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).
Go to PeopleSoft Process Scheduler and define MySpecificWorkflowDBAGProcess
Add a new process of type Database Agent on the Process Definitions page.
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.
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.
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 section of this documentation. Don't forget to call the GB_SET_JOB_WF function to activate your specific workflow and disable the generic workflow.
Add PeopleCode to store the necessary information in MySpecificWorkflowTable.
Working with Group Versions
This section provides an overview of version numbers and discusses how to work with versions (for developers).
Understanding Version Numbers Each time you build a group, the system generates a version number and stores it in the Group Result Table. The system creates a new version number and updates the result table if any of the following have changed since the last time you executed the group:
The group definition.
The query definition.
Any parameters that you used to generate the group; for example, if you used effective-dated job data.
Working with Versions (for Developers)
Before reading this section, see "Building Applications or Batch Programs That Include Group Build Functions".
You can implement Group Build in an application by:
Using the default developer query.
The default developer query works with the default Group Result Table.
Creating your own query.
If you use your own query, you can define more parameters and/or more fields in a personal Group Results Table.
However, you can use your own Group Results Table with the default developer query or use the default Group Results Table with your own query, as long as the fields selected by the query match the default Group Results Table structure.
This means that the system regenerates the group and changes the version number if either of the following changed since the last time you executed this group:
The query definition that was added by the developer.
The Group Results Table.
Note. You can bypass the versioning mechanism by calling GB_EXEC("Y"). Then the group is generated each time it is called.
Note. When using Developer Query or User Query, keep in
mind that GB_QRY_LINK_VIEW is based on the JOB record. When Group Build generates
the SQL, the system replaces all references to GB_QRY_LINK_VIEW with JOB.
If, after this is done, the left REC.FIELD is the same as the right REC.FIELD,
Group Build will not process the line in the SQL generation.
For example, if you have the criteria GB_QRY_LINK_VIEW.EFFDT <= JOB.EFFDT
in Query, Group Build will replace it with JOB.EFFDT <= JOB.EFFDT. The
system will then remove the line because the left REC.FIELD is the same as
the right REC.FIELD. As a result, the Query count may differ from the one
returned by Group Build.