Using the Excel to Component Interface Utility

Version 2: May 13, 2003 Note. This utility is only available for Microsoft Office 2000 and specifically needs c:\WINNT\system32\msxml.dll. Some applications have been known to overwrite this file with another version possibly causing the utility not to work. Always ensure that you work with the vanilla version of the msxml.dll. This chapter discusses how to: Set up connection information. Create a template. Import data into PeopleSoft using ExcelToCI.xls. Construct the SOAP/XML request. Send the SOAP/XML request and receive the SOAP/XML response.

Understanding the Excel To CI UtiIity

The Excel to Component Interface utility includes an Excel spreadsheet with Visual Basic for Applications (VBA) code that enables you to input data to your Peoplesoft database. The code formats spreadsheet data into a PeopleSoft readable Document Object Model (DOM) structure, and submits it to the PeopleSoft database. Next a PeopleCode program parses the DOM structure and utilizes the component interface to create entries in the PeopleSoft database, preserving the business logic built into the PeopleSoft component. Because the component interface is a wrapper around the component, all logic applied during data entry is applied when loading data through this tool. The component interface executes all the necessary PeopleCode events and the fields-level edits. Based upon results from saving the component interface, another DOM is created in the PeopleCode that returns success, warnings, and/or errors to the Excel document. Records in error can be corrected and resubmitted.

Setting Up Connection Information

Note. The Excel to CI utility requires the Visual Basic 6.0 SP5: Run-Time Redistribution Pack installed. It is available at this website: http://www.microsoft.com/downloads/release.asp?releaseid=28337&area=top&ordinal=23 To set up the connection information, select the Connect Information tab in ExcelToCI.xls.

Connection Information tab

Note. Most likely they will be the PeopleSoft default values unless your installation is customized. If you are unsure what you set these values to you can check your system administrator. Web Server Machine Name Portal HTTP Port Protocol PeopleSoft Site Name Node Blocking Factor Enter the name of the PIA web server Enter the portal name. EMPLOYEE is a default portal shipped with PeopleSoft PIA server. Enter the HTTP Port number. The default is 80. The protocol used to access the web server. The default is http. The PeopleSoft site name that you entered when you installed PIA. The default is ps. Enter the PeopleSoft node name. The default is PT_LOCAL. This determines the number of records bundled and sent to the server together. Default is 40. This is the blocking factor that PeopleSoft has determined to give optimal performance.

Action The value for the Action field is populated when the component interface is retrieved from the database. The different actions are Create, Update, and UpdateData. Create Set if the component interface has create keys. Only one scroll item can be created. After the primary record is created, the Process Mode needs to be changed to Update, to create more scroll items. Set if the component interface does not have create keys. Instead of level 0 record, scrolls are created; this mode will automatically create a new level one scroll, without checking the keys.

Update

UpdateData

UpdateData requires intervention from the designer creating the template. This mode is used to update existing data. Then keys locate the row in the scroll match data from the upper level scroll. When a match is found the row is updated with new data.

Note. If you are unable to connect to the server or the connection fails, you will be prompted for a User ID and password again. Your login information is needed for both creating the template and submitting it to the database. You will be prompted for your User ID and Password when you attempt either of these functions for the first time after opening the document. The information will be saved and reused as long as you keep the Excel document open. Note: The Web Library SOAPToCI and the component interface being used must be in the permission list for the User ID entered at connection time on the ExcelToCI.xls spreadsheet. For more information, see PeopleTools Security PeopleBook.

Troubleshooting
If you are having trouble setting up the connection, note the following: During the login there is a prompt asking you if you want to create a debug log. If you specify Yes, two log files are created. One that logs the ExcelToCI.xls and the other logs the SOAPTOCI Web Library. The log for ExcelToCI.xls is created on the workstation running the Excel spreadsheet in the temp directory, while the one for the Web Library is created on the application server in <PS_HOME>\appserv\<DOMAIN>\files directory. Log files are written for each <Blocking Factor> number of records. However, unless you are receiving error messages that are not being returned to the Status column of the spreadsheet, PeopleSoft recommends that you specify this to No, the default

