ExcelToCI Troubleshooting Guide

Contents

Introduction Tool Basics Handling Multiple Child Collection Rows Testing Troubleshooting

2 3 7 !"

Introduction
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. "or additional information on CIs and ExcelToCI see the #eopleTools Component Interface #eople$oo%s. &ou may also notice that the spreadsheet screenshots are not all identical, and may loo% different from your spreadsheet. The reason for this is that the document was developed and updated over multiple #eopleTools releases. 'ome things to remember( ). *ot all CIs are suitable for ExcelToCI. +. The ',A#T,CI #eoplecode sets the CI properties in the same order in which they appear in Application -esigner. This will be a problem in cases where properties need to be set out of sequence in order for #eoplecode validations to wor% correctly. .. Avoid using large complex CIs. /owever, if you elect to use them, send them in smaller chun%s to avoid running into problems such as timeouts, and to improve the application server throughput. 0. Ensure that you use a copy of the ExcelToCI wor%boo% found in 1#'2/,3E45excel for the #eopleTools release you6re on. Also, ma%e sure you don6t open multiple Excel wor%boo%s at the same time, either multiple ExcelToCI wor%boo%s or a combination of ExcelToCI wor%boo%s and other Excel wor%boo%s to avoid seeing strange behavior. *ote the following about the Excel spreadsheet and macro file!. a. #T 7.08 9 ExcelToCI+::;.xlsm 9 $oth the spreadsheet and macro are in a single file. This file was released in the #T 7.08..: or #T 7.08..) #eopleTools patch. b. #T 7.<: and later 9 $oth ExcelToCI+::;.xlsm and =el>ang3cro.xla macro file! are used. $efore opening the ExcelToCI spreadsheet, copy both files to the Excel client machine6s test?wor%ing directory to avoid errors.
#$TE% The following sections cover some of the available topics, not everything. 'ee the ExcelToCI documentation in the #eople'oft Component Interface #eopleTools #eople$oo%s @
#eople'oft #eopleTools 7.<. #eople$oo% 4 #eople'oft Component Interfaces 4 Asing the Excel To Component Interface Atility&

Tool Basics
Connection 'age

(eb )er*er +achine na+e% #rovide the web server machine name. If you created auth to%en domain, then include it in the name. The name should match the #IA A=> server name use the same name as when logging into #IA via the browser!, port and site name, and you should be able to log into #IA using the web server, port and site name used here. 'rotocol% -efault is http. If you want to use https, ensure that the ''> certificates are properly installed, including any required client certificates. ,ne way of testing whether ''> is properly installed is to open a browser and try logging into #eople'oft using the https port. If the certificates are invalid, you will usually get a pop up message indicating possible problems with the certificates. /owever, if you clic%ed ,% to continue in spite of the questionable certificates, you won6t see this popup on subsequent attempts to log into #eople'oft. #$TE% The default ''> setting In Beb>ogic the setting is CTwo Bay Client Cert $ehaviorD, and the default setting is EClient Certs *ot =equestedE! is supported. If client cert setting is CClient certs requested, but not requiredD or more stringent, uploads from Excel will not wor%. HTT' HTT') 'ort% #rovide the web server6s port number. The default http port is 7:. The default https port is 00.. Even though these are the standard defaults, verify that the port number is correct in the case where the port number does not 3

appear in the #IA login A=> because your system administrator can set up the environment such that even though the port number is resolved without it being specified when logging into #IA the port number might not be 7: or 00.. 'ortal% The name of the portal you are using. E3#>,&EE is the default portal shipped with #eople'oft. 'eople)o,t )ite #a+e% The #eople'oft site name that you entered when you installed the #eople'oft Internet Architecture. The default is ps. The site name can be determined from the #IA browser A=>, as it is the second field after the port number in the A=>. In sample below it is E8):F+)A. Also remember this field is case sensitive.
http(??sla.us.oracle.com(7+::?psp?E8):F+)A?E3#>,&EE?/=3'?h?GtabH-E"AA>T

