Personal Library

Concept - Customer Approval

Introduction

This concept is addressed to developers and deals for the most part with the technical aspects of the approval process. Shop managers can also benefit as it helps them to understand how the approval process is applied to channels and applications. Customer approval is a feature that allows shop managers to review self registrations made to a shop. The feature is configurable.

A shop manager can approve or reject the registration.
The approval or rejection of a customer directly affects the customer's possibilities, e.g., a rejected customer cannot use the login functionality as well as other features available for approved customers.
A shop manager can decide whether or not a customer's registration can be used on later occasion.

Like all customer-related features the approval feature is realized as a capability of the customer type. In other words, a developer has to configure a customer type to respect the approval process. On top of this, the approval process can be configured dynamically - a shop manager:

Can configure the dynamic appoval per channel
Activate or deactivate the dynamic appoval for the specific customer types
The dynamic configuration depends on the customer type's capabilities. A shop manager cannot force the approval process for customers which type is not aware of the approval process.

The dynamic approval preferences are realized as general settings to the channel's application repository. Since the approval preferences are stored to the application repository, their management takes benefits from the application repository concept. Thus, the preferences are applicable to all applications belonging to the said repository.

Before you continue reading, be sure to be familiar with the Concept - Customers and Users as well as with the Concept - Application Framework Developers should also have expert knowledge about business objects, business object extensions and how those extensions are created (extension factories).

Glossary

Term	Meaning
customer	From the shop manager's point of view, a customer is an actor at the selling side of the e-commerce environment who, among others, browses through the storefront, orders products and services, returns products, creates and manages an own customer account, subscribes or unsubscribes for newsletters etc. In Intershop 7, customers are categorized in customer types and can be grouped in customer segments.
customer type	In Intershop 7, customer types categorize customers. They indicate whether a customer represents an individual or household -> individual customer or business customer -> business customer Intershop 7's features can differ according to the customer type. For example, it can display either gross prices or net prices, provide additional profile information, hide certain functionalites, etc.
individual customer	In Intershop 7, a customer type that represents an individual person or household. As opposed to business customers, exactly one user is assigned to one individual customer. They are presented gross prices by default.
business customer	In Intershop 7, a customer type that represents a business. As opposed to individual customers, multiple users can be assigned to one business customer. They can be managed and are presented net prices by default.
user	The meaning varies depending on the customer type: With single customer - the user and customer are one thing With group customer - an associate to an organization

References

Application and Customer Capabilities

Application and Customer are realized in the code by ApplicationBO and CustomerBO. Extending their capabilities is a matter of creating a new business object extension. The customer approval feature perfectly fits this approach. This functionality can be turned on and off at runtime. In addition, it can affect an existing business process with respect to its settings.

Customer Approval Extension

Approval Status of a Customer

The approval status is not a direct attribute of the customer. On the contrary, the status is manageable/accessible via an extension of the CustomerBO. Like any other customer-related functionality an applicable extension must be added to the customer type the customer is based on.

<instance name="PrivateCustomers" with="CustomerType" scope="app">
...
    <fulfill requirement="applicableExtensionID" value="CustomerApproval" />
...
</instance>

This approach allows for easy plugging in and plugging out of the approval process. If it is assumed that the customer type does not have an applicable approval extension, the process is not applicable to the customer type in the whole system.

Public API

At the business object's layer the approval status of the customer is handled via the CustomerBOCustomerApprovalExtension.

The applicability of the approval extension is determined by the extension factory which creates the approval extension.

Whether or not the extension can be created depends on the customer type's specifics, as shown below.

@Override
public boolean isApplicable(BusinessObject object)
{
    if (object instanceof CustomerBO)
    {

        CustomerBO customerBO = CustomerBO.class.cast(object);

        return super.isApplicable(object)
                        && customerBO.getCustomerType().isApplicableExtension(
                                        CustomerBOCustomerApprovalExtension.EXTENSION_ID);
    }
    return false;
}

Implementation Details

This extension and the customer's concept is used to enable developers to configure how the customers behave in the system as a whole. This extension is not and should not be aware of any application-/domain-specific configuration about the approval process.

The approval status is internally backed up by a field in the customer's table in the database. The diagram below shows how it is implemented.

Application Approval Extension

Having introduced the application model, the concept of the channel repository as the central point is outdated. Instead, applications have ApplicationBORepository relations and they can create a new application themselves. The present concept bases on the application-specific customer approval process preferences.

Back Office and Storefront Applications

Back office applications can create storefront applications by utilizing the ApplicationBORepositoriesExtension extension. The approval process preferences should be managed at one place: the back office. Furthermore, the approval process preferences should be available for all applications in the sales channel.