Creating a Template
Select the Template tab in ExcelToCI.xls to create your template. Enter your User ID, password, and the component interface name for which you want the template created. Select the Generate Log checkbox to create a log file.

Build New Template dialog

Template tab

Identifying Required Fields

When determining which fields of the component must be added to the template, keep in mind that the fields exercise the same business logic and execute the same PeopleCode as if the record were entered on-line, through PIA. To provide the minimal data necessary, these fields must either be provided with default (hard-coded) values, or user-provided values. Note the following: Some values are required to trigger the creation of child or scroll level records. Unlike Import Manager, you do not have to specify all required field values. As a result of the PeopleCode triggered during the instantiation and execution of the PeopleSoft component, many of the default fields are provided. You do not have to specify a value for every field in the record. When providing field level values for translate fields, provide the translate value (the one stored in the database) not the short or long description. If you are unsure of the field values, check in the record definition in Application Designer.

Selecting fields for Data Input from the Template tab.

Note. The buttons on this page will clear the data on the Template page and the Data Input page when the pages are rebuilt. If you have information you need to save make a backup of the document before you begin to design the connection. This pertains especially to the Data Input page. That information can be stored as a record of the work done with this document.

Build New Template

Builds a new template based upon a component interface. The Build New Template macro builds the parent child relationship within Excel based upon the component interface scroll level definition. The macro adds a new row for each scroll level and assigns a unique record type. You will be prompted for the name of the component interface; you should also know the component and the data source for the new entries. The structure of the component interface is retrieved from the database. All of the fields that are available through the component interface display on the template page. The name of the template-created component interface displays in the top left corner of the page; field information displays across the page in columns. Each field retrieved has an associated colored (yellow) cell at the bottom of the page. Different properties may contain colored cells in different rows corresponding to the structure of the component interface. For example, a property at level 1 has a colored cell one row below that of a level 0 property.

Mark Selected Input Cell

Maps data from your external data source to PeopleSoft. Mark each fields color-coded cell for which you want to set new values.

Unmark Selected Input Cell Repaint Input Cells

If you mark a field by mistake, you reselect its cell and press this button. This will clear the selected mark. If you deselect several fields use this button to repaint all the unselected fields. Note. It is at this point that you must make sure you have all the fields for which you wish to input data selected. The next step will build the Data Input page based on your selection.

Build Blank Input Page from Template button

Creates a sheet on which you can enter the data to be imported into PeopleSoft. You will be redirected to the input page, and then prompted to verify you want to delete the data on that page. If you select "No", processing will stop. If you select "Yes" The data input page clears, and new headings (based on the selected fields on the Template page) will be written to the data input page.

Clear Template

Clears all the data on this page.

Note. You should unit test the template you created with a few sample entries, and then verify your results before using the interface for mass input. If your results are expected, continue entering data. If you forgot to select a property, you will need to build a new template

Defaulting Values
Some fields have default values associated with them, either in the record definition or at run time when the record is created on the database (the input for these fields is usually either blank or "NEXT"). To accept the database default, do not select the field and no value for this field will be submitted. There may be some fields for which you want to create your own default. For example, if you want the field "Status as of Effective Date" to be set to A, enter the default value in the template for that field. Then, do not mark the cell for use on the input page. The field will not appear on the Data Input page, but will be filled in on the Submit to Database page. This is useful for Effective Dates, Status fields, Set Ids for simple imports, and so on. After the setup is complete, there will be a row of labels indicating the values that can be used for input. Once you have entered your data, you are ready to submit it to the database.

Adding Multiple Rows

By default only one row is available for a given level. To add multiple rows at a collection level, insert a blank row and copy the row you want to duplicate. In the following example the SDK_BUS_EXP_DTL collection level has two rows, indicating that the data you want to insert into the database will have a maximum of two rows of SDK_BUS_EXP_DTL. Note. On the Data Input tab (when the hierarchy is flattened) you will see duplicate columns for these inserted rows. You may select to enter data for one row or all the rows. For rows that do not have data, ExcelToCI skips the row and builds the appropriate SOAP Request.

