Using the Shopping Cart Framework

This Campus Community PeopleBook chapter provides an overview of the Shopping Cart framework and discusses:

Note. Technical developers, consultants and, implementers should use this PeopleBook chapter to identify the skills that are required for implementing the framework and to determine the scope of data that the shopping cart web service operations can exchange between a self-service user interface (that the academic institution builds) and the PeopleSoft Campus Solutions system. The framework uses the Campus Community Entity Registry feature to perform the data exchange and PeopleTools Integration Broker for the web services. Business and functional analysts should use this chapter to understand how the generic Shopping Cart framework functions.

Click to jump to parent topicUnderstanding the Shopping Cart Framework

The Shopping Cart framework provides the generic SCC_SHOPPING_CART service. You can use this service to implement a shopping cart for any Campus Solutions feature.

Like the other Campus Community frameworks, such as List of Values and Entity Registry, the Shopping Cart framework can be used by all Campus Solutions applications. Therefore, the Campus Solutions system maintains the framework code separately as Campus Community shared components. Examples of Campus Solutions applications include Campus Community, Financial Aid, Student Records, Recruiting and Admissions, and Student Financials.

The benefits of using the Shopping Cart framework include:

The following table lists the service operations for the SCC_SHOPPING_CART service.

Service Operation

Operation Description

Request Message

Response Message

SCC_SC_ADDITEM

Add an item to the cart

SCC_SC_ADDITEM_REQ

SCC_SC_ADDITEM_RESP

SCC_SC_CLEARCART

Clears the cart

SCC_SC_CLEARCART_REQ

SCC_SC_CLEARCART_RESP

SCC_SC_GETCART

Get cart request.

SCC_SC_GETCART_REQ

SCC_SC_GETCART_RESP

SCC_SC_GETITEM

Get an item from the cart.

SCC_SC_GETITEM_REQ

SCC_SC_GETITEM_RESP

SCC_SC_REMOVEITEM

Remove an item from the cart.

SCC_SC_REMOVEITEM_REQ

SCC_SC_REMOVEITEM_RESP

SCC_SC_SAVECART

Save the cart.

SCC_SC_SAVECART_REQ

SCC_SC_SAVECART_RESP

SCC_SC_VALIDATE

Validate cart item.

SCC_SC_VALIDATE_REQ

SCC_SC_VALIDATE_RESP

SCC_SC_CHECKOUT

Check out from the cart.

SCC_SC_CHECKOUT_REQ

SCC_SC_CHECKOUT_RESP

Note. The service operations listed in the preceding table are synchronous. These service operations use the SCC_FAULT_RESP message to return the error messages to the online user interface. The SCC_FAULT_RESP message is not part of the Shopping Cart framework, but is a common fault response message owned by Campus Community which any service operation could use to define fault response.

Click to jump to top of pageClick to jump to parent topicAssessing Staff Skills

Developers working on the implementation of shopping cart should have strong skills in:

Click to jump to parent topicShopping Cart Service Operations

This section discusses the shopping cart service operations.

Click to jump to top of pageClick to jump to parent topicSCC_SC_ADDITEM

This service operation adds a single or multiple items to a user's shopping cart. The operation adds the items to the item table specific to the Campus Solutions application implementing the shopping cart.

The service operation first checks if the item, which the user wants to add, already exists in the cart. If the item already exists, the operation deletes the item from the cart and then adds the item as a new item to the cart. Therefore, a user interface can also use this operation to update an existing cart item.

Once the item is added to the cart, the service operation retrieves all the cart items for the user and sends them back in the response message.

Example: Suppose your institution has an enrollment shopping cart. A student can use this enrollment shopping cart to add the classes in which he or she wants to enroll. The enrollment shopping cart uses the SCC_SC_ADDITEM operation to add a class to the enrollment shopping cart item table.

Example when a shopping cart can use SCC_SC_ADDITEM to modify an existing item: Suppose a student wants to change an enrollment option. For example, the student wants to change the Units for an item that has already been added to the enrollment shopping cart. The student can add the same item with a changed value for Units. In this case, SCC_SC_ADDITEM deletes the existing item and adds it again with the new value for Units.