Following the standard domain model, the {{ApplicationBORepository} has a domain-specific context and the preferences are stored internally as domain preferences.

Because of the separation of responsibilities different implementations of ApplicationBOCustomerApprovalExtension wired to different applications behave differently. For example, the application extension for a back office application manages the preferences while the storefront application only reads them. The following sections illustrate these different behaviors.

ApplicationBOCustomerApprovalExtension for Back Office Applications

The extension can dynamically configure given customers of a given customer type which are subjects of the approval process. This requires that the customer type is aware of the approval concept, i.e., the customer type must have configured the customer approval extension properly.

The internal implementation of the extension is not specific. It uses the domain behind the ApplicationBORepository the back office application belongs to and stores the configurations as domain preferences.

The code below shows how those preferences are stored:

ApplicationBO applicationBO = getExtendedObject();
ApplicationBORepository applicationBORepository = applicationBO.getRepository("ApplicationBORepository");
Domain domain = domainMgr.getDomainByUUID(applicationBORepository.getRepositoryID());
domainPreferenceMgr.setStringPreference(CUSTOMER_APPROVAL_PREFERENCE_KEY, preferenceHelper.serialize(), domain);

ApplicationBOCustomerApprovalExtension for Storefront Applications

As shown in the diagram above, there is an ApplicationBOCustomerApprovalExtension in the base B2C cartridge that offers methods for verifying whether or not the approval process is enabled for the given customer type or is enabled at all. This extension is used as of now from the storefront applications.

The internal implementation differs from the back office implementation shown above. Instead of ApplicationBORepository the storefront application seeks for the preferences in the domain from which it is created.

ApplicationBO applicationBO = getExtendedObject();
PersistentObjectBOExtension persistenObjectBOExtension = applicationBO.getExtension(PersistentObjectBOExtension.class);
Domain domain = persistenObjectBOExtension.getPersistentObject().getDomain();
preference = domainPreferenceMgr.getStringPreference(CUSTOMER_APPROVAL_PREFERENCE_KEY, domain);

Of course, the isEnabled methods include a check whether the approval is available for the customer at all.

if (!customerType.isApplicableExtension(CustomerBOCustomerApprovalExtension.EXTENSION_ID))
{
    return false;
}

Approval Process Preference

The approval preference intershop.customer.approval.process.enabledForCustomerType is stored in the PREFERENCE table. When configuring a new customer type which is subject of an approval process its ID is appended to the comma-separated list and stored to the database. The table below shows some examples about standard customer types.

Preference value	Approval status activated for
SMB	Only Business Customers are subject of an approval.
PRIVATE	Only Individual Customers are subject of an approval.
SMB;PRIVATE	Both Business Customers and Individual Customers are subject of an approval.

If the database table returns no results on a query, the approval process is not enabled for any customer type. Checking the PREFERENCEDEFINITION table shows the preference definition.

Recipient List of Pending Approval Registration

If the approval process is enabled, shop managers must be notified about incoming registrations. For this matter the ApplicationBOCustomerApprovalExtension holds a list of users of a specific user group (CustomerApprovalRecipients). Some additional business logic carries out the e-mail sending. The assignment of users to the user group with the ID CustomerApprovalRecipients can only be managed at the approval process preferences page in the back office.

Dynamic Applicability of the `CustomerBOCustomerApprovalExtension`

In applications it only needs to be checked for ApplicationBO approval preferences if the customer is unknown (not logged in). The extension factory wired in an application takes the isEnabled method of ApplicationBOCustomerApprovalExtension into consideration. This means that the approval-related functionality can be triggered based on the existence of the extension.

@Override
public boolean isApplicable(BusinessObject object)
{
    if (object instanceof CustomerBO)
    {
        ApplicationBO applicationBO = object.getContext().getVariable(ApplicationBO.CURRENT);
        ApplicationBOCustomerApprovalExtension applicationBOCustomerApprovalExtension = applicationBO
                        .getExtension(ApplicationBOCustomerApprovalExtension.class);

        CustomerBO customerBO = CustomerBO.class.cast(object);

        return super.isApplicable(object)
                        && customerBO.getCustomerType().isApplicableExtension(
                                        CustomerBOCustomerApprovalExtension.EXTENSION_ID)
                        && applicationBOCustomerApprovalExtension.isEnabled(customerBO.getCustomerType());
    }
    return false;
}

This can be used on various occasions. For example, checking if the approval/reject buttons are shown in the back office.

<isif condition="#isDefined(CustomerBO:Extension("CustomerApproval"))#">
    <input type="submit" class="button kor-approval" value="Approve" name="approveCustomer">
    <input type="submit" class="button kor-approval" value="Reject" name="rejectCustomer">
</isif>

Furthermore, a fine-grained process can be defined based on the approval status of the customer. For example, showing the approval/reject buttons only if the customer is still pending for the approval.

<isif condition="#isDefined(CustomerBO:Extension("CustomerApproval")) AND (CustomerBO:Extension("CustomerApproval"):Pending EQ 'true')#">
    <input type="submit" class="button kor-approval" value="Approve" name="approveCustomer">
    <input type="submit" class="button kor-approval" value="Reject" name="rejectCustomer">
</isif>

E-Mail Handling

There are various occasions when an e-mail is sent to either someone that has to be notified about a pending registration or the customer itself.

Approvers List

The back office users in this list receive an e-mail when a new customer has been registered and if the approval process is enabled. Toggling the approval process state for a given customer type does not trigger this, e.g., no e-mail will be sent for a pending approval if the approval process is disabled.

Customer

The customer will receive e-mails on the following occasions:

When a customer completes the registration. The content of this e-mail differs depending on the status of the approval process. If it is enabled, the e-mail states a successful registration, but the account has to be approved. Otherwise, a standard welcome e-mail is sent.

When a customer is approved. The e-mail states a fully usable account and login.

When a customer is rejected. The e-mail states a rejected account and the customer cannot log in.

Usage/Extensibility

Currently, the approval process is used for the review of a customer's registration only. Customers cannot log in until the registration is approved. However, it is conceivable to adjust the business logic for placing orders, shopping in general, viewing special parts of the webshop, etc.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Table of Contents