#ode% The #eople'oft default local node name. The default is #T2>,CA>. To determine the default local node name, log into #IA and navigate to #eopleTools 4 Integration $ro%er 4 *ode -efinitions. Then press the search button without providing any search criteria. The default local node will have a ) in the >ocal *ode column and a C&D in the -efault >ocal *ode column. -anguage 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. Chun.ing /actor% The number of rows of data to be transmitted to the database at one time. The default is 0:. If the CIs being used are large and?or have much #eoplecode, 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. Bhen the error threshold is exceeded, an error message appears and submission to the database stops. &ou should specify a valid number instead of leaving it blan%. )ub+it Blan.s 0s Input% This option is available in #T 7.<) and later. Bhen this option is set to &es and a character input field selected for input contains only blan% spaces, the field will be included for submission instead of being ignored. This option is set to *o by default, for bac%wards compatibility. If full9 width blan% space Anicode characters are entered as an input value in ExcelToCI, this is achieved by using an encoding that supports such Anicode characters! the field will be submitted, the blan%s will be sent, and the value will not be trimmed before it is saved to the database. If regular A'CII blan% spaces also %nown as half9width characters! are entered as a value for a character field, the field will be submitted, but the value will be trimmed, so an empty string will be saved. In essence, the field value will be cleared.

$ptional 1e2s% This option is available in #T 7.<. and later. This option is provided for use by ,racle Applications development, not for customer use. Ase the default value of *o. 0ction% The value for the Action field is populated by the system when the component interface is retrieved from the database. /owever, you can change the populated value by selecting it from the Action drop9down 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 %eys. Ase this mode when new %eys are being added at level :. Update: Ase this mode if you are adding new children to an existing parent e.g. inserting new rows into existing collections!. UpdateData: This mode is used to update specific non9%ey values that already exist but need to be updated. The system uses the %eys to locate the row, and when a match is found, the row is updated with new data. If a %ey match is not found by the system, it displays an error message indicating which collection was missing a %ey match. #$TE on e,,ecti*e dated processing% Bhen inserting effective dated collection rows remember the following. "irst, C/istoryD is included in the data set. This means that both historic data in the past!, and future data are included in the existing collection data. 'econdly, the data used to initially populate the new row is copied forward from the existing row at index ). This means that if the existing >evel ) collection row at index ) has child collections containing data, those child collection rows are copied forward to the new >evel ) row6s children, but with the effective date of the new row. The reason this behavior is present is due to the following settings in the #eoplecode processing the request. ). /istory @ The Fet/istoryItems and Edit/istoryItems flags are set to CTrueD in the #eopleCode processing the data. This means that both historic data in the past! and future data are included in the data set. This would be similar to Correction 3ode when using the online component. +. Index passed to InsertItem ! and Item ! methods 9 The index passed to the method being used InsertItem or Item! is always ). This means that the data used to initially populate the new row will be ta%en from the existing row at index ), even if the existing row is a future dated row. "or E""-T effective dated data!, if you want to insert at other indexes, see the two solutions below for more information on how this can be accomplished. -oc I- 8;.:+:.) E9ExcelToCI 9 Can the -efault Ialues of the newly inserted E""-T =ow be Copied forward from a =ow other than =ow )G 5

-oc I- )+;:<78.) E9ExcelToCI( E""'EJ Key Is *ot $eing Ased to -etermine Insert Index using E""-T -ata

Te+plate 'age

#ew Te+plate% Ase this button to download and create a new template based on a component interface. )elect Input Cell% Ase this button to select fields to be included on the Input page. The selected cells will have a pin% bac%ground as shown above!. Include /or )ub+ission% Ase this button to include a single property to be included on the 'taging and 'ubmission sheet. #roperties 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 li%e to see in the structure of the 'taging and 'ubmission sheet. #roperties that are included for submission are highlighted in blue. -etermine 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 'taging L 'ubmission page, not the -ata Input page.

Insert #ew Child% Ase this button to Copy the selected row to be inserted as a new child. This creates multiple occurrences of the same record type. "or example, if the selected row has a template identifier of )::, a new row is inserted that also has an identifier of ):: and is an exact duplicate of the selected row. If you want to upload multiple collection rows, see the next section, /andling 3ultiple Child Collection =ows.
#ote3 4se Insert #ew Child when +ultiple children +ust be sub+itted under the sa+e parent record3 Multiple children should not be created at identi,ier 5553

Handling Multiple Child Collection Rows )i+ple scenario

This is the case where the Cmultiple rowD collection does not have any children, so you don6t need to maintain a hierarchy. "or this case you can simply use the Insert *ew Child button as shown below. The example below uses the A'E=2#=,"I>E CI. The =oles collection is a >evel ) collection, and =outeControls is the >evel + child collection of =oles. #ote% This is simply used for illustration purposes. 03 Be,ore inserting second -2 collection row

B3 0,ter inserting second -2 collection row

C3 6ata Input page 7note that both -2 rows are 8,lattened9&

10

