Developing Component Interfaces

This chapter discusses how to:

• Create component interface definitions.

• Use keys.

• Set properties.

• Work with collections.

• Work with methods.

• Validate component interfaces.

• Set security options.

• Test component interfaces.

• Understand synchronization.

• Write component interface programs.

• Understand runtime considerations.

Creating Component Interface Definitions

This section discusses how to:

• Create new component interface definitions.

• Name component interface definitions.

• Associate component interface definitions with menus.

• Determine the fields to expose in component interfaces.

Understanding Creating Component Interface Definitions

This section discusses key concepts for creating component interface definitions.

Component Structure

Because each component interface refers to a single component, you must know the structure of the component for which you are constructing a component interface. You can use an existing component within an application or create a new one for the sole purpose of constructing a component interface. Many parts of the component interface, such as the keys, are created based on settings in the referenced component.

Criteria for Setting Automatic Default Properties

To be able to set automatic defaults for fields in the new component interface, the system needs the properties to be of a specific field or page control type.

The fields should be of the following types:

• Character

• Long character

• Number

• Signed number

• Date

• Time

• Datetime

The field should be one of the following page control types:

• Edit box

• Drop-down list box

• Check box

• Radio button

The field cannot be invisible and should not be the same as the key field of the immediate parent.

Collections must have at least one child property that satisfies the field or page control criteria for providing the field by default. Collections with no properties are not added.

For a field on a secondary page to be selected for the default properties process, it must satisfy all the criteria for field type and page control and must be at the same level as the host page.

Additionally, the component tree that a component interface uses to order the properties lists the fields in the record based on their order in the record definition and not the order of the fields on the page. If the component tree lists the fields of a record based on the page, the properties of the component interface will reflect that order.

Creating New Component Interfaces

This section discusses how to create a new component interface.

To create a new component interface:

1. Select File, New from the PeopleSoft Application Designer menu.

2. Select Component Interface from the New dialog box.

3. Select the component on which to base this component interface.

   After you select the appropriate component, you see a message asking whether you want the fields that are exposed in the selected component to become the default properties of the component interface.

   Note. Not all fields on the component interface can have automatic defaults created for them.

4. Click Yes to confirm the default property definitions or No if you don’t want any properties initially created.

   If you elect to have the property definitions automatically provided by the system by default, then all properties that appear on the pages of the underlying component are added to the component interface. Even though the system adds the default properties, you may need to move other properties into the component view for the component to work.

   An untitled component interface appears, showing the Get keys and Find keys. Create keys are produced only if the underlying component can run in Add mode (the example preceding this procedure does not have Create keys, because the search record of the underlying component cannot run in Add mode). PeopleSoft Application Designer generates the keys for you as you drag definitions.

   The standard methods Cancel, Find, Get, and Save are automatically created. The Create method is not automatically created unless the component supports the Add mode.

   Note. You can begin adding properties to a new component interface at any point. However, you cannot add any user-defined methods to the component interface until you have saved the component interface.

5. Save the component interface.

   After you have saved the component interface, you can further define user-defined methods.

Naming Component Interface Definitions

Like every other definition in PeopleTools, component interfaces must have unique names. The naming of component interfaces should be consistent and systematic. Also, the name should not be changed after the component interface is part of a production system—other applications depend on a consistent name with which to reference the component interface.

If you are changing the structure of a component interface such that an existing program can no longer access it correctly, create a new component interface rather than updating the existing one. No version property is on a component interface, so if you must create a new version of a delivered component interface, adhere to a standard naming guideline to avoid confusion. A suggested naming guideline is:

• LOCATION (original component interface).

• LOCATION_V2 (version two of the component interface).

Associating Component Interfaces with Menus

This applies to component interfaces built from components that are already attached to one or more menus.

To associate a component interface with a menu:

1. Select File, Open from the PeopleSoft Application Designer menu to open an existing component interface.

2. Select File, Definition Properties from the PeopleSoft Application Designer menu.

   The Definition Properties dialog box appears.

3. Select the appropriate menu name on the General tab for this component interface.

   Note. Associate a menu with a component interface only when PeopleCode is in the component that uses the %Menu system variable.

Determining the Fields to Expose in Component Interfaces

