Implementation of Keys in ActiveMatrix BusinessWorks Plug-in for PeopleSoft

The PeopleSoft component interfaces become schemas in the plug-in. When applying a PeopleSoft Component Interface to a CI Request and CI Request Response in the plug-in, the fields in the CREATEKEYS (if applicable), GETKEYS and FINDKEYS buckets in every Component Interfaces definition hold a special significance.

GETKEYS

The plug-in primarily uses GETKEYS to update a particular record in PeopleSoft. For CI Request Response activity, if the FINDKEYS values are not specified in the incoming request, the plug-in looks for GETKEYS values. For a CI Request activity, the plug-in by default looks for GETKEYS and ignores the FINDKEYS completely.

If the GETKEYS values are specified, the plug-in queries PeopleSoft to check if the record exists. If the record exists, the plug-in updates that record in PeopleSoft fields with values specified under the PROPERTIES keys.

The GETKEYS keys should be a subset of the FINDKEYS keys. This is to avoid an error scenario wherein the plug-in tries to search for a record with a key that is not a part of the FINDKEYS in the CI definition.

If the record does not exist, the plug-in looks for CREATEKEYS.

FINDKEYS

The FINDKEYS functionality of PeopleSoft Component Interface is a feature that can be used with the plug-in's CI Request-Response activity. If the FINDKEYS values are specified in the incoming request, they take precedence over any GETKEYS or CREATEKEYS values specified. The plug-in's CI Request-Response activity uses the same to query PeopleSoft and return a sequence of FINDKEY keys with values, which satisfy the query criterion, as a reply. Please note that any other part of the incoming request (GETKEYS, CREATEKEYS or PROPERTIES) is ignored.

Fields in FINDKEYS should be a superset of fields in GETKEYS() as the fields under these decide the query criterion.

CREATEKEYS

The plug-in primarily uses CREATEKEYS to create a record in PeopleSoft. If neither GETKEYS nor FINDKEYS are specified in the incoming requests (or due to the conditions arising out of the two scenarios described in GETKEYS), the plug-in looks for CREATEKEYS in the incoming request.

If specified, the plug-in queries PeopleSoft to check if the record already exists. If the record is not found, the plug-in creates a new record with the CREATEKEYS fields as primary fields and PROPERTIES keys as values for the non-primary fields. If the record already exists, an error is thrown by the plug-in saying CREATEKEYS failed.

The CREATEKEYS should be a subset of the FINDKEYS keys. This is to avoid an error scenario wherein the plug-in is trying to search a record with a key which is not a part of FINDKEYS in the CI definition.

Each CI can have multiple levels up to Level 3. In this case, the plug-in mandates the occurrence of key fields at all levels in this scenario for performing the CREATE, UPDATE, or DELETE operations successfully at all levels.

Note: For NULLKEYS, if user does not provide any values in the FINDKEYS, GETKEYS, and CREATEKEYS and provides value in the PROPERTIES a new record gets created. But user is not recommended to use NULLKEYS, as this differs from CI to CI, as some CI allow blank records to be added at child level while some CI do not allow this, and therefore the operation fails. Therefore it is recommended to use CREATEKEYS, to create a new record.

Valid Operation Codes for the Plug-in

PeopleSoft Component Interface can have multiple levels up to level 3. The plug-in can INSERT or UPDATE the records at all these levels. The DELETE operation can be performed only at level 1 and above. In these cases, the key fields should be present at all levels and the user needs to provide the operation code at all levels.

Valid values for OPRN_CODE for CREATEKEYS and GETKEYS scenario are:
  • UPDATE - U
  • INSERT - I
  • DELETE- D

CREATEKEYS Scenarios

For all CREATEKEYS scenarios, specify I as the value for OPRN_CODE for all the records in the request.

GETKEYS Scenarios

  1. To update details of an existing record, specify U as the value for OPRN_CODE at all levels.

  2. To insert a new record under an existing record, specify I as the OPRN_CODE for the record to be inserted. If the new record to be inserted is not a Level1 record, specify U as the OPRN_CODE for the parent records under which the new record is inserted in the following format:

    • Level1 record - 'U'
      • Level2 record - 'I'

  3. To delete a record under an existing record, specify D as the OPRN_CODE for the record to be deleted. If the record to be deleted is not a Level1 record, specify U as the OPRN_CODE for the parent record(s) from which the record is to be deleted in the following format:

    • Level1 record - 'U'
      • Level2 record - 'D'

  4. While inserting a new Level1 record with Level2 and Level3 records under it, specify the value for the OPRN_CODE in the following format:

    • Level1 record - 'I'
      • Level2 record - 'I'
        • Level3 record - 'I'

    For some CIs, PeopleSoft by default creates child records while inserting a new record. For example, while inserting a new Level1 record for some CIs, PeopleSoft creates Level2 and Level3 records by default. In such a scenario specify the value for the OPRN_CODE in the following format:

    • Level1 record - 'I'
      • Level2 record - 'U'
        • Level3 record - 'U'