63 )taging : )ub+ission page 7note the 2 -2 rows; hierarch2 is restored&

Co+plex scenario
Asing the above example, suppose we need to be able to have multiple >) =oles! and >+ =outeControls! collections. In this case we6ll Must illustrate inserting two >) and >+ rows. &ou will need to use the same technique for additional rows up to the maximum number of rows you expect to upload. Bhen uploading, fill in the data for the number of rows from the left side, leaving any blan% rows to the right on the -ata Input page.

11

03 Te+plate page ). Clic% on column ) of the highest9level cell in this case it is the >) row!, and select CInsert *ew ChildD. =epeat this for the maximum number of rows you intend to upload. "or this example we6re going to use three >) and three >+ child rows, so we need to insert a total of N rows. 'ince there6s already one >+ child row we want to end up with five >) rows and one >+ row initially, as shown in the screenshots below.

12

2. Right-click on column 1 of row 21 abov ! co"# an$ "a%t &'(c l m nu) th 310 row cont nt% into th alt rnating 300 row% %o #ou hav th $ %ir $ hi rarch#! a% %hown b low. *hi% will allow u% to in% rt u" to thr +1 coll ction row%! ach with a +2 chil$ row.

.. #ress the C*ew -ata InputD button to create a new -ata Input page.

13

B3 6ata Input page% #ote that the hierarch2 is ,lattened and onl2 two -! rows ha*e data3 0,ter entering the data press the 8)tage 6ata ,or )ub+ission9 button3

14

C3 )taging : )ub+ission page% #ote that the third -! row and its child row are e+pt23 (hen the data is uploaded the blan. row will not be sub+itted<3 O #ote% $n 'T =3"> and earlier the beha*ior is as described abo*e 7e3g3 the blan. row will not be sub+itted&3 The =3?5 and =3?! @B +acro code logic has a +odi,ication; which uploads the blan. row3 This can cause issues in cases in*ol*ing collection .e2s with de,ault *alues3 )ee 6oc 7?=A5>3! and !2==!"A3! ,or additional in,or+ation3

15

Testing Troubleshooting
In terms of testing, first test the CI6s underlying component online to ensure that it wor%s properly. Then test the CI using the CI Tester as described in section A below before testing from ExcelToCI. It6s a good idea to use this testing sequence, especially when developing custom CIs CIs built from custom or delivered components!. "or additional information on developing and testing CIs see C-oc I- )<:8N:+.) 9 E9CI( -eveloping and Testing Component Interfaces CIs!D. This document has helpful information on developing and testing CIs, as well as lin%s to other related solution documents.

03 CI Tester
). ,pen Application -esigner in .9tier that is through the application server6s B'> port see screenshots of Configuration 3anager below!. #ote% #rior to #T 7.07, the B'> process was automatically enabled to run, but in #T 7.07 later, it must be explicitly enabled from the psadmin menu.

16

+. ,nce in Application -esigner open the CI to be tested. .. ,pen the CI Tester right9clic% on the CI and select CTest Component InterfaceD or select CTest Component InterfaceD from the Tools menu. 'ee the Component Interface #eopleTools #eople$oo%s for additional information on using the CI Tester.

17

0. Test using the same scenario as from Excel Create, Apdate, or Apdate-ata!.
#ote% "or items iii Apdate! and iv Apdate-ata! below, ensure that both Fet/itoryItems and Edit/istoryItems flags chec%boxes in CI Tester! are set to True chec%boxes are selected in CI Tester!.

i.

Enter the values for the properties in the sequence in which the CI properties appear. Bhile doing so pay attention the behavior for example a value that was accepted by the system no edit error! being blan%ed after some subsequent properties6 values are entered!. "or the Create Action enter the create %eys, press the CCreate *ewD button and then enter the other properties6 values. "or Apdate, enter the get %ey values, press the CFet ExistingD button, and then navigate to collection s! into which you6re inserting new

ii. iii.

18

row s!. Then right9clic% on the collection cube shaped! icon and select the InsertItem ! method and supply an index of ). Then enter the correct values for the new row. Bhen processing the request from Excel, the ',A#T,CI #eopleCode uses a value of ) for the InsertItem ! method. iv. "or Apdate-ata, enter the get %ey values, press the CFet ExistingD button, and then navigate to the properties being modified and edit the value. ,nce you6ve performed item ii, iii, or iv above, select the topmost row in CI Tester row with the CI icon!, right9clic% and select 'ave. A return value of ) indicates success, while a value of : indicates that the changes were not successful. If : was returned you6ll see error messages at the bottom of the tester utility. Ase P < below to get a 'J> and #eopleCode trace of the execution path. Ase P N below to step through the underlying #eopleCode.

