ExcelToCI Troubleshooting Guide

Contents

Introduction Tool Basics Handling Multiple Child Collection Rows Testing/Troubleshooting

2 3 7 14

1

IntroductionThe ExcelToCI tool was introduced in PeopleTools (PT) 8.41 and has been changing ever since. The PT 8.41 8.43 versions of it are not as robust and do not offer as much functionality or features as in PT 8.44 and later. For example, effective dated processing is very limited prior to PT 8.44. In PT 8.44 the tool and the code (both VBA and Peoplecode) were redesigned. The purpose of this document is to provide basic information about ExcelToCI and assistance with troubleshooting problems when using ExcelToCI. Although there are no prerequisites to using ExcelToCI it is very helpful to have an understanding of Component Interface (CI) technology. For additional information on CIs and ExcelToCI see PeopleTools Component Interface PeopleBook. Note that unlike prior releases, in PT 8.44 the ExcelToCI documentation is part of the Component Interface PeopleBook. Also, the screenshots in this document will be from PT 8.44 and 8.45. Some things to remember: 1. Not all CIs are suitable for ExcelToCI. 2. The SOAPTOCI Peoplecode sets the CI properties in the same order in which they appear in Application Designer. This will be a problem in cases where properties need to be set out of sequence in order for Peoplecode validations to work correctly. 3. Try to avoid using large complex CIs. However, if you elect to use them, send them in smaller chunks to avoid running into problems such as timeouts, and to improve the application server throughput. 4. Ensure that you use a copy of the ExcelToCI workbook found in \excel for the PeopleTools release youre on. Also, make sure you dont open multiple Excel workbooks at the same time, either multiple ExcelToCI workbooks or a combination of ExcelToCI workbooks and other Excel workbooks to avoid seeing strange behavior.NOTE: The following sections cover some of the available topics, not everything. See the ExcelToCI documentation for additional information (available in PeopleBooks in PT 8.44 and later - Enterprise PeopleTools 8.45 PeopleBook: PeopleSoft Component Interfaces > Using the Excel to Component Interface Utility)

2

Tool BasicsConnection Page

Web Server machine name: Provide the web server machine name. If you created auth token domain, then include it in the name Protoccol: Default is http. If you want to use https, youll need to make sure the SSL certificates are properly installed, including any required client certificates. One way of testing whether SSL is properly installed is to open a browser and try logging into PeopleSoft using the https port. If the certificates are invalid, you will usually get a pop up message indicating possible problems with the certificates. However, if you clicked Ok to continue in spite of the questionable certificates, you wont see this popup on subsequent attempts to log into PeopleSoft. HTTP/HTTPS Port: Provide the web servers port number. The default HTTP port is 80 Portal: The name of the portal you are using. EMPLOYEE is the default portal shipped with PeopleSoft. PeopleSoft Site Name: The PeopleSoft site name that you entered when you installed the PeopleSoft Internet Architecture. The default is ps. You can determine the site name from your PIA browser URL, as it is the second field after the port number in the URL. In sample below it is E880G70P. Also remember that this field is case sensitive. 3

http://gsplas104.peoplesoft.com:8003/psp/E880G70P/EMPLOYEE/HRMS/h/? tab=DEFAULT

Node: The PeopleSoft default local node name. The default is PT_LOCAL. To determine the default local node, log into PIA and navigate to PeopleTools > Integration Broker > Node Definitions. Then press the search button without providing any values. The default local node will have a 1 in the Local Node column and a Y in the Default Local Node column. Language Code: The code for the language that the data is submitted to the database in and the template is created in. If no language code is specified, the base language is used. Chunking Factor: The number of rows of data to be transmitted to the database at one time. The default is 40. Note that if the CIs being used are large and or have a lot of Peoplecode a smaller value will probably result in better throughput by the application server. Testing will help determine a suitable value. Error Threshold: The total number of errors that are permitted before submission to the database ceases. When the error threshold is exceeded, an error message appears and submission to the database stops. You should specify a valid number instead of leaving it blank. Action: The value for the Action field is populated by the system when the component interface is retrieved from the database. However, you can change the populated value by selecting it from the Action drop-down list. The types of actions available are based on the structure of the component interface. The different actions are: Create: if the component interface has create keys. Use this mode when new keys are being added at level 0. Update: if the component interface does not have create keys. Use this mode if you are adding new children to an existing parent (e.g. inserting new rows into existing collections). UpdateData: requires you to select this option from the drop-down list. This mode is used to update specific non-key values that already exist but need to be updated. The system uses the keys to locate the row, and when a match is found, the row is updated with new data. If a key match is not found by the system, it displays an error message indicating which collection was missing a key match.

4

Template Page