Click to jump to top of pageClick to jump to parent topicSCC_SC_CLEARCART

This service operation deletes all the items from the cart for a user. The operation deletes the items from the item table specific to the Campus Solutions application implementing the shopping cart.

Example: A student deletes all the classes that he or she added previously to the enrollment shopping cart. In such a case, the enrollment shopping cart uses the SCC_SC_CLEARCART operation to delete all the classes added by the student.

Click to jump to top of pageClick to jump to parent topicSCC_SC_GETCART

This service operation retrieves all the items added to the shopping cart for a user. The operation retrieves the items from the item table specific to the Campus Solutions application implementing the shopping cart.

Example: A student accesses the enrollment shopping cart to make additional changes. The shopping cart displays all the classes that the student had previously entered. In such a case, the enrollment shopping cart uses the SCC_SC_GETCART operation to retrieve all the classes that the user had previously added to the enrollment shopping cart.

Click to jump to top of pageClick to jump to parent topicSCC_SC_GETITEM

This service operation retrieves a particular item from the shopping cart for a user, based on an index number. The index number is a numeric value that represents the position of an item in the cart.

A user interface can send the index number as a request parameter to this service operation. The service operation then uses the index number to retrieve the appropriate item from the cart. The operation first validates the index number and then retrieves the item only if it is a valid index number. If index number is not valid, the operation sends back an error message to the user interface stating that the index number is invalid.

For instance, if the index number in the request message passed to this service operation is greater than the number of items in the cart, then an error message is sent back to the user interface.

Example: A student wants to review details of a specific class that he or she had previously added to the enrollment shopping cart. To review the class details, the student clicks the class number link. In such a case, the enrollment shopping cart feature uses the SCC_SC_GETITEM operation to retrieve the details of the particular class.

The user interface could initially use the SCC_SC_GETCART operation to display only the basic information (for example, Class Nbr) for all the cart items (academic classes). To get more information about the classes, the student can click any class number. When the student clicks a class number, the user interface can use the SCC_SC_GETITEM operation to retrieve and display the complete information for that item.

Click to jump to top of pageClick to jump to parent topicSCC_SC_REMOVEITEM

This service operation removes a single or multiple items from the shopping cart for a user.

Once the item is removed from the cart, the service operation retrieves all the remaining cart items for the user and sends them back in the response message. In other words, the response message will contain the remaining cart items. However, the response message will be blank if the cart is empty after the removal of an item.

Example: A student deletes one or more classes from the enrollment shopping cart. In such a case, the enrollment shopping cart uses the SCC_SC_REMOVEITEM operation to remove a class from the enrollment shopping cart.

Click to jump to top of pageClick to jump to parent topicSCC_SC_SAVECART

This service operation saves a single or multiple items to the cart for a user. The service operation first deletes all the items in the cart for the user and then adds the new items to the cart.

Once the items are saved to the cart, the service operation retrieves all the cart items for the user and sends them back in the response message. In other words, if an error does not occur, the response message contains all the cart items.

There is a difference between SCC_SC_ADDITEM and SCC_SC_SAVECART. If an item already exists in the cart and the user adds it again, SCC_SC_ADDITEM first removes the item from the table and then adds the item again. SCC_SC_SAVECART first deletes all the existing cart items and then adds all the items that are in the request message.

Example: A student uses the enrollment shopping cart to clear all the existing cart items and then adds the new classes in which he or she wants to enroll. After adding the new classes, the student clicks the save link. In such a case, the enrollment shopping cart uses the SCC_SC_SAVECART operation to first remove the existing cart items and then add the new classes to the enrollment shopping cart item table.

Click to jump to top of pageClick to jump to parent topicSCC_SC_VALIDATE

This service operation validates the items in the cart for a user. A user interface can use this operation to validate a single or multiple items in the cart. The validation results of all the items indicating a success or failure is sent back in the response message.

