AppEngine Exer 2.pdf

of 18

Application Engine Exercise #2: Using a State Record to Accept User Input

In this exercise, you will modify the AppEngine program you created in Exercise #1 that increases the hourly pay rate for the employees in your department. The percentage used to increase the hourly pay rate will be accepted from the user. Table name: PS_GBUT_AETRN1_TBL Field name: AMT Web navigation: Tool Training > AE Training > AE Objects > Employees To open an existing project:

1. Click on File, Open or click on

2. In the Open Object window first choose an Object Type of Project, then either a. Type the entire name of the project in the Name box and click on Open,

or b. Type a partial name in the Name box and press ENTER to get a list to

choose from. Then either double-click the project you want to open or click on it once to highlight and click on Open.

of 18

Note: If you need to create a new project, please refer to Exercise #1. Now that you have opened your project, you are ready to modify the AppEngine program created in Exercise #1 to accept input from the user. In order to accept runtime parameters from the user a state record is required. The state record will be used to pass variable information from the process scheduler run control record and your AppEngine program as well as passing the variable information between steps in your AppEngine program. The first thing you should do is create the state record to be used in this exercise.

1. Click on File, New or click on .

2. Click on Record and then click OK

3. The key field (and the only key field) for a state record should be the field called

PROCESS_INSTANCE (do not use the field PROCESSINSTANCE). To insert the field into your record, on the menu bar click on Insert, then on Field

4. Type the entire name of the field in the Name box and click on Insert, or

Your project should be named GBUT_TRNTECHxx

of 18

type a partial name in the Name box and press ENTER to get a list to choose from. Then either double-click the field you want to insert or click on it once to highlight and click on Insert.

5. Now your record has one field in itPROCESS_INSTANCE.

of 18

You will also need a field on your state record in which to store the percentage value input by the user. You can create a new field for this purpose or use an existing field that is the correct type and size for your needs. Use the field GBUT_PCT_INCREASE, which already exists in the LSTRA database.

6. Insert the field GBUT_PCT_INCREASE into your state record. Follow the steps outlined in Steps 3 and 4 above.

7. Add the field COUNTER to your state record definition.

Your state record should now look like this:

8. Now you need to save your state record definition. Click on File, Save As or

Click on . Type a name for your state record (please follow established naming conventions explained in UNTSP Standards document found in the Shared Documents section of the EIS Developer Forum website), and then click on OK (or press ENTER). For this exercise use, GBUT_xx_AET. When prompted, use UNTUSER for the Space Name.

GBUT_00_AET

of 18

9. You must build the record since this will be a physical SQL table. With the

record definition open on the screen, click on Build, then on Current Object.

10. Verify that the boxes for Create Tables is checked and the radio button for Execute and build script is selected, then click on the button labeled Build.

11. Once the build process has completed, verify that you received no errors and no

warnings in the Build messages window at the bottom of the screen. It should look something like this:

Now you are ready to open the program you created in Exercise #1 so that it can be modified to accept the percent increase from the user (inserted into the state record by the Process Scheduler when the program is executed) rather than using a hard-coded value of 10%.

1. Click on File, Open or click on

2. In the Open Object window first choose an Object Type of App Engine Program, then either

a. Type the entire name of the project in the Name box and click on Open, or

b. Type a partial name in the Name box and press ENTER to get a list to choose from. Then either double-click the project you want to open or click on it once to highlight and click on Open.

Your program name should be GBUT_xx_EX1

of 18

3. You should now see the program you created in Exercise #1.

4. To see all the Sections, Steps, and Actions c. Click on the View (on the menu bar) and then click Expand All or d. Press CNTL-SHIFT-X or

e. Click on the Expand All button on the toolbar

of 18

Now the program should be displayed as shown:

5. Now save this AppEngine program with a new unique name. Click on File, Save As. Type a unique name for your program (please follow established naming conventions explained in UNTSP Standards document found in the Shared Documents section of the EIS Developer Forum website), and then click on OK (or press ENTER).

6. Since you cloned this program (GBUT_xx_EX2) from an existing program (GBUT_xx_EX1) that already had the Disable Restart box checked, you will not need to change the Program Properties at this time. For information on Disable Restart, please refer to Exercise #1.

7. You need to make three changes to the AppEngine program you just cloned.

a. Modify the SQL to accept the percentage used from the state record.

Save As using the program name GBUT_xx_EX2.

of 18

b. Change the Log Message used so that the message will contain the percentage accepted from the user.

c. Link the program to the new state record you have created.

8. Double-click in the area to the left of the SQL Action to open the SQL Editor.

9. The SQL currently looks something like this:

UPDATE PS_GBUT_AETRN1_TBL SET AMT = AMT + (AMT * 10/100)

WHERE DEPARTMENT = 'TRNTECHxx'

