Understanding Get List of Values Web Service Operation

You can develop an external user interface (UI) outside of your PeopleSoft Campus Solutions system. For example, a PeopleTools-developed UI that is directly connected to the PeopleSoft database for entering personal data is internal. A web page used by the student, which is not directly connected to the PeopleSoft database, is external.

This external UI may present list or prompt fields to the users. These fields only accept input from a list of values. The list of values could be prompt values that you set up in Campus Solutions or translate values that the system delivers. For example, you define Communication Category field values using the Communication Categories pageselect (Set Up SACR, then select Common Definitions, then select Communications, then select Communication Category Table). On the other hand, a Campus Solutions page has a Direction field. This field has delivered translate values, such as Outgoing Communication and Incoming Communication.

The following is an example of a field with a list of values.

Image: A List field

This example illustrates the fields and controls on the A List field. You can find definitions for the fields and controls later on this page.

The Get List of Values service operation (SCC_GET_LOV) allows an external UI to request a list of prompt or translate values for a field name configured inside the PeopleSoft Campus Solutions database.

The LOV request message (SCC_LOV_REQ message) accepts the following input parameters:

Record Name (required).
Field Name (required).
LOV Context (optional – defined on the List of Values Setup component).

The list of values retrieved by the service is used to populate drop-down list boxes or prompt fields in an external UI. Also, the external UI logic can use this retrieved list of values to validate a value that a user enters in a field of the external UI.

When the Get List of Values service operation is called, the external UI nominates the field name and its record for which the service should return the list of values. The external UI can request one or more lists of values in a single Get List of Values call. For example, the external UI could request lists of values for multiple field names in one request when it initializes, as long as the field names do not have dependencies on other fields known as key fields. Doing so is a recommended procedure and will save processing time. Subsequently, the external UI can call the service operation whenever necessary.

The external UI does not have to authenticate a user to use this service. That is, a User ID is not required when an external UI calls this service. Therefore, you can use the Get List of Values service operation to populate a list of values on a pre-Login page. For example, a pre-login page may ask applicants to select an academic career before they can sign into the external UI.

When the request message contains a LOV Context, the service returns the list of values based on the settings in the List of Values Setup page for the record name, field name, and LOV Context combination.

When the external UI does not include the LOV Context inside the request message, the service returns the list of values based on the settings in the List of Values Setup page for the record name and field name where LOV Context is set to Default.

If you have not set up a Default LOV Context for the record name and field name, the service returns the list of values based on the prompt table defined for the field name of the record or the translate values if the field passed is a translate field. The service will have no output if the prompt table does not exist or is empty for the record-field name combination.

Warning! Configuring the List of Values Setup page or using the Get List of Values service operation is a technical task and should only be performed by developers with strong Integration Broker skills and good understanding of the record structure contained inside the PeopleSoft Campus Solutions application.

Note: If a SOAP service request XSD contains the 'languageCd' parameter, then the service is enabled for National Language Support (NLS). An ISO Locale value must be passed as the languageCd variable. Valid values can be found in PeopleTools, Utilities, International, Languages.

How the Get List of Values service operation returns list of values

There are two ways to return list of values to the external UI:

Default way: The service uses the record definition or the field properties (for translate fields) defined in Application Designer.
Optional way: The service uses the List of Values Setup component

1. Default way: The system can use the default way for both prompt and translate fields.

The following describes the default way for a prompt field:

For a prompt field, the list of values that the service returns is determined by the prompt table associated with the field name from the record definition in Application Designer.

For example, in the following graphic, notice that the ADMIT_TERM field name from the ADM_APPL_PROG record is associated with a prompt table TERM_TBL. Therefore, when the ADMIT_TERM field and ADM_APPL_PROG record are passed inside the LOV request message (and no LOV Context is passed) the service retrieves the admit terms list of values from TERM_TBL.

Image: Application Designer showing the prompt table associated with a field

This example illustrates the fields and controls on the Application Designer showing the prompt table associated with a field. You can find definitions for the fields and controls later on this page.
To determine which description field to use to return the list of values, the default logic evaluates the identified prompt table (TERM_TBL in our example) and checks if it includes the following fields (respecting the order given): DESCR, DESCRSHORT, DESCR30, DESCR100.