Example: A student adds three classes to the enrollment shopping cart. Before the student checks out these classes, the user interface validates the class choices. After validation, the user interface determines that the student is eligible to enroll only in one specific class. The enrollment shopping cart uses the SCC_SC_VALIDATE operation to perform such a pre enrollment validation.

The SCC_SC_VALIDATE operation enables a user interface to first validate the classes that exist in the enrollment shopping cart, before the user interface invokes the SCC_SC_CHECKOUT operation to enroll the student in the classes. On successful validation of the class, the SCC_SC_VALIDATE operation sends back a response message: OK to Add. If any error occurs during validation, the response message contains the appropriate error message.

Note. The validation code should be specific to the shopping cart feature that you are implementing. Therefore, whoever implements a shopping cart needs to create feature-specific validation logic as part of the adopting feature's application class. In the preceding example, the enrollment validation logic is not part of the Shopping Cart framework. We have incorporated this enrollment validation logic in the CourseShoppingCart application class, validateCart method (part of SSR_COURSE application package). This class and method are specific to the enrollment shopping cart. The validateCart method executes when the enrollment shopping cart user interface invokes the SCC_SC_VALIDATE service operation.

Click to jump to top of pageClick to jump to parent topicSCC_SC_CHECKOUT

This service operation checks out the items that the user has added to the cart. A user interface can use this operation for a single or multiple cart items. The service operation sends back a response message indicating success or failure.

Example: After adding all the desired classes to the enrollment shopping cart, the student confirms his or her choices by checking out the items. The enrollment shopping cart uses the SCC_SC_CHECKOUT operation to check out (enroll) the classes added to the enrollment shopping cart. On successful enrollment, the response message returns the following message to the student: The class has been added to your schedule. If any error occurs during enrollment, the response message contains the appropriate error message.

Note. The checkout code should be specific to the shopping cart feature that you are implementing. Therefore, whoever implements a shopping cart needs to create feature-specific checkout logic as part of the adopting feature's application class. In the preceding example, the enrollment checkout logic is not part of the Shopping Cart framework. We have incorporated this enrollment checkout logic in the CourseShoppingCart application class, purchase method (part of SSR_COURSE application package). This class and method are specific to the enrollment shopping cart. The purchase method executes when the enrollment shopping cart user interface invokes the SCC_SC_CHECKOUT service operation.

Click to jump to top of pageClick to jump to parent topicShopping Cart Framework APIs

This section discusses the classes that you can use for implementing a shopping cart.

The Shopping Cart framework supports a set of Application Programming Interfaces (APIs) that comprise the functionality common to all shopping carts. These APIs are application classes. These APIs exist in the SCC_COMMON application package as shown in the following diagram:

The following diagram shows the delivered enrollment shopping cart implementation. This implementation uses the Shopping Cart framework, and the delivered CourseShoppingCart and CourseShoppingCartItem entities.

The following table describes the delivered classes that are shown in the preceding diagram.

Classes/Tables

Description

CartConfigurationTable

This table contains details about the available carts and the implementation classes that support these carts. The database table for CartConfigurationTable is SCC_SHOPCART.

ShoppingCartHandler

This class is the only web service handler that the system needs to drive the shopping cart. To access the Shopping Cart framework, all the web services will use this web service handler. This class is part of the SCC_COMMON application package.

ShoppingCartManager

The generic handler class uses the ShoppingCartManager core class to create and return the appropriate entity specific to the Campus Solutions application. Additionally, a user interface can use the ShoppingCartManager class to retrieve the items from a cart specific to the Campus Solutions application. This class is part of the SCC_COMMON application package.

ShoppingCart

This core class contains the common functions available to all carts. Note that we have modeled this class as a WorkEntity and therefore, this class does not require real database persistence (table). The feature, adopting the Shopping Cart framework, must extend this class. This class is part of the SCC_COMMON package.

Note. The purchase() & validateCart() methods, which are used by the SCC_SC_CHECKOUT and SCC_SC_VALIDATE service operations respectively, are defined as abstract in the ShoppingCart class. Therefore, you must provide the implementation code in the adopting class.

ShoppingCartItem