This command will increase hourly pay rate (AMT) by 10% for your department.

10. To modify the SQL to use the percent increase entered by the user, change the code highlighted in bold above so that the SQL looks something like this:

UPDATE PS_GBUT_AETRN1_TBL

SET AMT = AMT + (AMT * (%Bind(GBUT_PCT_INCREASE)/100)) WHERE DEPARTMENT = 'TRNTECHxx'

11. Click on to check the syntax of the SQL statement. Important note this will not validate that your SQL is correct (i.e., correct table name, correct field names, etc). It will basically reformat your SQL the way it wants it to look. Misspelling names or misplaced commas or parentheses will cause runtime errors.

Double-click in this area to open the SQL Editor

of 18

12. Close the SQL editor window.

13. Now change the Log Message that will be written out when the program successfully completes. Use Message Set 20101, Number 2. This message expects two parameters to be passed from the AppEngine program so enter the following in the Parameters: box:

%AEProgram, %Bind(GBUT_PCT_INCREASE) This will pass the name of the AppEngine program (%AEProgram is a system variable) as the first parameter of the message and the value in GBUT_PCT_INCREASE in the second parameter of the message.

14. Save your program again.

15. The last modification necessary is to link the state record you created to the AppEngine program. This is done in the Program Properties.

Open the AppEngine Program Properties window:

a. Click on or b. Click on File, Object properties or c. Press ALT-ENTER on your keyboard

16. Click on the State Records tab. In the box labeled Qualify Search, you can

type a partial name or the full name of your state record and click on the button labeled Get List. DO NOT PRESS ENTERthat will close the Program Properties window.

17. Click once on your state record to highlight it and click on the button labeled Add. You will now see your state record listed in the Selected window on the right. It is automatically selected as the default state record because it is the only one you are using. If you were using more than one state record with your AppEngine program, you would continue to add then using the same process just described.

During batch processing (as opposed to online invocation using CallAppEngine in PeopleCode), Application Engine automatically performs all State Record UPDATEs. When a program starts, it INSERTS a row into the State Record that corresponds to the Process Instance assigned to that program run. Application Engine updates the record whenever a COMMIT occurs. When Restart is enabled and a commit occurs, all State Records that have been updated in memory will be written to the database, except for derived State Records, which are instead initialized. Then, after the program completes successfully, Application Engine deletes the corresponding row in the State Record. There is only one row in the State Record for each Process Instance, or program. Multiple programs can use the same State Record, and each program has it's own row based on the unique Process Instance key.

of 18

To set values in the State Record, you use the %SELECT construct in a SQL statement or write PeopleCode that references the State Field with the standard "record.field" notation. To reference fields in the State Record you use the %BIND construct.

Now, you are almost ready to test your AppEngine program! In order to run an AppEngine program, you must first create a custom Run Control Page that will accept input from the user and a Component to contain the page, add the Component to a Menu, and set Security for the Component. Your custom Run Control Page will require a custom Run Control Records. You can clone the generic Run Control Record delivered from PeopleSoft as a starting point.

1. Open the Record PRCSRUNCNTL by either

a. Click on File, Open or by clicking on The record will look like this:

The fields OPRID and RUN_CNTL_ID are the record key fields. The LANGUAGE_CD and LANGUAGE_OPTION fields are used in global development projects and are not necessary in our application.

2. First, save this record with a new, unique name. Click on File, Save As. Type a unique name for your program (please follow established naming conventions

of 18

explained in UNTSP Standards document found in the Shared Documents section of the EIS Developer Forum website), and then click on OK (or press ENTER).

3. When prompted with the question Do you wish to also save a copy of the PeopleCode associated with PRCSRUNCNTL.ENG?, click on Yes.

4. Since we have no need for the LANGUAGE_CD and LANGUAGE_OPTION fields, delete those fields. One method for deleting the fields is to right-click on the field and then click on Delete. Once the two fields have been deleted, save your record again.

5. Now you need to add the field for which you will be accepting a parameter from

the user. This field is GBUT_PCT_INCREASE. Add this field to the record as described previously in this document (see hyperlink Inserting a Field into a Record).

6. Save your custom run control record again. Then build the SQL table as

described above (see hyperlink Building a Record). Likewise, even though you will need to modify it to accept additional parameters and to use the custom run control record you just created, you can still clone the generic Run Control Page delivered from PeopleSoft as a starting point.

7. Open the Page PRCSRUNCNTL by either

a. Click on File, Open or by clicking on

Save As using GBUT_xx_RNCTL

of 18

The Page will look like this:

8. The first thing you should do is save the page with a unique name. Click on File, Save As to save the Page under a different name (please follow established naming conventions explained in UNTSP Standards document found in the Shared Documents section of the EIS Developer Forum website).

