Implementing PeopleCode API Calls

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.