You expose fields from a component in the component interface by dragging a record field or a scroll from the component view into the component interface view. However, some forethought is required before exposing a component as a component interface. You need to have a thorough understanding of the underlying component so that you expose fields that are required in the external system. For example, if the component has a field called SSN, you need to be sure that the SSN field is required before exposing it to the external system. Expose only those properties that are necessary.

The component view displays fields that are available in the component buffer at runtime. For example, if a record containing 10 fields has only 3 fields included on a page, then the component view will list only those 3 fields.

The first time that you drag a scroll from the component view to the component interface view, the system uses the following rules to determine what properties to expose:

• Keys are exposed only at the highest-level collection in which they first appear.

  In some cases, this is not appropriate. When an effective-dated component that has the same level-zero and level-one record is exposed through a component interface, it should be exposed the same way in which it appears on a page in the component. In this case, only one key field typically appears at level zero and the effective-date keys appear at level one. The component interface wrapper should expose the page in the same fashion—removing keys that do not appear in the level-zero scroll from the component interface top-level collection and manually adding keys that appear in level-one scroll to the second-level collection.

  Typically, you do not want to expose Get keys or Create keys as properties, because these are set before a Get or Create operation and might be inadvertently changed.

• Make sure that you do not delete all the properties within the collection; that would result in an empty collection. If such empty collections exist, remove them; otherwise, they appear with X in the component interface view.

• If your page does not support Add mode, then you should not expose the level-zero record of the component, because it contains data that is not specific to the component interface that you are creating.

• Do not expose fields that are not visible in the component view.

  The component optimization code might eliminate unused fields from its buffers, which results in an error when that field is accessed by the component interface.

Using Keys

This section discusses how to add and delete keys.

Understanding Keys

The following table shows the three types of component interface keys:

Keys are created automatically when you create a component interface. Typically, you must manually add keys only if new search key fields are added to the underlying component after the creation of the component interface. However, you might want to modify the Find keys—either to restrict a user from searching on a particular key or to add an alternate search key that didn’t exist when the component was created.

Component interface keys are based only on the search key fields and alternate search key fields that are designated as list box items in the search record of the underlying component. When you create the component interface, the keys are automatically generated from all key fields that qualify.

• Each search key field produces a Get key and a Find key.

• Each search key field also produces a Create key if the underlying component allows Add mode.

• Each alternate search key field produces a Find key.

Valid Conditions for Modifying Keys

The following conditions are valid for modifying keys.

• You can add or delete a Find key if it is based on an alternate search key field.

• You can add any type of key based on a qualifying search key field in the component, if it isn’t already the basis of an existing key of the same type.

  This is necessary only if a new search key field is added to the component after you create the component interface.

• You can delete any type of key if its underlying search key field meets one of these criteria:

  • It is no longer defined as a search key field.

  • It is no longer designated as a list box item.

  • It has been deleted from the component.

Note. An X icon precedes a name in the component interface view if the field underlying a component interface key no longer qualifies as a key. Remove keys (or any other properties) that are marked with this symbol to ensure proper operation of the component interface.

Adding and Deleting Keys

To add a key:

1. Expand the search key collection (the first collection) in the component view.

2. Drag the key to the component interface view.

To delete a key:

1. Select the key in the component interface view.

2. Press the Del key.

Setting Properties

This section provides an overview of standard properties and discusses how to:

• Create user-defined properties.

• Delete user-defined properties.

• Rename user-defined properties.

• Create reference properties.

• Make properties read-only.

Understanding Standard Properties

Standard properties do not appear in the component interface view in PeopleSoft Application Designer. The following tables name and define the standard properties, and list the interfaces for PeopleCode, Java, C++, and Visual Basic.

This table contains the component interface properties:

The CompIntfPropInfoCollection object supports the following properties:

Example of PropertyInfoCollection

Here is a Java example that calls PropertyInfoCollection:

IcompIntfcPropertyInfoCollection oLO_PropInfoColl
IcompIntfcPropertyInfo oLO_PropInfoItem
 