v.

vi.

<. )B- 'eopleCode tracing 9 Test with 'J> and #eopleCode tracing enabled on the application server to get a better understanding of the execution path. I use tracing values of )+; 'J>! and .<8N #eopleCode!. To enable tracing do the following. i. ii. ,pen the psappsrv.cfg file. >ocate the following bitfield settings and set them to the desired values the values I use are shown below!. Trace'qlH)+; Trace#CH.<8N iii. iv. 'ave the psappsrv.cfg file. =estart the application server. #ote% If you have the flag shown below set to & as shown below!, you don6t need to restart the application server each time you want to enable?disable tracing. 'imply ma%e the bitfield changes, save the psappsrv.cfg file, and the application server will accept the changes while it6s running. Also, if this flag is set to &, you6ll have better control over what is traced and avoid a slow starting application server. &ou6ll also minimiQe the amount of tracing, and avoid generating and loo%ing through unnecessary and irrelevant trace information. Bhen using CI Tester

19

for example, first open the CI Tester in application designer, and then set the above trace bitfield settings to enable tracing. Allow -ynamic ChangesH& N. 'eopleCode debugger 9 Test with the #eopleCode debugger if you want to step through the underlying #eopleCode. "or this do the following. i. 'hut down the application server. =econfigure the domain so that a #eopleCode debugger application server process is started. Then restart the application server. ,pen application designer in .9tier through the same application server. ,pen the CI to be tested. 'elect C-ebugD 4 Enter -ebug 3ode from the menu. Then select C$rea% at startD from the -ebug menu selection. ,pen the CI Tester and begin testing. The debugger will stop at the first segment of #eopleCode that fires, and you can step through it to follow the execution path.

ii. iii. iv. v.

B3 ExcelToCI
). ExcelToCI and )$0'T$CI logs @ Fenerating?reviewing these two logs for a transaction is sometimes sufficient to find the source of the problem. Bhen submitting the data chec% the Fenerate >og chec%box as shown below.

The Fenerate >og selection causes the following two log files to be created. *ote that a new log file is create each time you submit data. i. )$0'T$CIxxx3log @ $y default this log is created in the app serverEs RfilesR directory below the app server domain!. The xxx is the 20

timestamp appended to the file name. This log shows the #eopleCode execution path in the ',A#T,CI application pac%age, and it can help you quic%ly determine the cause of the behavior you6re seeing. ii. ExcelToCIxxx3log @ $y default this log is created in user6s 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 following. ,n the Excel client machine6s des%top right9clic% on the C3y ComputerD icon and select #roperties. Then select the CAdvancedD tab and clic% on CEnvironment IariablesD. >ocate the Temp or tmp! variable mappings it may be C(5Temp or some other location!. A quic% alternative is to open Bindows Explorer, enter STempS in the address bar and press the Enter %ey. This will resolve to your Temp directory location. This is normally where the ExcelToCIxxx log is placed. This log simply contains the ',A# format message containing the Excel data, and is useful in verifying that the uploaded data is the same as in the Excel spreadsheet.

+. )B- 'eopleCode tracing @ After submitting the data locate and review the ',A#T,CI log. If the log does not provide sufficient detail to narrow down the source of the problem, enable 'J> and #eopleCode tracing on the application server and upload another transaction from Excel with the Fenerate >og chec%box chec%ed. .. Co+paring ExcelToCI to CI Tester results @ If the results from ExcelToCI are different from those using CI Tester, test using CI Tester in .9tier! using the same values as from Excel with #eopleCode and 'J> tracing enabled on the application server. 'ave the trace file and then run another transaction using ExcelToCI with #eopleCode and 'J> tracing enabled on the application server!. 'ave the second trace file. Compare the execution path and values in the two trace files. 0. 6ebug ,ro+ @B0 9 In some cases for example, where values are not being correctly handled in Excel, or other Excel related processing!, you can step through the I$A code to try and pin point the source of the problem. To step through the I$ code do the following( i. "rom Excel, press Alt9")) to open the I$ Editor. ii. >ocate an appropriate location?line of code for the $rea%point, and press "8 to enable the $rea%point press "8 to disable it as well!. 'ave the setting in I$. iii. Fo bac% to Excel, and perform the operation such as submit the data! to hit the I$ $rea%point you set above. Then step