Adding multiple rows at a level

Importing Data
Select the Data Input tab in ExcelToCI.xls.

Data Input tab

Data Input page

Results posted from Submit to Database page.

The Data Input tab is also used to display the results posted from the Submit to Database page. Errors in input flagged on the Submit to Database page can be posted to the input page and when you have corrected them, the items marked in error can be re-imported to the Submit page. Errors received for that record display in a comment field by moving the cursor over the error flag. The records marked "OK" in green are ignored by the Submit to Database page, and can be kept as a record of work completed.

Submitting to the Database

Select the Submit to Database tab.

Enter data to submit to the database.

Import items from Data Input Pressing this button causes the data on the submit page to be cleared. The template structure on the template page is copied to this page (once for each item on the Input page), and the values from the Data Input page item are inserted into the structure. The result is a set of structures that can be submitted to the database, with values that have been inserted into the input page. Any input values that were marked as "Error" in previous processing are imported again. Values marked "OK" will be ignored.

Submit items on this page

This is used to submit each row of data to the database. If the data is added successfully to the database, the item will be marked "OK" and its background color is set to green. If it fails, the status field will be marked "Error", and its background color is set to red. A comment will also be inserted into the field, with the error message issued by the database. After correction, the data can be resubmitted. The results that are marked in the first column will be copied to the corresponding item on the Data Input page. The comments embedded in the "Error" mark will also be copied. After corrections the data can be imported again. The items marked "Error" will be resubmitted, while those marked "OK" will be ignored

Post these results to the Data Input

Results from submission

Note. Excel has a physical limitation of 256 columns and 65k rows. There is not a one-to-one relationship between the records submitted and the rows of data on the Submit to Database page. Depending on the complexity of the record structure and the number of scroll-level records that are required in the template, you could use 10 to 15 rows per record of data on the Submit to Database page. To work around Excels limitations, you may need to limit your import data so that the number of rows on the Data Input Page will not exceed 65k.

Constructing a SOAP/XML Request

You can construct a SOAP/XML request to create, update, or get component interface rows. The request and response contain component interface data in a SOAP/XML format. Request Format <?xml version="1.0"?>

<SOAP-ENV:Envelope xmlns:SOAPENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <Action__CompIntfc__CIName> Tags and Data </Action__CompIntfc__CIName> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Valid actions are Create, Get, Update, and Updatedata. CIname is the name of the component interface. Tags and Data contains the tags and data for the component interface row or rows.

Sample Create Request <?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:SOAPENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <CREATE__CompIntfc__QE_SUPPORT_DOC_TBL> <QE_SUPPORT_DOC_ID>POLICE</QE_SUPPORT_DOC_ID> <QE_SUPPORT_DOC> <QE_DESCR>Police Report</QE_DESCR> <QE_DESCRSHORT>Police</QE_DESCRSHORT> </QE_SUPPORT_DOC> </CREATE__CompIntfc__QE_SUPPORT_DOC_TBL> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Sample Get Request <?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:SOAPENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <Get__CompIntfc__SDK_BUS_EXP> <SDK_EMPLID>8052</SDK_EMPLID> </Get__CompIntfc__SDK_BUS_EXP> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Sample Update Request <?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:SOAPENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body>

