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

Enter the name of the PIA web server

Portal

Enter the portal name. EMPLOYEE is a default portal

shipped with PeopleSoft PIA server.

HTTP Port

Enter the HTTP Port number. The default is 80.

Protocol

The protocol used to access the web server. The default is

http.

PeopleSoft Site Name

The PeopleSoft site name that you entered when you

installed PIA. The default is ps.

Node

Enter the PeopleSoft node name. The default is

PT_LOCAL.

Blocking Factor

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.

Update

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.

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

If you mark a field by mistake, you reselect its cell and

press this button. This will clear the selected mark.

Repaint Input Cells

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.

Post these results to the

Data Input

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

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>