10g (9.0.4)
Part Number B10298-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle® Application Server Integration Adapter for PeopleSoft 8 User's Guide 10g (9.0.4) Part Number B10298-01 |
|
This chapter provides information about the Component Interface standard and user-defined interactions for Oracle Application Server Integration Adapter for PeopleSoft 8. This chapter discusses the following topics:
Oracle Application Server ProcessConnect provides the following standard interactions for Component Interfaces:
In the following discussions, a single record is correlated to multiple keys.
Use the Create interaction to create a new record using a set of unique keys and specified properties.
Create (key1, key2, ... keyn, properties)
where:
key (in/out parameter)--The individual key parameters (key1, key2, .. keyn) must be supplied. This set of keys must not exist in the server database, that is, they must be unique. The keys correspond to the set of Create Keys as defined for the particular Component Interface.
You can call Create() without a set of explicit keys; however, the Create interaction returns a set of keys. This behavior is supported with PeopleCode, which is triggered on the server. For example, to create a Purchase Order, the client may not know what the next available PO number is. By specifying NEXT as the PO number key, the call triggers PeopleCode, which determines the next available PO number. This information must be returned to the calling client, using the in/out key parameters.
The Oracle Application Server ProcessConnect Create() interaction is available if the PeopleSoft's Create and Save interactions in the Component Interface are enabled on the PeopleSoft server.
You use the CreateEx interaction to create a new record using a set of unique keys and specified properties.
CreateEx(key1, key2, ..., keyn, interactiveMode, properties)
where
key (in/out parameter). The individual key parameters (key1, key2, .. keyn) must be supplied. This set of keys must not exist in the server database, that is, they must be unique. The keys correspond to the set of Create Keys as defined for the particular Component Interface.
properties parameter is a structure that contains all the properties of the Component Interface. When the CreateEx interaction is called, these properties are inserted into the record created with the specified key(s).
interactiveMode flag is used for error handling. When accessing properties in a Component Interface, the Oracle Application Server Integration Adapter for PeopleSoft 8 uses PeopleSoft-provided APIs that read and write individual fields in the Component Interface. However, these changes are not propagated to the PeopleSoft server one at a time. Instead, the psjoa.jar (with which the Oracle Application Server Integration Adapter for PeopleSoft 8 interacts) packages all the changes and sends the changes to the server in one package. If any of the individual updates fail, a generic error is returned, which does not pinpoint the actual error. With the interactive mode set to True, every field update is sent to the server individually. This has a substantial impact on performance, but it does provide specific error information if the update fails (for example, invalid value used for setting a field).
The interactiveMode provides maximum performance and provides error reporting at the field update level. To use this feature properly, it is recommended that normal calls be made with the interactiveMode set to FALSE. There should be no impact on performance. If an error is returned, the same call can be re-tried with the interactiveMode flag set to True. When the call fails, the server returns a more precise error message.
In some situations, it is common practice to call CreateEx() without a set of explicit keys, but the CreateEx interaction returns them. This behavior is supported with PeopleCode that gets triggered on the server. For example, to create a Purchase Order, the client may not know what the next available PO number is. By specifying NEXT as the PO number key, the call triggers PeopleCode which determines the next available PO number. This information must be returned to the calling client, using the in/out key parameters.
The Oracle Application Server ProcessConnect CreateEx() interaction is available if the PeopleSoft's Create and Save interactions in the Component Interface are enabled on the PeopleSoft server.
The DeleteOnly method allows you to delete items in a collection.
DeleteOnly(key1, key2, ..., keyn, correctionMode, interactiveMode, properties)
where
key parameters must be supplied. This set of keys must exist in the server database, else an error occurs. The keys correspond to the set of Get Keys as defined for the particular Component Interface.
correctionMode is a Boolean flag, when set to True, allows deletion of past effective-dated items in a collection. Specifically, it allows the deletion of items that have EFFDT prior to the current effective date. Without this flag set to True, any modification to these items result in an error returned from PeopleSoft server.
.
.
interactiveMode flag is used for error handling. When accessing properties in a Component Interface, the Oracle Application Server Integration Adapter for PeopleSoft 8 uses PeopleSoft-provided APIs that read and write individual fields in the Component Interface. However, these changes are not propagated to the PeopleSoft server one at a time. Instead, the psjoa.jar (with which the Oracle Application Server Integration Adapter for PeopleSoft 8 interacts) packages all the changes and sends the changes to the server in one package. If any of the individual updates fail, a generic error is returned, which does not pinpoint the actual error. With the interactive mode set to True, every field update is sent to the server individually. This has a substantial impact on performance, but it does provide specific error information if the update fails (for example, invalid value used for setting a field).
The interactiveMode provides maximum performance and provides error reporting at the field update level. To use this feature properly, it is recommended that normal calls be made with the interactiveMode set to FALSE. There should be no impact on performance. If an error is returned, the same call can be re-tried with the interactiveMode flag set to True. When the call fails, the server returns a more precise error message.
properties contain a subset of the structure that exists on the server. All items that are leaves are deleted.
The properties have the same datatype as the CreateEx or UpdateEx methods of this Component Interface; however, only the key values are important. The nonkey values are ignored. The key values must match those on the server, otherwise an exception is raised.
The following demonstrates the use of the key values. If a collection contains the items:
item0 item1 item2 item3
you can delete item1 and item3 by providing the keys of item1 and item3 in the properties:
item1 item3
After the call, the server has the remaining items in the collection:
item0 item2
The second example, shows the items containing other collections:
item0
item0a
item1
item1a item1b item1c
item2
item2a item2b
You can delete item1b and all of item2 by giving the keys to item1b and item2:
item1
item1b
item2
By providing an empty subcollection for item2, you turn it into a leaf and that entire subbranch is deleted. After the call, the server has the remaining items:
item0
item0a
item1
item1a item1c
Use the Find interaction to return a list of keys that satisfy the supplied partial search keys. If the Component Interface has only one instance without a key, then the Find() interaction is not generated.
Find (partialKey, keyList)
where:
partialKey (structure)--The individual keys are optional.
keyList (output parameter)--A list of keys that matches the partialKey.
The keys correspond to the set of Find Keys as defined for the particular Component Interface.
When specifying partialKey, you can use the same wildcard search available from the PeopleSoft internal Find() interaction. For example, the partial ACCOUNT key of 11 returns all ACCOUNT keys that start with 11, whereas %40 returns all ACCOUNT keys that contain 40 anywhere within the key. The partial key _4_4 returns all ACCOUNT keys with the character 4 in the second and fourth positions.
The Oracle Application Server ProcessConnect Find() interaction is available if the PeopleSoft Find interaction in the Component Interface is enabled and Get keys are available.
Use the Get interaction to retrieve properties based on the input key parameters (key1, key2, ... keyn). The output parameter is a structure containing the properties of the record that matches the key parameters. If the Component Interface has only one instance without a key, then the Get interaction does not contain any key parameters.
Get (key1, key2, ... keyn, properties) Get (key1, key2, ... keyn, getHistoryItems, properties)
where:
key parameters must be supplied. This set of keys must exist in the server database; otherwise an error occurs. The keys correspond to the set of Get Keys as defined for the particular Component Interface.
properties (structure)--Contains a complete structure of the Component Interface properties, which is returned upon completion of the call.
getHistoryItems, is used to control the range of effective dated items returned.
False.
If the Component Interface does not have a key, as in the case where only one instance exists, then the Get() interaction has the form:
Get(properties)
The Oracle Application Server ProcessConnect Get() interaction is available if the PeopleSoft Get interaction in the Component Interface is enabled.
Use the Update interaction to update properties based on the input key parameters (key1, key2, ... keyn).
Update (key1, key2, ... keyn, properties)
where:
key parameters must be supplied. This set of keys must exist in the server database; otherwise an error occurs. The keys correspond to the set of Get Keys as defined for the particular Component Interface.
properties (structure)--Contains a complete structure of the Component Interface properties, which replaces the existing properties in the database.
When calling this interaction, the properties of the record corresponding to the keys are replaced by the properties input parameter. All collections within the original record are deleted and replaced by those in the input parameter, properties. The sizes of these collections do not have to match, as the procedure within Update is to delete all existing collection items and then insert the given ones.
If the properties of the Component Interface contain effective dated items below level 0 (that is, a key field with a name of EFFDT) an additional parameter is required, getHistoryItems. This parameter is of type Boolean. If it is set to True then all effective dated items are returned as a sequence (which could be embedded in any level). These include all past effective dated items, the current effective dated item, as well as all future effective dated items. If the getHistoryItems parameter is set to False, only the current and all future effective dated items are returned. If subsequent calls to update on the same instance are to be made, then getHistoryItems should be set to False.
If the Component Interface does not have any keys, as in the case where only one instance can exist, then the Update() interaction has the form:
Update(properties)
The Oracle Application Server ProcessConnect Update() interaction is available if the PeopleSoft Get and Save interactions in the Component Interface are enabled in the PeopleSoft application.
You use the UpdateEx interaction to update properties based on the input key parameters (key1, key2, ... keyn). Using UpdateEx, it is not possible to delete items in a collection. A separate interaction, DeleteOnly, facilitates deletion.
UpdateEx (key1, key2, ... keyn, correctionMode, interactiveMode, properties)
where
key parameters must be supplied. This set of keys must exist in the server database, else an error occurs. The keys correspond to the set of Get Keys as defined for the particular Component Interface.
correctionMode is a Boolean flag, when set to True, allows modifications to Component Interfaces with effective-dated items either by updating the field values, or by inserting new items into a collection. Specifically, it allows modification to items that have EFFDT prior to the current effective date. Without this flag set to True, any modification to these items result in an error returned from PeopleSoft server.
.
.
interactiveMode flag is used for error handling. When accessing properties in a Component Interface, the Oracle Application Server Integration Adapter for PeopleSoft 8 uses PeopleSoft-provided APIs that read and write individual fields in the Component Interface. However, these changes are not propagated to the PeopleSoft server one at a time. Instead, the psjoa.jar (with which the Oracle Application Server Integration Adapter for PeopleSoft 8 interacts) packages all the changes and sends the changes to the server in one package. If any of the individual updates fail, a generic error is returned, which does not pinpoint the actual error. With the interactive mode set to True, every field update is sent to the server individually. This has a substantial impact on performance, but it does provide specific error information if the update fails (for example, invalid value used for setting a field).
The interactiveMode provides maximum performance and provides error reporting at the field update level. To use this feature properly, it is recommended that normal calls be made with the interactiveMode set to FALSE. There should be no impact on performance. If an error is returned, the same call can be re-tried with the interactiveMode flag set to True. When the call fails, the server returns a more precise error message.
When calling this interaction, the properties of the record corresponding to the keys are replaced by the input parameter properties. All collections within the original record are deleted and replaced by those in the input parameter, properties. The sizes of these collections do not have to match, as the procedure within UpdateEx is to delete all existing collection items and then insert the given ones.
If the properties of the Component Interface contain effective dated items, then the properties parameter must contain all future effective dated items, as the original list is replaced. This provides the mechanism for adding and deleting future effective dated items. However, if the properties also contain past effective dated items, an error is returned, as past effective dated items cannot be modified. If the current effective dated item is also included, it is ignored. This permits the client to call Get() with the getHistoryItems parameter set to False, and then modify any future effective dated items or add new future effective dated items, and then passing the structure as parameter for the UpdateEx() interaction.
If the Component Interface does not have any key, as in the case where only one instance can exist, then the UpdateEx() interaction has the form:
UpdateEx(correctionMode, interactiveMode, properties)
The Oracle Application Server ProcessConnect UpdateEx() interaction is available if the PeopleSoft Get and Save interactions in the Component Interface are enabled in the PeopleSoft application.
Oracle Application Server ProcessConnect supports user-defined interactions in Component Interfaces. The signatures are of the form:
myRet=myMethod(parameter1, parameter2, ...)
where:
The parameters can only be input parameters to the interaction. Only one value can be returned from the interaction as the return parameter.
.
Table 4-1 describes the list of basic types in PeopleSoft and how they map to Oracle Application Server ProcessConnect types. The xsd prefix stands for the namespace http://www.w3.org/2001/XMLSchema.
The following provides further explanations for datatypes that require special attention.
Although these types can contain strings of any length, you may still have length limitations at runtime. A cast failure occurs at runtime if a client program is sending a string to PeopleSoft as a key or a property, and if that string is longer than n (refer to the table). This is not true if n is zero. In that case, PeopleSoft accepts strings of any length, up to the maximum as defined by the back-end database.
| Datatype | Description |
|---|---|
|
Char(n) |
Any string of n characters. n is between 1 and 254. |
|
Long(n) |
Any string of n characters. n is between 0 and 64000. Long(0) is an unbounded string. |
The Nbr and Sign datatypes in PeopleSoft map to datatype xsd:byte, xsd:short, xsd:int, xsd:double, or xsd:string based on the values of n and d, which specify the number of integral and fractional digits respectively. Due to a current limitation in the PeopleSoft API, output values cannot have a precision that exceeds a float; for example, the return value of the client call can only keep a maximum precision of 7 digits regardless of the client type.
If the PeopleSoft type is Nbr, verify that the client inputs positive values. The precision may be lost if it exceeds the specified n and d. For example, 123.456 loses two digits when converted to a Nbr(3,1).
In PeopleSoft, the Date type contains only the date information. Time properties may be defined with different levels of precision:
The Oracle Application Server Integration Adapter for PeopleSoft 8 translates all Date types to xsd:date, all Time types to xsd:time and all DateTime types to xsd:dateTime.
Because the Time part in Date values always allow you to specify up to milliseconds, you may lose precision if you are not aware of the actual precision of the field in the PeopleSoft database.
Date, DateTime and Time types appearing in user-defined interactions are mapped as strings, due to a limitation in PeopleSoft.
PeopleSoft provides the ability to schedule and keep track of planned items by using a special property called Effective Date (abbreviated EFFDT). Such items are either in effect or merely planned, depending on whether their date is before or after PeopleSoft's current date.
If the properties of a Component Interface contain such effective dated items (that is, a field with a name of EFFDT), the adapter makes it possible for callers to retrieve the complete set of values or only those values not yet effective--those that can still be changed.
For Components Interfaces with properties that include an effective date, the adapter provides an additional parameter, called getHistoryItems, to the Get operations. This parameter is of type Boolean and if it is set to True then all effective dated items are returned. These include all past effective dated items, the current effective dated item, as well as all future effective dated items.
If the getHistoryItems parameter is set to False only the current and all future effective dated items are returned. Choose False if your intention is to add or change to these items (because past items cannot be changed).
It is also possible to have multiple Effective Dated items having the same Effective Date. In this situation, an additional property, Effective Sequence (EFFSEQ), must also be provided. The values of the EFFSEQ must be unique to differentiate items with the same Effective Date.
The correctionMode argument in both the UpdateEx and DeleteOnly interactions control whether past effective dated items can be modified. If it is set to True, all items can be modified. Otherwise, modifying past effective dated item generates an exception.
When calling the Update interaction on a Component Interface that has Effective Dated items, you must take care not to include any Effective Dates of a value earlier than PeopleSoft's current Effective Date, or the call fails with an exception. However, the current Effective Dated item can be included as it is bypassed when setting properties. If Effective Sequence exists, then all current Effective Dated items with matching Effective Sequences in the server are skipped when setting properties.
|
 Copyright © 2003 Oracle Corporation. All Rights Reserved. |
|