PeopleSoft Component Interface Builder
In this topic ...
Related Topics ...
Use this builder to add an LJO to your model that can access a PeopleSoft backend system and make calls to a Component Interface. The LJO supports the following standard PeopleSoft Component Interface methods: Get, Find, Create, Save, and Cancel.
In addition, this LJO makes it possible to call user-defined Component Interface methods. The builder also adds an XML schema to your model. This schema defines the structure and the type of data we can send to and receive from the Component Interface.
This builder s functionality is incorporated into the PeopleSoft View & Form builder.
How Do I...
Establish a connection with a PeopleSoft server...
1. Specify connection properties - The builder allows you to specify connection for a PeopleSoft server in two ways. The primary way is by using a connection properties file that can be shared by multiple instances of the builder. A connection properties file must be created in web-inf/config/peoplesoft_config and filled out with the required properties. The file default_connection.properties in web-inf/config/peoplesoft_config shows that properties that are required. As an alternative to the properties file we can specify connection inputs in the "Connection Override" group of builder inputs. These overrides take precedence over any properties defined in the properties file.
2. Place the PeopleSoft JAR file -The PeopleSoft JAR file that place into web-inf/work/lib can be obtained from your PeopleSoft installation. The file will be named psjoa.jar or something similar. Once positioned, we can add a PeopleSoft builder to a model, specify the connection properties, and press the "Test Connection" button to verify that the builder can access your PeopleSoft server.
Use Component Interface Label Metadata...
Data contained in PeopleSoft Component Interfaces is identified by property names. These names are usually abbreviations of the labels that would be used for the data when displayed on a report or web page. For example, some Component Interfaces have a property called "PROP_EMPLID" which contains an "Employee ID".
When displaying Component Interface data on a web page it s best to use meaningful labels such as "Employee ID". Fortunately, PeopleSoft Component Interfaces contain label metadata that can be used to create presentable web pages and reports.
This builder contains a "Generate Label Resources" input that when enabled causes the builder to query a Component Interface for its property label metadata and construct two resource bundles that can be used by other builders, such as Data Page, to create presentable web pages. One resource bundle contains long labels while the other contains short labels. Using "PROP_EMPLID" as an example, the long-label resource bundle would contain an entry similar to "PROP_EMPLID=Employee ID". Similarly, the short-label resource bundle would contain an entry like "PROP_EMPLID=Emp ID".
1. Check the "Generate Label Resources" input of the builder.
2. Apply the builder input changes. The label resource bundles are written to web-inf/source and web-inf/classes.
3. Open the Data Page Builder that is being used to display the Component Interface data. In the Label Translation Settings group select either the long or short label resource bundle as the value for the Resource Bundle Name input.
4. Apply the Data Page changes and run your model. The displayed web page now uses the selected labels instead of the property names to identify Component Interface data.
Specifying Inputs
The PeopleSoft Component Interface builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties and HTML Attributes input groups, see "Using the Builder Call Editor."
Input Name Description Name Enter a name for this builder call. The Designer displays this name in the Builder Call List. Connection Properties File Enter the name of the properties file to be used to establish a connection with the backend PeopleSoft server. Example: my_psoft.properties
This file must be located in the WEB-INF/config/peoplesoft_config directory
Test Connection Button Press this button to test the builder's connection to the PeopleSoft server. If the connection is successful, a connection confirmation dialog is displayed. If the connection is unsuccessful,an error dialog will be displayed with information about why the builder was unable to contact the PeopleSoft server.
The connection properties are taken from the properties file defined for the builder and any overrides you specified in the "Connection Override" advanced group. If you have connection problems remember to review both inputs for correctness.
Runtime Credentials Select the type of credentials to use at runtime to access the PeopleSoft server. We can choose:
- Use same credentials properties for all users To use the user name and password credentials specified in the .properties file regardless of which user is running the PeopleSoft builder.
- Specify execution credentials To specify a user name and password that will be used by this builder at runtime to access the PeopleSoft server.
Execution User Name This input is available when "Specify Execution Credentials" is selected as the Runtime Credentials input. Specify an indirect reference to the location used to store the PeopleSoft user name. This location might be a variable or method result.
Execution Password This input is available when "Specify Execution Credentials" is selected as the Runtime Credentials input. Specify an indirect reference to the location used to store the password.
Component Interface Selection Get Component Interface Names Button Press this button to get a list of Component Interfaces that are available on the PeopleSoft server. If successful, the "Component Interface" input picker will list the available Component Interfaces.
If the operation was unsuccessful, an error dialog will be displayed with information about why the builder was unable to get the list of Component Interfaces.
If the picker does not list any Component Interfaces or you do not see the expected list of names, then the user name provided by the properties file may not have permission to access any Component Interfaces.
Component Interface Select the name of the PeopleSoft Component Interface that is to be accessed by this builder. Get History Items This input, in conjunction with the "Edit History Items" input, defines how the Component Interface (and by extension the helper LJO) handles history rows when fetching and saving data. There are several combinations of TRUE/FALSE settings we can apply:
- "Get History Items" is TRUE and "Edit History Items" is TRUE -- The LJO accesses the data in the Component Interface in Correction mode. This means all history rows are returned and we can edit/save all of these rows.
- "Get History Items" is TRUE and "Edit History Items" is FALSE -- The LJO accesses data in the Component Interface in Update/Display All mode. This means all history rows are returned when data is fetched. However, we can only edit rows with an effective date set in the future.
- "Get History Items" is FALSE -- The LJO accesses Component Interface data in Update mode. The "Edit History Items" input has no effect when "Get History Items" is FALSE and therefore is not displayed.
"Get History Items" and "Edit History Items" are standard Component Interface properties but they may not be available across all versions of the PeopleSoft access library (psjoa.jar). In some versions of the library these properties are missing. The PeopleSoft builders detect when either of these properties are not supported by the library in use and issue warnings in the Designer to alert the user of the potential problems getting and saving history rows.
Edit History Items See the description of "Get History Items" above. This input works in conjunction with the "Get History Items" input. Find Behavior This input allows you to customize the return data of the "Find" method and create search results pages based upon those "Find" results. Select the type of data to be returned by the builder when the "Find" method of the Component Interface is invoked through the builder. We can choose:
- Return key properties - The builder will return only a collection of "FindKeys" that matches the partial "FindKeys" that were provided to the "Find" method of the Component Interface. Each member of the collection can be used to get the details for a specific Component Interface instance.
- Return all properties - The builder will return a collection of Component Interface instances that contain the complete detail for each instance. This is equivalent to invoking the "Get" method for each Component Interface instance that matches the partial "FindKeys" provided to the "Find" method of the Component Interface.
- Return only top-level properties -This builder will return a collection of Component Interface instances that contain only the top-level properties of each instance. This is equivalent to invoking the "Get" method for each Component Interface instance that matches the partial "FindKeys" but omitting any collection type properties of the instances.
Enable Schema Caching Use this check box to enable the caching of the schema for the specified PeopleSoft Component Interface. When enabled, the Builder s regeneration phase uses a cached version of the Component Interface schema. If a different Component is selected a new version of the schema will be cached. Selecting this option provides two benefits:
- Enhanced Performance - This helps during editing models containing this Builder.
- Enhanced Security - A cached schema avoids exposing model generation time credentials once an initial regen has been performed. To leverage this specify to use separate runtime credentials (see the "Runtime Credentials" input).
Note - If the schema for the data changes on the PeopleSoft server, disable this input, regenerate the model, and enable this input again.
Note - If you have the "Generate Resource Labels" input checked uncheck this input to generate the resource files for the labels. Once the resource bundles are generated we can enable schema caching again, and then disable the "Generate Resource Labels" input.
Connection Override Host Server Use this input to override the "HostServer" property specified in the connection properties file. You might want to do this if we need to use a different PeopleSoft server than the one specified in the properties file (or you need to profile the selection of the PeopleSoft server).
This input is a selectable list but is initially unpopulated. The only items that appear in this list are those you have entered manually. To use this input, manually enter the name of the host server. Once entered, that name will remain in the list for the duration of the current user's session.
User name Use this input to override the "UserName" property specified in the connection properties file. You might want to do this if we need to use different credentials than the ones specified in the properties file
Password Use this input to override the "Password" property specified in the connection properties file. You might want to do this if we need to use different credentials than the ones specified in the properties file
Resource Bundle Generation Generate Label Resources Enable the check box to have the builder query a Component Interface for its property label metadata and construct resource bundles that can be used by other builders, such as Data Page, to create presentable web pages. One resource bundle contains long labels while the other contains short labels. The resource bundles are written to web-inf/source and web-inf/classes when the model is regenerated. The bundle names are created from a combination of the model name, builder name, and Component Interface name to ensure uniqueness.
the builder writes the resource bundles only if they do not already exist. This means we can manually customize the content of the bundles if we need to change one or more of the PeopleSoft provided labels for some reason.
You must disable "Enable Schema Caching" in order to generate the resource files for the labels. Once the resource bundles are generated we can enable schema caching again, and then disable the "Generate Resource Labels" input.
Specifying Credentials
You have several options when choosing the credentials used to access the PeopleSoft system at portlet execution time. We can employ the same credentials for all portlet users if you want all users to have the same user name and password. In many cases, it is desirable to have different credentials for each user. Implementing this feature varies greatly between different brands of portal server, therefore, it is best to refer to the specific portal server's documentation to learn how to implement user-specific credentials.
Objects Created by the PeopleSoft Component Interface Builder
A variety of WebApp artifacts are created by the PeopleSoft builders. These artifacts include the following LJOs, variables, and files:
Linked Java Objects
- <buildername> (helper LJO) - LJO that includes methods to invoke the various standard methods defined for a Component Interface (including Find, Create , and Cancel)
- getPSAccess (helper LJO) - Method to retrieve a PSAccess object. PSAccess has several methods to retrieve information directly from PeopleSoft.
Variables
- <buildername>_Schema - XSD schema representing the data passed to and returned from the Component Interface via the helper LJO. Child schema elements are defined for FindKeys, GetKeys, CreateKeys, FindResults, and Detail.
- <buildername>_GetKeys - This schema-typed variable holds the inputs (if any) that are used by the Get method of the Component Interface. If "Create Input Page" is selected along with "Create Detail Page", then an Input Page is generated using a Data Page Builder to generate an input form from the GetKeys schema element.
- <buildername>_FindKeys - This schema-typed variable holds the inputs (if any) that are used by the Find method of the Component Interface. If "Create Input Page" is selected along with "Create Search Results Page", then an Input Page is generated using a Data Page Builder to generate an input form from the FindKeys schema element.
- <buildername>_CreateKeys - This schema-typed variable holds the inputs (if any) that are used by the Create method of the Component Interface.
- <buildername>_Detail - This schema-typed variable is populated whenever the Get method of the Component Interface is called. This variable contains all of the detail for the Component Interface instance that corresponds to the current value of the GetKeys variable.
- <buildername>_SearchResults - This schema-typed variable is populated whenever the Find method of the Component Interface is called. This variable contains data for each Component Interface instance whose keys match the current value of the FindKeys variable.
Note : The PeopleSoft server might limit the number of search results returned by a call of the Find method. If you do not see the expected set of search results, try specifying a more restrictive set of FindKeys that returns a smaller set of matching Component Interface instances.
Files
<modelname>_<buildername>_<ciname>_long.properties - Resource bundles containing long labels for every property that can be obtained from the Component Interface (if " Generate Label Resources " is selected).
<modelname>_<buildername>_<ciname>_short.properties - Resource bundles containing short labels for every property that can be obtained from the Component Interface (if " Generate Label Resources " is selected).
PeopleSoft Session Pooling
The PeopleSoft builders support pooling of sessions to your backend PeopleSoft servers. By default session pooling is disabled which is a reasonable configuration for a Designer environment. However, on the server you may want to enable pooling to minimize the number of sessions created and improve overall builder runtime performance. See the PeopleSoft Getting Started Guide for information about the properties available to control session pooling
The PeopleSoft builders use the standard open source Apache Commons pooling implementation. See the Commons documentation for the GenericKeyedObjectPool class on the Apache web site for detailed information on the meanings of these properties.