9. When prompted with the question Do you wish to also save a copy of the PeopleCode associated with PRCSRUNCNTL.ENG?, click on Yes.

Save As using page name of GBUT_xx_RNCTL

of 18

10. Next, you need to add the custom field to the page. The easiest way to accomplish that is to double-click on GB_xx_RNCTL from the project workspace window so that you can see the individual fields on the record. Then drag-and-drop GBUT_PCT_INCREASE on to the run control page.

11. Save your page again. To create a Component for your new custom Run Control Page:

1. Click on File, New or click on

2. Click on Component, then click on OK

of 18

3. Expand the list of Pages in your project by clicking on the plus sign next to Pages in the Project workspace.

4. Drag and drop the custom Run Control Page you created onto the Component.

5. Before the Component can be saved, a search record must be specified. Click on

to open the Properties window and click on the Use tab. Since you have created a custom run control record, you should select it (GBUT_xx_RNCTL) as the search record, and then click on OK.

6. Click on File, Save or click on .

7. Type a name for the Component (please follow established naming conventions explained in UNTSP Standards document found in the Shared Documents section of the EIS Developer Forum website) and click on OK. For this exercise, use the name GBUT_xx_EX2. The instructor will add your component to the menu and grant you security when youve told them that you are ready.

Drag and drop in the Object workspace

of 18

One more important thing must be done before you can test your program. When you use a custom run control page, the Process Scheduler will NOT automatically populate your state record with the value input by the user. You must add the step to do that to your AppEngine program.

1. Insert a Step/Action before the Step01. The new Step will automatically be numbered Step03, but the numbering does NOT imply execution order. The steps will execute in the order they are shown on the screen. So that the order will make more sense, rename the steps so that they reflect the action being performed in the Step. Your program should look something like this:

2. The new SQL Action you inserted should contain the following SQL: %Select(GBUT_PCT_INCREASE) SELECT GBUT_PCT_INCREASE FROM PS_GBUT_00_RNCTL

WHERE OPRID = %OperatorId AND RUN_CNTL_ID = %RunControl

The first command (%Select (GBUT_PCT_INCREASE) populates your state record with the value retrieved in the SELECT statement following it. The second line (the SELECT command) retrieves the value of GBUT_PCT_INCREASE from your custom run control record.

3. Save your AppEngine program again.

of 18

The last step before you can run the AppEngine program youve created is to create a Process Definition for the PeopleSoft Process Scheduler. This step must be completed whether you are running the AppEngine program two-tier, three-tier, or n-tier. To create a Process Definition:

1. On the web, navigate to PeopleTools > Process Scheduler Manager > Use > Process Definitions

2. Click on the hyperlink Add a New Value

3. Click on the lookup icon and then click on Lookup 4. Click on the hyperlink Application Engine 5. Type in the Process Name This must match your AppEngine program

name! 6. Click on Add 7. Click on the Process Definition Options tab 8. In the Component section of the form, click on the Lookup icon and select your

Component (this will be the Component that contains your Run Control Page) 9. In the Process Groups section of the form, click on the Lookup icon and select the

permission list used with this AppEngine program (in this exercise use ALLPANLS)

Click on Save Believe it or not, you are finally ready to run your AppEngine program! First, check the course contact hours on a few courses in the subject area the program is set to modify (in this exercise, the SQL references the subject area ACCT). This can be accomplished either by accessing the records through the web navigation listed at the top of this document or by writing a simple query through Query Manager. To execute your AppEngine program via the web:

1. Navigate to the Menu Item you added Tools Training > AE Training > TRNTECHxx > Input Pay Rate Increase. The Run Control Search Page will be displayed.

2. If you have an existing Run Control ID you want to use, you can type the name (or partial name) and click on Find. If you want to add a new one, click on the hyperlink Add a New Value then type a value for the Run Control ID and click on Add. This can be any value you wishit does not need to match the AppEngine program name and can be reused.

3. When the Run Control Page is displayed, click on Run.

of 18

Then click here to run AE program

Type in the percent to increase course contact hours by here

of 18

4. A page containing a list of all Process Definitions linked to this Component (via Security) is displayed. Since the Process Definition name must match your AppEngine program name, this provides the link that PeopleSoft will need to know which program to run. Click on OK to submit the Process Scheduler Request.

5. The display will return to the Run Control Page and display your Process

Instance. You can now click on the hyperlink Process Monitor to view the progress of your program execution. For more information on the Process Monitor, please see Exercise #1.

6. Verify that the message written to the message log contains the value you input for GBUT_PCT_INCREASE.

7. Lastly, you should verify that your program did what it was supposed to by

checking that the hourly pay rates of the employees in your department increased by the percentage you input.

Exercise #2: Using a State Record to Accept User Input

AppEngine Exer 2.pdf

Documents

Transcript of AppEngine Exer 2.pdf