The adopting feature must extend this core class to hold any items in the cart. Note that we have modeled this class as a BasicEntity having a real underlying database table that will contain the cart items. This class is part of the SCC_COMMON package.

BasicEntity

You must create the adopting feature entity with an entity type set to ShoppingCartItem. We have defined this type with the base application class called SCC:COMMON:SHOPCART:ShoppingCartItem. This base class extends the SCC_COMMON:ENTITY:BasicEntity application class. Therefore, when creating a shopping cart, you create an application class that extends the BasicEntity class. The BasicEntity class is part of the SCC_COMMON package.

CommonSubRecord

This is a table that contains the Shopping Cart framework's common fields that any adopting feature's item table should include. This enables the cart to track the common system data, with no effort from the adopting feature. The database table for CommonSubRecord is SCC_SHOPCRT_SBR.

CourseShoppingCart

This class pertains to the implementation for enrollment shopping cart. This class is part of the SSR_COURSE application package.

The CourseShoppingCart class extends the core ShoppingCart class. The CourseShoppingCart class contains the implementation for the purchase() & validateCart() methods that are abstract in the core ShoppingCart class.

Note that the CourseShoppingCart class is attached to a work entity (SCC_SHOPCRT_WRK) because the class has nothing to save and therefore does not require a real database table.

CourseShoppingCartItem

This class pertains to the implementation for enrollment shopping cart (which is specific to the Student Records Campus Solutions application). This class is part of the SSR_COURSE application package. This class handles the storage of the enrollment shopping cart items (academic classes). The CourseShoppingCartItem entity is attached to the enrollment shopping cart item table (SSR_REGFORM) that holds the enrollment shopping cart items (academic classes).

WorkEntity

This class is extended by entities that have nothing to save, meaning they do not have a real underlying database table. The core ShoppingCart class extends WorkEntity. The WorkEntity class is part of the SCC_COMMON package.

Click to jump to parent topicDefining a Shopping Cart

This section describes how to use the Shopping Cart framework as a base to create a shopping cart specific to a Campus Solutions application. The section uses the delivered enrollment shopping cart to show an example of how this is done.

This section discusses how to:

Click to jump to top of pageClick to jump to parent topicCreating Application Classes

Create feature-specific shopping cart application classes to customize the business logic specific to the Campus Solutions application. At this stage, create only the application classes inside the proper application package. Add the PeopleCode at a later step.

Typically, any shopping cart feature would include XXXShoppingCart & XXXShoppingCartItem classes where XXX points to the specific feature for which the shopping cart is created (for example, Course and Student Financials). These are the application class names that you will associate with the corresponding entities on the Entity Registry page in the next step.

The XXXShoppingCart class extends the core ShoppingCart class and contains the implementation code for the purchase() method. The SCC_SC_CHECKOUT service operation uses the purchase() method and the SCC_SC_VALIDATE service operation uses the validateCart() method. The system has defined the purchase() method and validateCart() method as abstract in the ShoppingCart base class. The XXXShoppingCart class can also override any other class provided by the base class for providing customized implementation specific to the Campus Solutions application.

The XXXShoppingCartItem class must point to the record where the system will store the shopping cart items.

For example, for the enrollment shopping cart we created the following two classes (APIs):

The following diagram shows that we have included both the classes inside the SSR_COURSE application package. This package is specific to the Campus Solutions Student Records application. The CourseShoppingCartItem class points to the SSR_REGFORM record. The system stores the cart items (academic classes in the case of enrollment shopping cart) in the SSR_REGFORM record.

Click to jump to top of pageClick to jump to parent topicSetting Up Entity Registry

Access the Entity Registry page (Set Up SACR, System Administration, Entity, Entity Registry).

The Shopping Cart framework uses the Entity Registry component for processing shopping cart requests specific to the Campus Solutions application. Use the Entity Registry component to define entity registries for each application-specific cart.

See Setting Up Entity Registry.