New Template: Use this button to download and create a new template based on a component interface. Select Input Cell: Use this button to select fields to included on the Input page. The selected cells will have a pink background (as shown above). Include For Submission: Use this button to include a single property to be included on the Staging and Submission sheet. Properties that use default values from the template must be included for submission. Cells that are included for submission generally are properties that contain default values or properties that you would like to see in the structure of the Staging and Submission sheet. Properties that are included for submission are highlighted in blue. Determine which fields you want to supply. Then enter the value into each of these fields on the Template page. These properties and values will show up on the Staging & Submission page, not the Data Input page.

5

Insert New Child: Use this button to Copy the selected row to be inserted as a new child. This creates multiple occurrences of the same record type. For example, if the selected row has a template identifier of 100, a new row is inserted that also has an identifier of 100 and is an exact duplicate of the selected row. If you want to upload multiple collection rows, see the next section, Handling Multiple Child Collection Rows.Note. Use Insert New Child when multiple children must be submitted under the same parent record. Multiple children should not be created at identifier 000.

6

Handling Multiple Child Collection RowsSimple scenarioThis is the case where the multiple row collection does not have any children, so you dont need to maintain a hierarchy. For this case you can simply use the Insert New Child button as shown below. The example below uses the USER_PROFILE CI. The Roles collection is a Level 1 collection, and RouteControls is the Level 2 child collection of Roles. Note: This is simply used for illustration purposes. A. Before inserting second L2 collection row

7

B. After inserting second L2 collection row

C. Data Input page (note that both L2 rows are flattened)

8

D. Staging & Submission page (note the 2 L2 rows, hierarchy is restored)

Complex scenarioUsing the above example, suppose we need to be able to have multiple L1 (Roles) and L2 (RouteControls) collections. In this case well just illustrate inserting two L1 and L2 rows. You will need to use the same technique for additional rows up to the maximum number of rows you expect to upload. When uploading fill in the data for the number of rows from the left side, leaving any blank rows to the right on the Data Input page.

9

A. Template page 1. Right click on column 1 of the highest-level cell (in this case it is the L1 row), and select Insert. Repeat this for the maximum number of rows you intend to upload (for this example were going to use three L1 rows so we need to insert a total of 6 rows).

10

2. Copy and paste the 300, and two 310 row contents into the 6 blank rows above as shown below. This will allow us to insert up to three L1 collection rows (with up to two L2 child rows for each L1 row)

3. Press the New Data Input button to create a new Data Input page.

11

B. Data Input page: Note that the hierarchy is flattened and only two L1 rows have data. After entering the data press the Stage Data for submission button.

12

C. Staging & Submission page: Note that the third L1 row and its children are empty. When the data is uploaded the blank row will not be submitted.

13

Testing/TroubleshootingIn terms of testing you should first test the CIs underlying component online to ensure that it works properly. Then test the CI using the CI Tester as described in section A below before testing from ExcelToCI. Its a good idea to use this testing sequence, especially when developing custom CIs (CIs built from custom or delivered components).