oLO_PropInfoColl = oCI.getPropertyInfoCollection();
for (int I=0; I < oLO_PropInfoColl.getCount(); I++) {
   oLO_PropInfoItem = oLO_PropInfoColl.item(i);
   
   System.out.println("\t Name = " + oLO_PropInfoColl.getName());
   System.out.println("\t Record Name = " + oLO_PropInfoColl.getRecordName());
   System.out.println("\t Field Name = " + oLO_PropInfoColl.getFieldName());
   System.out.println("\t Label Long = " + oLO_PropInfoColl.getLabelLong());
   System.out.println("\t Label Short = " + oLO_PropInfoColl.getLabelShort());
   System.out.println("\t IsCollection = " + oLO_PropInfoColl.getIsCollection());
   System.out.println("\t Type = " + oLO_PropInfoColl.getType());
   System.out.println("\t OAType = " + oLO_PropInfoColl.getOAType());
   System.out.println("\t Format = " + oLO_PropInfoColl.getFormat());
   System.out.println("\t Is Get Key? = " + oLO_PropInfoColl.getKey());
   System.out.println("\t Is Required = " + oLO_PropInfoColl.getRequired());
   System.out.println("\t Is Xlat? = " + oLO_PropInfoColl.getXlat());
   System.out.println("\t Is Yesno? = " + oLO_PropInfoColl.getYesno());
   System.out.println("\t Prompt = " + oLO_PropInfoColl.getPrompt());
   System.out.println("\t Length = " + oLO_PropInfoColl.getLength());
   System.out.println("\t DecimalPosition = " + oLO_PropInfoColl.
      getDecimalPosition());
   System.out.println("\t Is Read Only? = " + oLO_PropInfoColl.
      getIsReadOnly());
   System.out.println("\t Is Alt Key? = " + oLO_PropInfoColl.getAltkey());
   System.out.println("\t Is ListBox item? = " + oLO_PropInfoColl.
      getListboxitem());

Object Adapter

The name of the property is OAType, and it holds the value of the object adapter type. Exposing this property and supplying the associated methods enables you to detect possible data type mismatches between the database and the component interface object.

The Java methods are:

For example:

public static void printPropertyType(String propName, ICompIntfcPropertyInfo i⇒
PropertyInfo) {
        
String strOAType = null;
String strDBType = null;
        
    try {
        switch ((int)iPropertyInfo.getOAType()) {
            /* Object Adapter Type == 0 */
            case CIPropertyTypes.PSPROPERTY_OA_TYPE_BOOL:
                    strOAType = "BOOL";
                    break;
             /* Object Adapter Type == 1 */
             case CIPropertyTypes.PSPROPERTY_OA_TYPE_NUMBER: 
                    strOAType = "INTEGER";
                    break;
             /* Object Adapter Type == 2 */
             case CIPropertyTypes.PSPROPERTY_OA_TYPE_FLOAT: 
                    strOAType = "FLOAT";
                    break;
             /* Object Adapter Type == 3 */
             case CIPropertyTypes.PSPROPERTY_OA_TYPE_STRING: 
                    strOAType = "STRING";
                    break;
            }
            
        switch ((int)iPropertyInfo.getType()) {
            /* Database Type == 0 */
            case CIPropertyTypes.PSPROPERTY_DB_TYPE_CHARACTER: 
                    strDBType = "CHARACTER";
                    break;
            /* Database Type == 1 */
            case CIPropertyTypes.PSPROPERTY_DB_TYPE_LONG_CHARACTER: 
                    strDBType = "LONG_CHARACTER";
                    break;
            /* Database Type == 2 */
            case CIPropertyTypes.PSPROPERTY_DB_TYPE_NUMBER: 
                    strDBType = "NUMBER";
                    break;
            /* Database Type == 3 */
            case CIPropertyTypes.PSPROPERTY_DB_TYPE_SIGNED_NUMBER:
                    strDBType = "SIGNED NUMBER";
                    break;
            /* Database Type == 4 */
            case CIPropertyTypes.PSPROPERTY_DB_TYPE_DATE:
                    strDBType = "DATE";
                    break;
            /* Database Type == 5 */
            case CIPropertyTypes.PSPROPERTY_DB_TYPE_TIME:
                    strDBType = "TIME";
                    break;
            /* Database Type == 6 */
            case CIPropertyTypes.PSPROPERTY_DB_TYPE_DATETIME: 
                    strDBType = "DATETIME";
                    break;
            }
            
        }
        catch (Exception e) {
            e.printStackTrace();
        }

        System.out.println("\n" + propName + 
             " Object Adapter Type is:  " + strOAType +
             ", Database Type is:  " + strDBType);
    }

Component Interface Collection Property

This table contains the component interface collection property Count.

Data Item Property

This table contains the data item property ItemNum:

Note. The component interface classes contain information about PropertyInfo properties and related PeopleCode.

Creating User-Defined Properties

User-defined properties are those properties on the underlying component that are exposed through the component interface. User-defined properties are derived from the component to which the component interface is associated and must be added manually. They are the specific record fields that you expose to an external system with the component interface. You create user-defined properties in addition to the standard properties to enable data manipulation of the component. When you create a new component interface, if you accept the default properties, user-defined properties are created automatically for each field displayed to the user on the underlying component.

User-defined properties are the points where the component and the underlying database are exposed to the external system. This is the means that component interfaces use to add or change fields and data in the database.

To create a user-defined property, drag a record, field, or scroll from the component view to the component interface view.

Where you insert the definition in the component interface view does not matter. When the component interface is opened, the system automatically converts the field or record into a component interface property and places it in the appropriate place in the list of properties. Also, when you drag a definition from the component view into the component interface view, all child definitions are brought into the component interface automatically. After these child properties are added to the component interface, you can remove each property individually, if desired.

Dragging a key from the search records, which precede the level-zero record in the page view, adds a key to all appropriate key collections (Get, Create, and Find) in the component interface. Because appropriate keys are added automatically when a component interface is first created, you typically must add keys only if the new keys are added to the underlying component after the creation of the component interface.

Deleting User-Defined Properties

To delete a property:

1. Select the property to be deleted.

2. Either press the Del key on the keyboard, or right-click the key and select Delete.

   Standard Windows behavior is employed for selecting multiple properties using the Shift and Ctrl keys.

Renaming User-Defined Properties

Property names are automatically generated according to the corresponding fields from the component. If these names are cryptic, you might want to rename these properties to explain them better. Renaming a property does not change the field that the property references.

Important! PeopleSoft Mobile Agent is a deprecated product. The options listed in the Mobile Property Persistence group box of the Edit Property dialog box exist for backward compatibility only.

To rename a property:

1. Double-click the property name or right-click the property name and select Edit Name from the menu.

2. Enter the new property name.

   Programs accessing this component interface must reference the new property name. For example, if SDK_NAME was changed to NAME, programs must use NAME instead of SDK_NAME.

3. Add any comments that might be helpful.

4. Select the Read-Only check box to make this property read-only.

5. If this property is for a mobile application, select a radio button that sets the persistence of the property.

   • Send Updates is the default behavior for a mobile property.

     Any changes or additions to this property on a mobile instance are synchronized to the server.

   • If a mobile property is set to Do not Send Updates, this property is not synchronized up to the server, but the value is maintained on the device.

   • A Derived property is used only at mobile runtime. Any values that are set or added to this property exist only for the runtime life of the object. No persistence of this data on the device exists, so it is subsequently never uploaded to the server.

Note. PeopleSoft Application Designer generates an error message if it detects that a component interface has properties that resolve to the same name when creating, saving, or opening a given component interface.

For example, NAME1 and NAME_1 both resolve to the same name when PeopleSoft APIs are built. The set and get functions that are generated for the properties RTE_CNTL_TYPE1 and RTE_CNTL_TYPE_1 are:

public String getRteCntlType1()

public void setRteCntlType1(String inRteCntlType1)

This results in a compile error. To fix this condition, name the properties so that they do not resolve to the same name.

Creating Reference Properties

Each component interface is isolated and unaware of the other component interfaces in the system. To access and update information from other component interfaces, references establish relationships between component interfaces.

Create a reference property in one component interface to access data exposed in another component interface. For example, the Customer object and the component interface exposing its properties include properties such as the customer’s name, address, and telephone numbers. Another object, Contact, includes data associated with all contacts in the system. The link between a specific customer and its associated contacts is owned by the Contact record, not the Customer record.

Therefore, to access contact data, the Customer component interface needs a reference property referring to the Contact component interface. For you to update contact data from the Customer component interface, the reference must include a valid reference path and reference backpointer to the customer ID.

Access the Create Reference dialog box by right-clicking the property and selecting Create Reference.

The Create Reference dialog box has the following fields:

Making Properties Read-Only

You can make any property read-only. At runtime, the value of a read-only property can be read but not updated.

To make a property read-only:

1. Select the property.

2. Select Edit, Toggle Read Only Access from the PeopleSoft Application Designer menu.

   A Y appears in the Read Only column of the component interface view corresponding to each property that you selected to be read-only.

Note. You can double-click the icon of any existing user-defined property to edit its name or comment or to toggle read-only access.

Working with Collections

A collection is a property that points to a scroll, rather than a field, in the underlying component for a component interface. A collection groups multiple fields in a scroll. All the fields in the scroll are mapped to a property. These properties are part of the collection.

You create collections the same way you create properties—drag the scroll from the component view into the component interface view. Consider these points when creating collections:

• When you drag a scroll into the component interface view, all child scrolls come with it.

  This is the same behavior that you would expect when creating a property. Child properties are always added automatically when you drag a field from the component view to the component interface view. After the property or collection has been created, you can delete individual child properties or collections manually, if necessary.

• When you drag a scroll into the component interface view, all record fields contained in that scroll come with it—not just those from the record that defines the scroll.

  The fields from all records at that scroll level are exposed as part of the same collection.

• Keys that appear in parent and child scrolls are not added to child collections.

  For the component interface to function as expected, the keys must remain synchronized at all levels of the component. Having keys at lower levels makes compromising this synchronization possible. Therefore, lower-level keys are not introduced into the component interface and are not exposed to the user because those keys have already been set at the parent level.

• When you drag a child scroll into the component interface view, parent collections are created automatically.

  For example, if you drag just the level-two scroll from the component view into the component interface view, a level-zero collection and a level-one collection are created automatically in the component interface. This hierarchy of collections is necessary so that you can navigate to the child collection at runtime.

Working with Methods

This section provides and overview of session functions and methods, standard methods and collection methods. This section also discuses how to:

• Enable and disable standard methods.

• Create user-defined methods.

• Export user-defined methods.

Understanding Session Functions and Methods

The session functions and methods connect to a session on an Application server. This connection must be made before you can use the component interface methods.

Component Interface Session Functions

This table contains the component interface session function createSession:

Component Interface Session Methods

This table contains the component interface session methods:

Understanding Standard Methods

A method is a definition that performs a specific function on a component interface at runtime. Each standard method is added by default when the component interface is created and is available in PeopleCode and other programming languages. Like properties, methods are saved as part of a component interface definition. Two main types of methods are available: standard methods and user-defined methods.

By default, each component interface is created with four standard methods—Cancel, Find, Get, and Save. Additionally, the Create standard method is generated if Create keys have been added to the component interface.

Example for GetPropertyInfoByName

The GetPropertyInfoByName method returns an object containing the property information. Here is a Java example that calls GetPropertyInfoByName:

IcompIntfcPropertyInfo oCompIntfcPropertyInfo
oCompIntfcPropertyInfo = oCI.getPropertyInfoByName(tempName);
System.out.println(oCompIntfcPropertyInfo.getName());
if (!oCompIntfcPropertyInfo.getIsCollection()) {
  System.out.println("\t Format = " + oCompIntfcPropertyInfo.getFormat());
    System.out.println("\t Type = " + oCompIntfcPropertyInfo.getType());
}
System.out.println("\t Is Required = " + oCompIntfcPropertyInfo.
   getRequired());
System.out.println("\t Is Collection? = " + oCompIntfcPropertyInfo.
   getIsCollection ());
System.out.println("\t Is Read Only? = " + oCompIntfcPropertyInfo.
   getIsReadOnly());
System.out.println("\t Is Get Key? = " + oCompIntfcPropertyInfo.getKey());
System.out.println("\t Label Long = " + oCompIntfcPropertyInfo.
   getLabelLong());
System.out.println("\t Label Short = " + oCompIntfcPropertyInfo.
   getLabelShort());
System.out.println("\t Length = " + oCompIntfcPropertyInfo.getLength());
System.out.println("\t Name = " + oCompIntfcPropertyInfo.getName());
System.out.println("\t Is Xlat? = " + oCompIntfcPropertyInfo.getXlat());
System.out.println("\t Is Yesno? = " + oCompIntfcPropertyInfo.
   getYesno());

Note. When creating a new component interface, you must save the component interface before the standard methods are created. PeopleSoft Application Designer adds the standard methods upon the first save of a new component interface.

Understanding Collection Methods

The first item in a component interface collection is always indexed as item 1 from PeopleCode and COM programs, which is consistent with other PeopleCode processing. From Java and C++ programs, this item is indexed as item 0.

Component Interface Collection Properties

This table contains the component interface collection properties:

Enabling and Disabling Standard Methods

You can control whether standard methods are accessible at runtime.

To enable or disable standard methods:

1. Select File, Definition Properties from the PeopleSoft Application Designer menu.

   The Definition Properties dialog box appears.

2. Select the Standard Methods tab.

   You can enable or disable any of the standard methods selecting the corresponding check box. Doing so determines whether the method is available at runtime when the component interface is accessed. The Create option is available only if the component interface has Create keys.

Creating User-Defined Methods

This section discusses how to create user-define methods.

To create a user-defined method:

1. Right-click anywhere in the component interface view.

2. Select View PeopleCode from the menu.

   The PeopleCode editor appears. If you are using a new component interface, no PeopleCode will appear in the editor because no user-defined methods have been created.

3. Write the required PeopleCode functions.

   PeopleCode functions that you write are stored in a single PeopleCode program that is attached to the component interface and associated with the Methods event.

   Note. New user-defined methods do not appear in the list of methods until you save the component interface. Double-click the icon of any existing user-defined method to return to this PeopleCode program.

4. Set permissions for the methods that you created.

   You must set permissions for every user-defined method. If you set permission to Full Access, at runtime that function is exposed to external systems as a method on the component interface object.

Exporting User-Defined Methods

If you want a user-defined component interface to be exportable, meaning used by code that instantiates the component interface, the method PeopleCode definition must include a Doc statement. It is in the form of:

Doc <documentation for method>

where <documentation for method> describes what the method does

For example, the following method returns true if foo is positive; otherwise, it returns false.

Function MyFooBar(int foo) returns boolean
Doc
if (foo >0) then
return True;
else
return False;
end-if;
end-function;

Validating Component Interfaces

Validation ensures that the structure of a component interface is still valid. Over time, the structure of a component interface can become invalid due to component structural changes and modifications. For example, this can happen whenever a component deletes or adds a record or field. It can also happen if the keys on the component are added or removed. Properties and keys that no longer synchronize with their associated components are marked with an X icon.

Note the following points about validating component interfaces:

• PeopleSoft Application Designer also validates each component interface upon its creation.

• The validation process determines only whether the underlying component of a component interface has changed. It does not validate the PeopleCode that is associated with a component interface. To validate the PeopleCode, open the component and select Tools, Validate from the PeopleSoft Application Designer menu.

• If a component interface definition becomes invalid, you cannot save changes to it in PeopleSoft Application Designer.

• If a component interface definition is associated with an active Integration Broker service, you cannot delete it.

To correct an invalid component interface, you might have to delete properties for which appropriate fields or records no longer exist. If the structure of the source component has changed, you might have to delete old properties and re-add the new properties in their appropriate locations. You may also need to rename a property or collection.

To validate a component interface:

1. Open the component interface in PeopleSoft Application Designer.

   Validation occurs automatically whenever you open a component interface in PeopleSoft Application Designer.

2. Select Tools, Validate for Consistency from the PeopleSoft Application Designer menu to validate an open component interface.

   As you change components or other related definitions, you should validate a component interface that is already open in PeopleSoft Application Designer.

Setting Security Options

After creating a component interface, you must set security for it. Each individual method also needs to be provided security. Security for the component interface is provided through the PeopleSoft Internet Architecture pages. Component interface permissions are set at the permission list level in PeopleSoft security.

To set up component interface security:

1. Sign in to the PeopleSoft Pure Internet Architecture through the browser, and select PeopleTools, Security, Permissions & Roles, Permission Lists.

2. Select the permission list for which you want to set security.

   The Permission List component appears.

3. Access the Component Interfaces page.

4. Select the component interface for which you want to set security.

   To add another component interface to the list, click the Add button.

5. Click Edit.

   The Component Interface Permissions page appears, showing all of the methods (both standard and user-defined) in the component interface and their method of access.

6. Set the access permission for each method.

   Select Full Access or No Access. You must grant full access to at least one method to make the component interface available for testing and other online use.

7. Click OK when you are done.

8. Save the page.

Testing Component Interfaces

After setting the security for a component interface, you can test the contents and behavior using the component interface tester. You should test the component interface before using it in your external system. This proactive tool helps you discover problems with the underlying component or the component interface itself, including user-defined methods. When you are testing a component interface, real data from the database is used. Therefore, if you save the information that you change by calling the Save method, the information is changed in the database.

With the component interface tester, you can:

• Test the component interface in interactive mode.

• Retrieve history items.

• Test the standard, custom, and collection methods.

Searching Component Interfaces to Test

To test the component interface, you search for the component interface to test, and then you test it.

Access the Component Interface Tester search dialog box:

To search for a component interface to test:

1. Open the component interface in PeopleSoft Application Designer.

2. Select Tools, Test Component Interface from the PeopleSoft Application Designer menu.

   The Component Interface Tester search dialog box appears. This dialog box displays the keys (in the left-hand columns) for getting, creating, or finding an instance of the component interface. The right-hand columns provide a place for you to enter sample key values for testing.

3. Enter key values.

   1. Double-click the column to the right of any displayed keys.

   2. Enter the value in the right-hand column.

      The data that is used for the test corresponds to the key values that you enter here. In the preceding example, we have entered an employee ID of 6602.

Getting Existing Records by Using Partial Keys

If you want to retrieve a partial key, click the Find button on the Component Interface Tester page. The Find Results dialog box appears:

You can choose the specific instance by selecting and clicking the Get Selected button. If you do not enter a partial key before clicking Find, all key values in the database are returned (subject to the maximum count of 300, just as when online). This is the same as calling the Find method through the component interface API, followed by selecting a value from the Find results, setting the Get key, and calling the Get method. After you click the Get Selected button, the Component Interface Tester dialog box appears.

Testing Component Interfaces

After you have searched for and retrieved the component interface, the Component Interface Tester dialog box appears.

Testing Component Interface Properties

From the Component Interface Tester dialog box, change the value of a property, double-click a value, and enter a new value. Some basic validation is done when you leave the field, which is equivalent to leaving a field using the Tab key in the online case. This validation includes system edit, FieldChange PeopleCode events, and FieldEdit PeopleCode events. Further validation can be done when the Save method is called (SaveEdit, SavePreChange, Workflow, and SavePostChange). If errors occur or warnings are encountered, messages are displayed in the Error Message Log area at the bottom of the window. The error message log displays the same text that would appear in the PSMessages collection of the Session object if you accessed the component through the Component Interface API.

Testing Component Interface Methods

Test component interface methods by right-clicking the component interface name.

A menu appears that shows the Save and Cancel standard methods and any user-defined methods that exist for the component interface. The Find, Create, and Get standard methods are not valid for an instantiated component, and therefore are not shown.

If a component interface method requires one or more parameters, a dialog box in which you can enter the parameters appears. After the method is executed, the same dialog box appears again, displaying changes to the parameters that were caused by the method. The return value of the function appears in the title of the dialog box. If a component interface requires no parameters, you do not see the initial dialog box, but you do see the return value dialog box following the function call.

Note. Because running a component interface method can result in a change to the component interface structure, PeopleSoft Application Designer always redraws the component interface tree in its collapsed form following a method call.

Testing Collection Methods

Test collection methods by right-clicking the collection name.

A menu appears that shows the standard collection methods. Select the collection method that you want to test for this component interface. After you select a collection method to test, the Enter parameters dialog box prompts you to enter an item number for the collection method that you are testing. The value that you enter for index [Number] is used to retrieve, insert, or delete an item, according to the following rules.

After you enter an index number, the result appears in the dialog box. If a return value is sent, it is displayed in the title bar. Otherwise, the message No value is displayed. Click OK or Cancel to dismiss the dialog box.

Collection Method Rules

This table contains the collection method rules:

Note. Component interface classes contain information about collection methods.

Determining ItemByKeys Parameters

You can get the signature for the ItemByKeys method (or any other method) when testing a component interface. This is helpful for the ItemByKeys method, because its signature is different for each component interface.

To determine ItemByKeys parameters:

1. Open the definition.

2. Select Tools, Test Component Interface.

3. Find or get an appropriate populated component interface.

4. Navigate to the appropriate collection.

5. Right-click, and select ItemByKeys from the menu.

   A dialog box appears, showing the specific parameters and types and the order in which you should call ItemByKeys.

   In the preceding example, the keys for the SDK_BUS_EXP_PER ItemByKeys method are SDK_EMPID (String) and SDK_EXP_PER_DT (String).

Understanding Synchronization

The Component Interface Properties Synchronization tab is used with PeopleSoft Mobile Agent.

Important! PeopleSoft Mobile Agent is a deprecated product. The Component Interface Properties Synchronization tab exists for backward compatibility only.

PeopleSoft Mobile Agent extends the functionality of PeopleSoft Pure Internet Architecture to disconnected mobile devices, enabling users to continue working with their PeopleSoft applications on a laptop computer or personal digital assistant (PDA) while disconnected from the internet or local network.

Writing Component Interface Programs

The following chapters in this PeopleBook describe how to write component interface programs in several programming languages.

Also, the PeopleTools PeopleCode Reference contains a chapter that describes the component interface classes, including detailed instructions on the life cycle of a component interface and how to implement a component interface program in PeopleCode. You can use this information to help design your component interface program in other programming languages.

See Component Interface Classes.

Understanding Runtime Considerations

In many ways, accessing a component interface is functionally equivalent to working with an online component. However, some important differences exist between component interfaces and components. This section describes how those differences affect interactive operation, functionality designed for graphical interfaces, client versus server operation, and several miscellaneous situations. These considerations, unless otherwise noted, apply to all the programming languages listed in this manual.

General Considerations

This section discusses general considerations for component interface programs.

WinMessage Unavailable

You cannot use the WinMessage API in a component that will be used to build a component interface. Use the MsgGet() function instead.

Email from a Component Interface

To use a component interface to send email, use the TriggerBusinessEvent PeopleCode event, not SendMail.

Related Display

Related display fields are not available for use in a component interface because they are not held in the buffer context that the component interface uses.

Row Inserts

If row insert functionality has been disabled for a page, you must take care when calling inserts against the corresponding component interface. Any PeopleCode associated with buttons used on the page to add rows will not be invoked by the component interface when an insert is done.

Note. If a component has logic that inserts rows on using the RowInsert event, the component interface cannot identify the change and locate the rows that were inserted by the application code. Generic interfaces such as Excel to Component Interfaces utility and the WSDLToCI will not function correctly when using this type of dynamic insert.

Custom Field Formats

Custom field formats that are defined dynamically via Peoplecode are not enforced by component interfaces, as they are evaluated by the page processor and not available to the component interface processor. Only the static formats defined in the Application Designer will be applied.

Scope Conflicts

This section discusses scope conflicts for component interface programs.

Infinite Processing Loops

A component interface should not call itself in any of the PeopleCode included within its component definition, because this may result in an infinite loop of the component interface. A component interface also should not call itself from a user-defined method.

Multiple Instances of a Component Interface

Because of potential memory conflicts, COM or C++ applications should not create multiple, simultaneous instances of the same component interface, either within a single procedure, or in both a parent and a child procedure.

Interactive Mode

This section discusses interactive mode considerations for component interface programs.

UNIX Server Performance

If you are using a component interface as part of a batch process in which thousands of rows are being inserted, running in interactive mode may reduce performance enough on some UNIX servers to produce a connection failure. Prevent this by setting the InteractiveMode property to False.

Hidden Edit Validation Errors

If the InteractiveMode property is set to True, and if a transaction sets a property to a value that isn't allowed in a prompt edit field, the edit field value is reset back to its original value. The error is logged in the PSMessages collection; however, the Save method runs without errors. Check the value of both the Save method and the collection ErrorPending property to discover all of the errors.