Using the Component Interface Software Development Kit

This chapter provides an overview of the component interface software development kit (SDK) and discusses how to:

• Set SDK prerequisites.

• Use the SDK_BUS_EXPENSES test page.

• Test the SDK_BUS_EXP component interface.

• Use the component interface SDK Java and C++ sample.

• Use the component interface SDK COM Excel sample.

• Use the component interface SDK COM ASP sample.

Understanding the Component Interface SDK

The PeopleSoft component interface SDK is installed with the PeopleTools installation. It provides resources to assist you in developing and testing component interface-based integration between PeopleSoft and third-party applications. The SDK contains sample definitions with data and source code. For easy identification, all of the definition names start with SDK_. The SDK is installed in the PeopleSoft home directory (PS_HOME) under sdk.

Note. The SDK definitions and associated data are for development purposes only and should not be used in a production environment.

Component Interface SDK Samples

Programming samples for the component interface SDK_BUS_EXP are part of the SDK. The samples are available in four languages—Java, C++, VBA, and ASP.

The component interface source code is located in the <PS_HOME>\SDK\PSCOMPINTFC directory.

Note. The source files mentioned in this section are located relative to the installed PeopleSoft home directory (PS_HOME).

Prerequisites for Using the Component Interface SDK

To call a PeopleSoft component interface, you must have:

• A working understanding of PeopleTools components.

• A working understanding of Java, C++, or COM.

• The application server and database installed.

• The Java Virtual Machine (JVM) installed that is supplied with the Sun Microsystems Java Development Kit (JDK), found in the %PS_HOME%\JRE directory.

Using the SDK_BUS_EXPENSES Test Page

The SDK includes a component interface, called SDK_BUS_EXP, which is part of the sample development project and is delivered with the SDK. It is built on the component SDK_CI_SAMPLES, which contains the page SDK_BUS_EXP. The page exposes information about employee business expenses for external access.

Note. The component SDK_CI_SAMPLES is a sample and is not for business use.

To test the SDK_BUS_EXPENSES test page:

1. Provide access to the SDK_CI_SAMPLES component, using PeopleTools security.

2. Select PeopleTools SDK, PeopleTools SDK, Use, SDK CI Samples.

3. Search for and select an employee ID.

Testing the SDK_BUS_EXP Component Interface

To test the SDK_BUS_EXP component interface:

1. View the component interface definition through the PeopleSoft Application Designer.

2. Test the component interface definition, using the component interface tester.

Using the Component Interface SDK Sample in Java and C+ +

This section describes how to use the component interface SDK sample in Java and C++.

Understanding using the Component Interface SDK Samples in Java and C++

The component interface sample programs for Java and for C++ are provided as part of the component interface SDK and follow the same sequence of options. The source files are located in <PS_HOME>\sdk\pscompintfc\src\<java or c++>\samples\sdk_bus_exp.

Building the Component Interface SDK Sample (Java)

The component interface sample program for Java is provided as part of the component interface SDK, located in <PS_HOME>\sdk\pscompintfc\src\java\samples\sdk_bus_exp.

The Java source code for the sample is in the following file: sdk_bus_exp.java

Before you run the sample, you must build the APIs and set up the Java environment.

To build the Java component interface sample:

1. Set your java classpath to include the external API classes you already built and the psoa.jar library delivered under <PS_HOME>\class\psjoa.jar

2. Compile the source using javac sdk_bus_exp.java

Building the Component Interface Sample (C++)

The component interface sample program for C/C++ is provided as part of the component interface SDK, located in <PS_HOME>\sdk\pscompintfc\src\cpp\samples\sdk_bus_exp.

The C++ source code for the sample is in the following file: sdk_bus_exp\sdk_bus_exp.cpp

Before you run the sample, you must build the APIs and set up the C++ environment. To build the C++ component interface sample:

1. Open the sdk_bus_exp workspace in the Microsoft Visual C++ editor.

2. Build the project by selecting Build, Rebuild All.