A. CI Tester1. Open Application Designer in 3-tier (that is through the application servers WSL port (see screenshots of Configuration Manager below).

14

2. Once in Application Designer open the CI to be tested. 3. Open the CI Tester (right click on the CI and select Test Component Interface or select Test Component Interface from the Tools menu. See the Component Interface PeopleTools PeopleBooks for additional information on using the CI Tester.

15

4. Test using the same scenario as from Excel (Create, Update, or UpdateData). i. Enter the values for the properties in the sequence in which the CI properties appear. While doing so pay attention the behavior (for example a value that was accepted by the system (no edit error) being blanked after some subsequent properties values are entered). ii. iii. For the Create Action enter the create keys, press the Create New button and then enter the other properties values. For Update, enter the get key values, press the Get Existing button, and then navigate to collection(s) into which youre inserting new row(s). Then right click on the collection (cube shaped) icon and select the InsertItem() method and supply an index of 1. Then enter the correct values for the new row.

16

iv.

For UpdateData enter the get key values, press the Get Existing button, and then navigate to the properties being modified and edit the value. Once youve peformed ii, iii, or iv above, select the topmost line in CI Tester (with the CI icon), right click and select Save. A return value of 1 indicates success, while a value of 0 indicates that the changes were not successful. If 0 was returned youll see error messages at the bottom of the tester utility. Use # 5 below to get a SQL and PeopleCode trace of the execution path. Use # 6 below to step through the underlying PeopleCode.

v.

vi.

5. SQL/PeopleCode tracing - Test with SQL and PeopleCode tracing enabled on the application server to get a better understanding of the execution path. I use tracing values of 127 (SQL) and 3596 (PeopleCode). To enable tracing do the following. i. ii. Open the psappsrv.cfg file. Locate the following bitfield settings and set them to the desired values (the values I use are shown below). TraceSql=127 TracePC=3596 iii. iv. Save the psappsrv.cfg file. Restart the application server. Note: if you have the flag shown below set to Y (as shown below), you dont need to restart the application server each time you want to enable/disable tracing. You simply need to make the bitfield changes and save the psappsrv.cfg file, and the application server will accept the changes while its running. Also, if this flag is set to Y, youll have better control over what is traced and avoid a slow starting application server. Youll be able to minimize the amount of tracing and avoid generating unnecessary tracing information, and youll avoid having to look through irrelevant trace information. When using CI Tester for example, first open the CI Tester in application designer, and then set the above trace bitfield settings to enable tracing. Allow Dynamic Changes=Y 6. PeopleCode debugger - Test with the PeopleCode debugger if you want to step through the underlying PeopleCode. For this do the following.

17

i.

Shut down the application server. Reconfigure the domain so that a PeopleCode debugger application server process is started. Then restart the application server. Open application designer in 3-tier thorugh the same application server. Open the CI to be tested. Select Debug > Enter Debug Mode from the menu. Then select Break at start from the Debug menu selection. Open the CI Tester and begin testing. The debugger will stop at the first segment of Peoplecode that fires, and you can step through it to follow the execution path.

ii. iii. iv. v.

B. ExcelToCI1. ExcelToCI and SOAPTOCI logs Generating/reviewing these two logs for a transaction is sometimes sufficient to find the source of the problem. When submitting the data check the Generate Log checkbox as shown below.

The Generate Log selection causes the following two log files to be created. Note that a new log file is create each time you submit data. i. SOAPTOCIxxx.log By default this log is created in the app server's "files" directory (below the app server domain). The xxx is the timestamp appended to the file name. This log shows the PeopleCode execution path in the SOAPTOCI application package, and it can help you quickly determine the cause of the behavior youre seeing. ExcelToCIxxx.log By default this log is created in users Temp directory. The xxx is the timestamp appended to the file name. To determine the location where your Temp directory is mapped to do the 18

ii.

following. On the client machines desktop right-click on the My Computer icon and select Properties. Then select the Advanced tab and click on Environment Variables. Locate the Temp (or tmp) variable mappings (it may be C:\Temp or some other location). This is normally where the ExcelToCIxxx log is placed. This log simply contains the SOAP format message containing the Excel data, and is useful in verifying that the uploaded data is the same as in the Excel spreadsheet. 2. SQL/PeopleCode tracing After submitting the data locate and review the SOAPTOCI log. If the log does not provide sufficient detail to narrrow down the source of the problem, enable SQL and PeopleCode tracing on the application server and send another transaction from Excel with the Generate Log checkbox checked. 3. Comparing ExcelToCI to CI Tester results If the results from ExcelToCI are different from those using CI Tester, test using CI Tester (in 3-tier) using the same values as from Excel with PeopleCode and SQL tracing enabled on the application server. Save the trace file and then run another transaction using ExcelToCI (with PeopleCode and SQL tracing enabled on the application server). Save the second trace file. Compare the execution path and values in the two trace files. 4. Debug from VBA - In some cases (for example, where values are not being correctly handled in Excel, or other Excel related processing), you can step through the VBA code to try and pin point the source of the problem. To step through the VB code do the following: i. From Excel, press Alt-F11 to open the VB Editor. ii. Locate an appropriate location/line of code for the Breakpoint, and press F9 to enble the Breakpoint (press F9 to disable it as well). Save the setting in VB. iii. Go back to Excel, and perform the operation (such as submit the data) to hit the VB Breakpoint you set above. Then step through the VB code using the appropriate debugger functions (such as Step Into, Step Over, etc.).

C. Additional information/resources1. Uploading large volumes of data using complex CIs. a. ExcelToCI was not designed for batch/large volume processing

19

b. You may see strange error messages when using ExcelToCI to upload large volumes using large, complex CIs. Also, the errors may not occur all the time. For example, you may see messages in sequence such as The response text is not valid XML. Login Data cleared, Error occurred in routine sendSOAPRequest_SubmitToDB The parameter is incorrect, and The XML string contains invalid characters. One of the reasons for the errors is that the application server is handling multiple long running transactions, resulting in timeouts by the web server. c. Suggestions: i. Avoid using large complex CIs. Build and use streamlined (CIs that are not large, complex, and do not have a lot of Peoplecode in the underlying layers. ii. Use a smaller Chunking Factor (default is 40). You can drop the value to 1, and then increase it until you find a reasonable value that works. Also remember that the error probably wont occur all the time, and will depend on different factors such as the amount of load on the system at processing time. So, you dont want to use an aggressive (large) value. Using a smaller value means more data uploads from the client. But it also means that uploads should be more evenly distributed among the application server instance, improve application server throughput, and make web server timeouts less likely. 2. Search the Solutions available on Customer Connection. Typically ExcelToCI solutions have ExcelToCI in the summary. 3. Open a case with the PeopleSoft GSC (Global Support Center).

20