21

through the I$ code using the appropriate debugger functions such as 'tep Into, 'tep ,ver, etc.!.

C3 0dditional in,or+ation resources

). Aploading large volumes of data using complex CIs. a. ExcelToCI was not designed for batch?large volume processing b. &ou 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. "or example, you may see messages in sequence such as CThe response text is not valid T3>. >ogin -ata clearedD, CError occurred in routine send',A#=equest2'ubmitTo-$U The parameter is incorrectD, and CThe T3> string contains invalid charactersD. ,ne 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. 'uggestions( i. Avoid using large complex CIs. $uild and use streamlined CIs that are not large, complex, and do not have a lot of #eoplecode in the underlying layers. ii. Ase a smaller Chun%ing "actor default is 0:!. &ou can drop the value to ), and then increase it until you find a reasonable value that wor%s. Also remember that the error probably won6t occur all the time, and will depend on different factors such as the available hardware resources web server and application server!, amount of load on the system at processing time, the distance between the Excel client and the web server client is miles away from the server!, etc. 'o, you don6t want to use an aggressive large! value. Asing a smaller value means more data uploads from the client. $ut it also means that uploads should be more evenly distributed among the application server instances, improve application server throughput, and ma%e web server timeouts less li%ely. iii. If you are on #eopleTools 7.<: or later, and are using the 3icrosoft T3> parser! v. N.: which you should be!, you can try to extend the timeout values in Excel. To do so, see -ocument )<:8):7.) for step by step instructions. +. Additional note about the Chun%ing "actor @ The Ctransaction boundaryD begins with the Iscript invo%ed once the upload gets to the web server and

22

encompasses the number of records in the Chun%ing "actor. There are scenarios where if you use a Chun%ing "actor larger than one, you can have some of the cells show up C,% @ green cell colorD even though the record was not saved to the database. The ',A#T,CI application class was not able to tell if a rollbac% has occurred when the CI6s save ! mehtod was called. This is due to the complexity of the underlying layers below the #eoplecode. If a CI rollbac% occurs for one of these records, the ',A#T,CI application class would not %now the rollbac% occurred. And it would return an ,K status for the previously saved rows except the current errored row! bac% to ExceltoCI. This would cause ExcelToCI to display incorrect results. This is due to a combination of the CI6s underlying component6s behavior, and how the transaction boundaries are defined. .. ExcelToCI and '', 'ingle 'ignon! 9 The %ey to incorporating '', with ExcelToCI begins with an understanding of the architecture of ExcelToCI and the manner in which '', is handled. $elow is a brief description of the ExcelToCI architecture and a brief discussion of how '', may be handled. a. ExcelToCI Architecture 9 The upload process begins with the user providing a valid #eople'oft Aserid and password in the upload dialog window. The underlying I$ macro then posts the data and user credentials in a ',A# envelope to the #eople'oft web server. The upload process is non9interactive, meaning that once the user enters his credentials on the upload window and presses the C,%D button, there is no further user interaction. b. '', Architecture 9 Typically this entails %nowing whether the user is authenticated prior to the request hitting the web server or after hitting the web server. =egardless of when the user is authenticated before or after hitting the web server! user credentials need to be provided in the request from Excel. If the user is authenticated prior to the upload reaching the web server, it is up to you and your '', vendor if applicable! to determine how to authenticate the user, and add the credentials into the upload so they get to the web server. Bhen the signon #eoplecode executes you will also need to ensure that it authenticate the userEs RcredentialsR that were provided. "or example, if a user is re9directed to an alternate site when attempting to sign on into #IA via the browser! to provide his '', credentials, you or your '', solution vendor! will need to customiQe the I$ macro code so the payload goes to the appropriate site, the user is authenticated, and some form of a coo%ie or the #eople'oft userid! is included with the pac%age that is sent to the #eople'oft web server. Additionally, if you want to avoid having a dialog window for the user to provide credentials, you will need to extract them from the appropriate location

23

in time for the upload and ensure that they are present in the uploadEs http header. 0. 'earch the 'olutions available in my,racle'upport. Typically ExcelToCI solutions have CE9ExcelToCID in the summary. <. "or additional information on developing and testing CIs see the document below( This document has helpful information on developing and testing CIs, as well as lin%s to other CI related solution documents. 6oc I6 !?5>A523! C ECCI% 6e*eloping and Testing Co+ponent Inter,aces 7CIs& N. ,pen a case with the #eople'oft FC' Flobal Customer 'upport!.

24