In the previous subsection (Creating Application Classes), we created two application classes: CourseShoppingCart and CourseShoppingCartItem. We will now attach each of these classes to an entity. Access the Entity Registry component to create a parent and at least one child entity. Any entity structure for an application-specific shopping cart should include a parent class that will extend the base ShoppingCart class. This parent class provides implementation for all of the service operations. The child class is needed because it points to the actual application-specific cart item table. If the application-specific feature has multiple child item tables, then you should create entities for all children and also define the parent-child relationship in the Entity Registry component.

Create the parent entity with the following configuration:

This example shows the parent entity, named CourseShoppingCart, which we created for the enrollment shopping cart:

Create the child entity with the following configuration:

This example shows the child entity, named CourseShoppingCartItem, which we created for the enrollment shopping cart:

Note. The record you enter in the Prod Record field for the child entity must contain the SCC_SHOPCRT_SBR (CommonSubRecord) sub record. That is, you must include SCC_SHOPCRT_SBR in the application-specific item table. This enables the common system data to be tracked by the Shopping Cart framework without any effort from the adopting feature. The SCC_SHOPCRT_SBR sub record contains the Shopping Cart framework's common fields that an adopting feature should include.

The following example shows how you should create the production record for the child entity:

Click to jump to top of pageClick to jump to parent topicGenerating Code for Application Classes

In the previous subsection (Setting Up Entity Registry), we created two entities and assigned the application classes to the entities. We will now click the Generate Code button on the Entity Registry page to generate the code that can be pasted inside the PeopleCode of the application class.

To generate the code:

  1. Access the Entity Registry page for the XXXShoppingCart and the XXXShoppingCartItem entities.

  2. Click the Generate Code button.

  3. Select the desired options and generate the code.

You can paste the generated code directly inside the application classes. You can also use the generated code as a template to add more logic as needed.

See Setting Up Entity Registry.

Click to jump to top of pageClick to jump to parent topicConfiguring Shopping Cart

To register the application-specific shopping cart, access the Shopping Cart Configuration page (Set Up SACR, System Administration, Utilities, Shopping Carts, Shopping Cart).

Owner ID

Because the Shopping Cart framework can be used by any Campus Solutions application, select the Campus Solutions application that will own the shopping cart you are creating.

Entity ID

Select the Entity ID of the parent entity that you created on the Entity Registry page.

On the Shopping Cart Configuration page, you attach the entity ID of an application-specific shopping cart to an application-specific shopping cart type. The shopping cart type represents the type of the application-specific shopping cart, and the entity ID represents the application-specific entity defined on the Entity Registry page.

Purpose of this configuration:

Because the Shopping Cart framework is generic, the service operation will need to know which application-specific shopping cart sent the request so that it can proceed with first building the appropriate entities that are specified on the Shopping Cart Configuration page and then start processing the request.

Each shopping cart request must contain a <SCC_SHOP_CART_TYPE> tag. The value of the tag indicates the shopping cart type that you have defined on the Shopping Cart Configuration page. Any shopping cart service operation upon receiving a request will first read the shopping cart type from the request. Once the service operation identifies the cart type, it then identifies the appropriate entities attached to this cart type from the Shopping Cart Configuration page to perform the application-specific shopping cart processing.

Example for how the framework uses SCC_SHOP_CART_TYPE:

The enrollment shopping cart involves two entities: CourseShoppingCart and CourseShoppingCartItem. We have defined these entities on the Entity Registry page with CourseShoppingCart as the parent entity and CourseShoppingCartItem as the child entity. The shopping cart configuration for the enrollment shopping cart would therefore look as shown in the preceding screen shot titled Shopping Cart Configuration page.

Note that the shopping cart is Course in the screen shot for the enrollment shopping cart. Therefore, for example, when the enrollment shopping cart sends a request to add an item (academic class) to the enrollment shopping cart, the request must include the shopping cart type Course. The following is an example of a request XML code to add an item to the enrollment shopping cart:

Note that in the code example, the SCC_SHOP_CART_TYPE tag contains the COURSE value. The SCC_SC_ADDITEM service operation reads the cart type value of Course from the request. The operation then queries the Shopping Cart Configuration page to identify the entity appropriate for this cart type (which is CourseShoppingCart for this example) and then proceeds with building the entity hierarchy for processing the enrollment shopping cart request.