The first of these fields that the service encounters is the one used to return the list of values. If none of these four fields exist, the logic uses the first non-key field marked as a list box item. To continue with our example, for the prompt table TERM_TBL, the DESCR field is the first field encountered from the list mentioned above, and it is therefore the field used to return the list of values.

Image: Application Designer showing the description fields for a record

This example illustrates the fields and controls on the Application Designer showing the description fields for a record. You can find definitions for the fields and controls later on this page.

The following describes the default way for a translate field:

For a translate field, the service retrieves the list of values from the field properties defined for the field name and the record. The external UI lets the service know for which field name and record the service should retrieve the values. For instance, if the external UI displays the Phone Type list field, the UI can include inside the request message the record PERSONAL_PHONE and the field name PHONE_TYPE (and LOV Context is left blank). On receiving this request message, the service includes the translate values defined for the PHONE_TYPE field name inside the response message. The service uses the Long Name fields as the values in the response message.

Image: Application Designer showing the field properties for a translate field

This example illustrates the fields and controls on the Application Designer showing the field properties for a translate field. You can find definitions for the fields and controls later on this page.

2. Optional way: The system can use the optional way for both prompt and translate fields. Use the optional way if you do not want to use the default way for a specific list of values to retrieve.

For a prompt field: if you want the service to retrieve list of values from a different table (or a view that contains logic to restrict the returned values), you can use the List of Values Setup component to select a different table (or view), select a different field description or to exclude values you do not want to display inside the external UI.

For a translate field: you can use the List of Value Setup component to make the service retrieve the list of values using the Short Name field or to exclude some values that you do not want to display on the external UI.

Logic to determine which way the Get List of Values service operation should use to return the list of values

To determine whether the default way or the optional way should be used, the Get List of Values web service operation first evaluates whether the optional way has been set up for the record and the field names included inside the LOV request message, else it uses the default way. The following describes this logic:

The logic determines whether the list of values configuration exists in the List of Values Setup component for the record name, field name, and optionally the LOV Context combination that exists inside the LOV request message.
If a LOV Context exists inside the LOV request message, the logic retrieves the list of values and the proper description according to the configuration for the record name, field name, and LOV Context combination in the List of Values Setup component.
If a LOV Context does not exist inside the LOV request message, the logic still looks at the List of Values Setup component for the record name and field name configuration, but this time where the LOV Context is set as DEFAULT.

If a default exists for the record name and the field name in the List of Values Setup component, the logic returns the LOV response message (SCC_LOV_RESP) according to the record name, field name, and DEFAULT LOV Context.
If the DEFAULT LOV Context does not exist, or if the List of Values Setup component is not defined for the record name and field name included inside the LOV request message, the logic uses the record definition or the field properties (in the case of a translate fields) defined in Application Designer for the record name and field name mentioned in the LOV request message.

Image: Get List of Values service operation logic

Get List of Values service operation logic

Note that the Get List of Values service operation returns an error message (SCC_LOV_FAULT) to the user interface in the following situations:

The UI has not supplied the required record name and field name input parameters.
The UI has not supplied the required key field name input parameters.
The UI has supplied an invalid record name or field name.
The UI has supplied a record name or field name which has its prompt table defined as %Edittable (dynamic prompt table).

Note: The external UI, which you develop, decides how to handle this error message.

Note: Using the List of Values Setup component is optional. Setting up list of values is useful only if the external UI wants to display lists of values that are defined inside your PeopleSoft Campus Solutions system and you want to alter the default way in which the operation picks up the list of values for a field. If you want the external UI to display lists of values that are defined inside the PeopleSoft Campus Solutions system, and you want to use the default way in which the operation picks up the list of values, you need not use the List of Values Setup page. If you are creating a UI that resides inside your PeopleSoft Campus Solutions system, you need not use this setup component. Instead, use the regular PeopleTools logic to display the translate values and the prompt values. Also, note that only the Get List of Values service operation can use this setup