<UPDATE__CompIntfc__SDK_BUS_EXP> <SDK_EMPLID>8001</SDK_EMPLID> <SDK_BUS_EXP_PER> <SDK_EXP_PER_DT>08/14/2002</SDK_EXP_PER_DT> <SDK_BUS_EXP_DTL> <SDK_CHARGE_DT>08/14/2002</SDK_CHARGE_DT> <SDK_EXPENSE_CD>01</SDK_EXPENSE_CD> <SDK_EXPENSE_AMT>1234.56</SDK_EXPENSE_AMT> <SDK_CURRENCY_CD>USD</SDK_CURRENCY_CD> <SDK_BUS_PURPOSE>Jen Test</SDK_BUS_PURPOSE> <SDK_DEPTID>10100</SDK_DEPTID> </SDK_BUS_EXP_DTL> </SDK_BUS_EXP_PER> </UPDATE__CompIntfc__SDK_BUS_EXP> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Sample Updatedata Request <?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:SOAPENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <UpdateData__CompIntfc__SDK_BUS_EXP> <SDK_EMPLID>8001</SDK_EMPLID> <SDK_BUS_EXP_PER> <SDK_EXP_PER_DT>06/28/2002</SDK_EXP_PER_DT> <SDK_BUS_EXP_DTL> <SDK_CHARGE_DT>01/04/2002</SDK_CHARGE_DT> <SDK_EXPENSE_CD>02</SDK_EXPENSE_CD> <SDK_EXPENSE_AMT>123.45</SDK_EXPENSE_AMT> <SDK_CURRENCY_CD>USD</SDK_CURRENCY_CD> <SDK_BUS_PURPOSE>UpdateData</SDK_BUS_PURPOSE> <SDK_DEPTID>10100</SDK_DEPTID> </SDK_BUS_EXP_DTL> </SDK_BUS_EXP_PER> </UpdateData__CompIntfc__SDK_BUS_EXP> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Sending the Request

To send the request, post the XML code to the URL of the PeopleSoft Internet Architecture (PIA) server with the appropriate path to the IScript on the server: Use this format: <Protocol(http or https)>://<WebServerMachineName >:<HTTPPort>/psc/ps/<Portal>/<Node>/s/WEBLIB_SOAPTOCI.SOAPTOCI.Field Formula.IScript_SOAPToCI?userid=<UserID>&pwd=<password>&disconnect=y &postDataBin=y

Example of Sending a Request http://MyWebServer:80/psc/ps/EMPLOYEE/PT_LOCAL/s/WEBLIB_SOAPTOCI.SOAPTOCI.Field Formula.IScript_SOAPToCI?userid=PTDMO&pwd=PTDMO&disconnect=y&postDataBin=y

(PSserver) is the machine name of the server. (PSPortal) is a portal defined on the PIA server. (PSNode) is a node defined on the PIA server.

Getting a Response
Sample Response if Row Already Exists This is one example of the error response. The messages vary depending on the type of error. <?xml version="1.0" encoding="UTF-8" ?> <SOAP-ENV:Envelope xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <USER_PROFILE> <Error-Warning> <Message> <Type>Error</Type> <MessageSetNumber>91</MessageSetNumber> <MessageNumber>49</MessageNumber> <MessageText>Row already exists with the specified keys. {USER_PROFILE} (91,49)</MessageText> <ExplainText>A rows already exists in the database with the specified keys.</ExplainText> </Message> </Error-Warning> <Key_information> <UserID>PTDMO10</UserID> </Key_information> </USER_PROFILE> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Sample Get Request The following XML code gets an SDK_BUS_EXP component interface row for an employee with an employee ID of 8052. <?xml version="1.0"?> <SDK_BUS_EXP action="GET"> <SDK_EMPLID key="Y">8052</SDK_EMPLID> </SDK_BUS_EXP> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Sample Get Response The XML response for this employee is: <?xml version="1.0" encoding="UTF-8" ?> <SOAP-ENV:Envelope xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <SDK_BUS_EXP> <SDK_BUS_EXP_PER> <SDK_EMPLID>8052</SDK_EMPLID> <SDK_EXP_PER_DT>2000-11-09</SDK_EXP_PER_DT> <SDK_BUS_EXP_DTL> <SDK_EMPLID>8052</SDK_EMPLID> <SDK_EXP_PER_DT>2000-11-09</SDK_EXP_PER_DT> <SDK_CHARGE_DT /> <SDK_EXPENSE_CD /> <SDK_EXPENSE_AMT>0</SDK_EXPENSE_AMT> <SDK_CURRENCY_CD>USD</SDK_CURRENCY_CD> <SDK_BUS_PURPOSE /> <SDK_DEPTID /> </SDK_BUS_EXP_DTL> </SDK_BUS_EXP_PER> </SDK_BUS_EXP> </SOAP-ENV:Body> </SOAP-ENV:Envelope>