Suppose if the <SCC_SHOP_CART_TYPE> had a value of StudentFinance. In such a case, the service operation builds the StudentFinanceShopCart entity and uses this entity for processing the Student Financials shopping cart request to add an item.

Therefore, depending on the <SCC_SHOP_CART_TYPE> value (for example, Course or StudentFinance) with which you have registered the application-specific entities on the Shopping Cart Configuration page, the service operation handler code builds the appropriate entities and uses these entities for further processing.

Click to jump to top of pageClick to jump to parent topicGenerating a Common XSD for the Shopping Carts

The Shopping Cart framework uses a common schema that includes elements of all the entities that are defined in the shopping cart configuration table. The name of the common schema is SCC_ENTITY_SHOP_CART.xsd.

To generate the common schema for all the shopping carts:

  1. Access the Entity Registry page for any parent entity of a shopping cart (Set Up SACR, System Administration, Entity, Entity Registry).

  2. Click the Generate XSD button to generate the XSD.

  3. Use the PeopleTools Schema page to access SCC_ENTITY_SHOP_CART.xsd (PeopleTools, Integration Broker, Integration Setup, Messages, Schema).

  4. Paste the generated XSD into SCC_ENTITY_SHOP_CART.xsd.

For example, the enrollment shopping cart has two entities: CourseShoppingCart (parent) and CourseShoppingCartItem (child). Click the Generate XSD button on the Entity Registry page for the CourseShoppingCart entity. When you click this button, the system generates an XSD that will contain elements of all the available shopping cart entities that you have defined on the Shopping Cart Configuration page.

Any shopping cart parent entity (for example, CourseShoppingCart) extends the ShoppingCart framework class. The ShoppingCart class overrides the base class generateXSD() method to generate a common XSD for all the available carts. You will then need to replace the XSD in SCC_ENTITY_SHOP_CART.xsd with the XSD generated by clicking the Generate XSD button. Note that it is this common XSD that the system references in all the generic XSDs of the messages that are attached to the service operations.

Another example: We will use the message SCC_SC_ADDITEM_REQ.xsd that is attached to SCC_SC_ADDITEM service operation. Suppose you have used the Shopping Cart Configuration page to define two shopping carts. One is an enrollment shopping cart and another is Student Financials shopping cart.

You defined the entity registry setups for the enrollment and Student Financials shopping carts. The following is an example of the Entity Hierarchy Display page for the CourseShoppingCart entity:

Note. We have registered CourseShoppingCart on the Shopping Cart Configuration page with Shopping Cart Type as COURSE.

The following is an example of the Entity Hierarchy Display page for the StudentFinanceShopCart entity:

Note. Assume that you have registered StudentFinanceShopCart on the Shopping Cart Configuration page with Shopping Cart Type as StudentFinance.

Click the Generate XSD button for one of the parent entities, for example, CourseShoppingCart. Doing so generates an XSD that contains the elements from CourseShoppingCart entity hierarchy as well as from StudentFinanceShopCart entity hierarchy.

Replace the content of SCC_ENTITY_SHOP_CART.xsd with the generated XSD. To do so, select PeopleTools, Integration Broker, Integration Setup, Messages, Schema to access the SCC_ENTITY_SHOP_CART message. On the Schema page, paste the newly-generated XSD.

The following is a graphical representation of the SCC_ENTITY_SHOP_CART.xsd:

Note that the XSD contains the Course Shopping Cart (COURSE_SHOP_CART) entity as well as the Student Financials Shopping Cart (SF_SHOP_CART) entity, each entity pointing to its appropriate items.

Note. When creating a new shopping cart, generating the XSD for the newly-created parent entity and then updating the SCC_ENTITY_SHOP_CART.xsd with this newly-created XSD has no impact on the existing shopping carts.

The following is the request XSD of generic SCC_SC_ADDITEM_REQ.xsd.

Note that this SCC_SC_ADDITEM_REQ.xsd schema includes the SCC_ENTITY_SHOP_CART.xsd schema that you generated for the CourseShoppingCart entity.