Running the Component Interface SDK Sample in Java and C++

To run the compiled Java or C++ component interface sample:

1. In a DOS window, change directories to the location of the sdk_bus_exp directory.

   After you launch the executable sdk_bus_exp, the system prompts you for parameters one at a time.

2. At each prompt, enter the appropriate value and press Enter.

   Select option 1 to sign in. You are then prompted to provide the connect information.

   If the connect succeeds, a menu appears where you can perform Get or Find functions.

3. Get details for an employee.

   Select option 1 to get details for an employee. You are then prompted with the different update modes and the employee ID for which you want to display information. Enter the employee ID 8001 and press Enter. This displays the level 0 data and the options that you can perform.

4. Select a business expense period at collection level 1.

   Select option 8, Item, to select a business expense period. Selecting this option displays a list of available business expense periods for the selected employee.

   Select the expense period that you want to work with.

5. Select a business expense detail item at collection level 2..

   Select option 18, Item, to select a business expense detail within the selected business expense period. Selecting this option displays a list of available business expense details within the selected business expense periods.

Interpreting the Code for the Component Interface SDK Sample (Java)

The following discussion refers to the Java sample program, sdk_bus_exp.java. (The code has been edited for length.) It explains the runtime options shown above.

1. Import all the required classes:

   The code example shows how to import the required classes:

   package sdk_bus_exp;
   import java.io.*;
   import java.util.*;
   import psft.pt8.joa.*;
   import PeopleSoft.Generated.CompIntfc.*;
   public class sdk_bus_exp {
   .....

2. Declare all the required objects.

   Only one active period and one active detail record are possible at any time. Users are prompted to select the needed values if they are not active.

   Collection Object	Level	Item Object for Collection
   oSdkBusExpCollection	Root (SDK_BUS_EXP)	oSdkBusExp
   oSdkBusExpPerCollection	Level 1 (SDK_BUS_EXP_PER)	oSdkBusExpPer
   oSdkBusExpDtlCollection	Level 2 (SDK_BUS_EXP_PER_DTL)	oSdkBusExpDtl

   In addition, the CompIntfPropInfoCollection object is used to access the structure of a component interface. It is not specific to a component interface.

3. Declare the PeopleSoft session object.

4. Connect to the application server.

5. Instantiate the component interface.

6. Perform a Get or Create to access the component interface.

   You must provide the keys to access the record that you want to modify.

7. Use the appropriate methods to access the component interface properties.

   There are standard methods and user-defined methods defined for the session, the component interface, and the component interface collections.

   The executeMethod function is used to invoke a method specified as a function parameter (nMethodIn).

The component interface Java SDK sample has 25 options:

Options 1 through 4 and options 6 through 25 are similar in behavior to those described in PeopleTools 8.52: PeopleCode API PeopleBook for a component Interface and its collections.

Option 5, InsertBusExpDtlDefaults, is the user-defined method of the SDK_BUS_EXP component interface. This method is defined in PeopleCode inside the component interface definition.

The logic used in the corresponding options of these collections is identical.

See Component Interface Classes.

This is the main method. It performs such functions as starting the session, getting the component interface, and disconnecting:

public static final void main(String[] args)System.out.println("  ");
System.out.println("\t 1) Sign In  ");
System.out.println("\t q) Quit ");
System.out.println("  ");
System.out.print("Command to execute (1, q) [1]: ");
charTemp = readCharacter();
switch (charTemp) {case 'q':case 'Q':.....
disconnectFromAppServer();
return;
default:
getConnectParameters();
if (connectToAppServer()) {
oSdkBusExp = (ISdkBusExp) oSession.getCompIntfc(m_strCIName);
while (getKeyType()) {
methodInt = selectMethod();
while (methodInt != 0) {
executeMethod(methodInt);
if (methodInt == 2) {
methodInt = 0;
} else {
methodInt = selectMethod();
.....

Interpreting the Code for the Component Interface SDK Sample (C++)

The following listings of code are taken from the C++ sample program, sdk_bus_exp.cpp. (The code has been edited for length.)

1. Include all the headers.

   #ifdef PS_WIN32
   #include "stdafx.h"
   #endif
   #include "cidef.h"  
   #include "apiadapterdef.h" 
   #include "PSApiExternalLib.h"  
   #include "PSApiAdapterInter.h"
   #include "PeopleSoft_PeopleSoft_i.h" 
   #include <stdio.h> #include <stdlib.h>
   #include <iostream.h> 
   #include <wchar.h>

2. Declare the PeopleSoft session handle.

   HPSAPI_SESSION hSession;

3. Declare all the required objects. Only one active period and one active detail record are possible at any time.

   Collection Object	Level	Item Object for Collection
   hSdkBusExpCollection	Root (SDK_BUS_EXP)	hSdkBusExp
   hSdkBusExpPerCollection	Level 1 (SDK_BUS_EXP_PER)	hSdkBusExpPer
   hSdkBusExpDtlCollection	Level 2 (SDK_BUS_EXP_PER_DTL)	hSdkBusExpDtl

   Collection ObjectLevelItem Object for CollectionhSdkBusExpCollectionRoot (SDK_BUS_EXP)hSdkBusExphSdkBusExpPerCollectionLevel 1 (SDK_BUS_EXP_PER)hSdkBusExpPerhSdkBusExpDtlCollection Level 2 (SDK_BUS_EXP_PER_DTL)hSdkBusExpDtl

The function executeMethod is used to launch the appropriate method depending upon the user input (nMethodIn).

The component interface C++ SDK sample has 25 options:

SDK Option1 through 5 SDK_BUS_EXP_PER collection.6 through 25SDK_BUS_EXP_DTL collection

Options 1 through 4 and options 6 through 25 are similar in behavior to those described in PeopleTools 8.52: PeopleCode API PeopleBook for a component Interface and its collections.

Option 5, InsertBusExpDtlDefaults, is the user-defined method of the SDK_BUS_EXP component interface. This method is defined in peoplecode inside the component interface definition.

The logic used in the corresponding options of these collections is identical.

See Component Interface Classes.

Using the Component Interface SDK COM Excel Sample

The component interface sample program for Microsoft Excel is provided as part of the component interface SDK, located in <PS_HOME>\sdk\pscompintfc\src\com\samples\vba.

The Visual Basic source code for the sample is in the following file: sdk_bus_exp.xlsm.

Before you run the sample, you must build the APIs and set up the COM environment.

Running the Component Interface SDK COM Excel Sample

When running the Microsoft Excel sample, you use the Get and Find sheet to find an employee.

To run the Microsoft Excel component interface sample:

1. Launch Microsoft Excel.

2. Open the Microsoft Excel sample spreadsheet.

   The Microsoft Excel spreadsheet is located in <PS_HOME>\sdk\pscompintfc\src\com\samples\vba\sdk_bus_exp.

3. When prompted about macros, select Enable Macros.

4. Attach PeopleSoft References to the spreadsheet.

   This example uses early bindings and hence requires attaching references to the spreadsheet. Select Tools, Macro, Visual Basic Editor from the Microsoft Excel menu. This opens the VBA editor.

   Select Tools, References from the menu. A dialog box appears, listing all the available references. Select the reference PeopleSoft_PeopleSoft.

5. Sign in to the sdk_bus_exp sample.

   Sheet 1 of the sdk_bus_exp spreadsheet is the sign-in page. Provide the connect information and press Tab to navigate out of the fields. Click Connect to establish the connection.

6. Find an employee by using the Find keys.

   The Find and Get keys are located on Sheet 2.

7. Select an employee from the list.

   Select an employee ID from the list by making the cell active and then clicking the GET selected button.

8. Get an Employee by providing the Get key.

   Enter the complete employee ID in cell B3. Press Tab to navigate out of the cell, and click Get (EMPLID). A list of all the available periods is displayed.

9. View details.

   To view the details for the listed business expense periods, click the Toggle Details button.

10. Add a new business expense period.

    Click the Insert period button. This redirects you to Sheet 3. Enter the business expense period date. Press Tab and click the Save New Period button.

11. Add a new business expense detail.

    Click the Insert Detail button. This redirects you to Sheet 3. Enter the charge date, expense code, amount, department ID, and business purpose. Press Tab, and save the new detail by clicking the Save New Detail button.

You can list the expense periods for the employee.

Understanding the Component Interface SDK COM Excel Sample Code

The following listings of code are taken from the Microsoft Excel sample program, sdk_bus_exp.xlsm. (The code has been edited for length.)

View the code by selecting Tools, Macro, Visual Basic Editor from the menu.

• Declare the PeopleSoft session object.

• List Business Expense Periods, using the Item method to get a specific item of the type SDK_BUS_EXP_PER.

• List Business Expense Details, using the Item method to get a specific item of the type SDK_BUS_EXP_DTL.

• To save a new business expense period, use the InsertItem method. This method inserts a new row and returns an item of the type SDK_BUS_EXP_PER. The item contains the properties. Set the properties and execute the Save method.

• To save a new business expense detail, use the InsertItem method. This method inserts a new row and returns an item of the type SDK_BUS_EXP_DTL. The item contains the properties. Set the properties and execute the Save method.

Using the Component Interface SDK COM ASP Sample

The component interface sample program for ASP is provided as part of the component interface SDK, located in <PS_HOME>\sdk\pscompintfc\src\com\samples\asp\sdk_bus_exp.

The ASP source code for the samples is in these files.

Before you run the sample, you must build the APIs and set up the COM environment.

Running the Component Interface SDK COM ASP Sample

When running the ASP sample, you use the Get key to find an employee.

To run the Component Interface SDK COM ASP component interface sample:

1. Install and configure the IIS web server.

2. Create a virtual directory to point to <PS_HOME>\sdk\pscompintfc\src\com\samples\asp\sdk_bus_exp.

3. Start the web server.

4. Run the SDK example through the browser.

   The web address http://machinename/sdkSDK_BUS_EXP_Signon.asp launches the SDK application.

5. Provide the connect information and click Submit.

6. Get details for an employee.

   Enter the Get key (SDK_EMPLID) and click the Get button. This lists all the business periods for the selected employee ID.

7. Update a business expense period.

   1. Click the Update button to update the business expense period.

   2. Update the expense period end date.

   3. Click the Save button.

8. Insert a business expense period.

   1. Click the Insert button to update the business expense period.

   2. Add the new expense period end date.

   3. Click the Save button.

9. Delete a business expense period.

   1. Click the Delete button to delete the business expense period. You are prompted to decide to delete the row.

   2. Click OK to confirm the delete.

   3. Click Cancel to cancel the operation

10. Update a business expense detail.

    Select a business expense period by clicking the Update button from the business expense period row.

11. Insert a business expense detail.

    1. Click the Insert button to insert a new business expense period.

    2. Enter the values for charge date, expense code, expense amount, currency code, business purpose, and department ID.

    3. Click the Save button to save changes.

12. Delete a business expense detail.

    1. Click the Delete button to delete the business expense detail.

       You are prompted to decide to delete the row.

    2. Click OK to confirm the delete.

    3. Click Cancel to cancel the operation.

You can list the expense periods for the employee:

Understanding the Component Interface SDK COM ASP Sample Code

This section discusses the ASP files that are included in the component interface SDK COM ASP. The files included are described in the following table:

SDK_BUS_EXP_DeleteBusinessExpenseDetail.asp

This ASP file deletes a specific expense detail row an allows to insert or delete expense details from existing expense periods.

To use the SDK_BUS_EXP_DeleteBusinessExpenseDetail.asp page:

1. Get the connection information forwarded from the previous page.

2. Get the key fields.

3. Get the SDK_BUS_EXP_PER collection in Sub insertBusinessExpenseDetail.

4. Get the SDK_BUS_EXP_PER collection, using the Item method.

5. Execute the DeleteItem method.

6. Execute the Save method.

SDK_BUS_EXP_DeleteBusinessExpensePeriod.asp

This ASP file deletes a specific expense period and allows to insert or delete expense details from existing expense periods.

To use the SDK_BUS_EXP_DeleteBusinessExpensePeriod.asp page:

1. Get the connection information forwarded from the previous page.

2. Get the key fields.

3. The submitted expense period is deleted.

   To view the updated SDK_BUS_EXP_PER collection, execute the Cancel method. Set the keys and execute the Get method. The function getBusinessExpensePeriods displays the business expense periods.

4. Execute the Save method.

5. Execute the Cancel method.

SDK_BUS_EXP_FUNCLIB.asp

This ASP file contains all the common functions and needs to be included in any other ASP page when you build the ASP program. It includes utility functions for checking required fields, extracting the host name to which the client connects, and confirming and submitting the user input.

SDK_BUS_EXP_GetBusinessExpenses.asp

This ASP file lists all the business expense periods for the selected employee.

To use the SDK_BUS_EXP_GetBusinessExpenses.asp page:

1. Get the connection information forwarded from the previous page.

2. Get the Key Field.

3. Set the Component Interface Get Key.

4. Get the business expense periods by executing the function getBusinessExpensePeriods.

   The function getBusinessExpensePeriods gets the business expense period, and then loops through the collection, using the Item method to get a specific business expense period. Each property in that item is then displayed.

5. The Update button is of the type submit.

   Because the form action is set to SDK_BUS_EXP_ UpdateBusinessExpensePeriod.asp, this page is launched. The Insert and Delete buttons use the JavaScript functions insertBusinessExpensePeriod() and deleteBusinessExpensePeriod().

6. Submit the page.

   Use the JavaScript function insertBusinessExpensePeriod to set the form.action to SDK_BUS_EXP_ InsertBusinessExpensePeriod.asp and submit the page.

SDK_BUS_EXP_GetSearchParameters.asp

This ASP file prompts for the Find and Get Keys. You can also set the component interface modes: Interactive Mode, Get History Items, and Edit History Items.

To use the SDK_BUS_EXP_GetSearchParameters.asp page:

1. Get the connection information forwarded from the previous page.

2. Use Sub getSearchParameters prompts the user for the Get or Find key and the component interface modes (interactive, get history items, and edit history items).

3. Use Sub getSearchParameters to call the appropriate page for Get and Find, using the JavaScript function invokeMethod().

SDK_BUS_EXP_GetSearchResults.asp

This ASP file is called if the Find option was selected.

To use the SDK_BUS_EXP_GetSearchResults.asp page:

1. Get the connection information forwarded from the previous page.

2. Get the Find keys.

3. Get the search result.

   The function getSearchResults lists all the employees for the provided Find keys by setting the Find keys and executing the Find method.

4. Loop through the collection to list all the employee IDs.

SDK_BUS_EXP_InsertBusinessExpenseDetail.asp

This ASP file enables the user to update the expense period data, as well as insert and delete business expense data. Sub insertBusinessExpenseDetail inserts a business expense detail for the selected business expense period.

To use the SDK_BUS_EXP_InsertBusinessExpenseDetail.asp page:

1. Get the SDK_BUS_EXP_PER collection in Sub insertBusinessExpenseDetail.

2. Get the SDK_BUS_EXP_PER collection, using the Item method.

3. Get the SDK_BUS_EXP_DTL collection.

4. Get the SDK_BUS_EXP_DTL using the Item method.

5. Create a form to get the properties for SDK_BUS_EXP_DTL.

6. Get the connection information forwarded from the previous page

7. Get the key fields.

8. Submit the form.

   The Save button calls the JavaScript function saveBusinessExpenseDetail, sets action of the form to SDK_BUS_EXP_SaveBusinessExpenseDetail.asp, and submits the form.

SDK_BUS_EXP_InsertBusinessExpensePeriod.asp

This ASP file enables the user to insert a new business expense period.

To use the SDK_BUS_EXP_InsertBusinessExpensePeriod.asp page:

1. Get the connection information forwarded from the previous page.

2. Get the key fields.

3. Call the insertBusinessExpensePeriod function to insert a new business expense period.

4. Get the business expense period.

5. Insert a new item into the collection.

   Use the InsertItem method is used to insert a new item in the SDK_BUS_EXP_PER collection.

   A field to enter the SDK_BUS_PER_DT is created.

6. Submit the form.

   Use the Save button to the JavaScript function newBusinessExpensePeriod. This function sets the action of the form to SDK_BUS_EXP_NewBusinessExpensePeriod.asp and submits the form.

SDK_BUS_EXP_NewBusinessExpensePeriod.asp

This ASP file enables the user to update the expense period data as well as insert and delete business expense details.

To use the SDK_BUS_EXP_NewBusinessExpensePeriod.asp page:

1. Get the connection information forwarded from the previous page.

2. Get the key fields.

3. Get the SDK_BUS_EXP_PER_COLLECTION.

   Execute the InsertItem method. Set the SDK_EXP_PER_DT property and execute the Save method.

SDK_BUS_EXP_SaveBusinessExpenseDetail.asp

This ASP file enables the user save submitted business expense details.

To use the SDK_BUS_EXP_SaveBusinessExpenseDetail.asp page:

1. Get the connection information forwarded from the previous page.

2. Get the key fields.

3. Save the business expense detail and get the SDK_BUS_EXP_PER collection.

   Using Submit saveBusinessExpenseDetails accomplishes both of these tasks. First it saves the business expense detail and then it gets the SDK_BUS_EXP_PER collection.

4. Use the Item method to get SDK_BUS_EXP_PER.

5. Get the SDK_BUS_EXP_DTL collection.

6. Get the SDK_BUS_EXP_DTL, using the InsertItem method. Set the properties.

7. Execute the Save method.

SDK_BUS_EXP_SaveBusinessExpensePeriod.asp

This ASP file enables you to update the end date of an existing expense period, and provide options to insert or delete expense details.

To use the SDK_BUS_EXP_SaveBusinessExpensePeriod.asp page:

1. Get the connection information forwarded from the previous page.

2. Get the key fields.

3. Save the business expense period for the selected employee ID and business expense period. Get the specific business expense period by using the Item method. Set the SDK_EXP_PER_DT property with the new value and execute the Save method.

SDK_BUS_EXP_Signon.asp

This section describes the behavior of the SDK_BUS_EXP_Signon.asp sample.

This ASP file enables the user to provide signon information and connect to the application server. When you provide and submit the form action, the code in SDK_BUS_EXP_GetSearchParameters.asp is invoked. When you click the Submit button, the JavaScript function checkRequiredFields() runs, which checks whether all the connect information is provided. The connection information is forwarded to the next page, using hidden fields.

SDK_BUS_EXP_UpdateBusinessExpensePeriod.asp

This ASP file enables you to update or delete expense period details data from and existing expense period.

To use the SDK_BUS_EXP_UpdateBusinessExpensePeriod.asp page:

1. Get the connection information forwarded from the previous page.

2. Get the key fields.

3. Update business expense details for the selected employee ID and business expense period

4. Get the business expense period to modify using Sub updateBuseinssExpensePeriod.

   Submitting updateBusinessExpensePeriod gets the business expense period collection. It passes PERIODNUM to the Item method to get the business expense period to be modified.

   This page also lists the business expense details, using the getBusinessExpenseDetails function.

5. Use the Save button to save the changes and submit the form.

   The Save button uses the JavaScript function saveBusinessExpensePeriod to save changes made to the business expense period. The function saveBusinessExpensePeriod sets the form action to SDK_BUS_EXP_SaveBusinessExpensePeriod.asp and submits the form.