Broadleaf Campaign Services

Overview

Important

Campaign Services has been deprecated since release train 1.8.0-GA and PromotionServices 2.0.0-GA as the functionality has been folded into OfferServices. For the latest docs on campaign, see Offer Services docs.

Campaign Services provide the management of a campaign. At current, the primary use of a campaign is as a container of limited use promotion codes that are used with the Offer Service.

See Data Model for field level details on the campaign entities.

Code Generation

A CodeGenerator is the component that controls the code generation process. There are several key properties and classes to be aware of for code generation.

The code generation generates codes according to a target format. The format has placeholders that drive the set of characters that can be used.

Consider the code format: TEST1-@@-##-*

This format has a hardcode prefix of "TEST1-" and 3 sets of placeholder values.

The "@" placeholder will use allowed alphabetic characters when generating the code.

The "#" placeholder will use allowed numeric symbols when generating the code.

The "*" placeholder will use allowed alphanumeric symbols when generating the code.

The DefaultCodeGeneratorService uses the CodeFormatAvailableCharHelper to determine the allowed symbols for code generation. By default, the allowed numbers exclude 0, 1, and 5. The allowed characters exclude I, L, O, and S. These characters are excluded from generated offer codes to avoid commonly misread letters and numbers.

These components can be customized for more precise code generation strategies.

If no format is provided, the code generation service will generate a code based on the code generators specified length. If no length or format is provided to the code generator, it will select an appropriate length based on a guessability ratio of 1 and 100.

Code Auditing

Generated codes are limited use. The Campaign Service is used by the Cart Operations Service to enforce limited use codes.

Here is the default flow:

When the code is added to the cart, the Cart Operations Service will verify that the code has not been used.
When the order is submitted, the Cart Operations Service will perform a final validation that the offer code is still valid.
After successful submit order, the Cart Operations Service will publish an event. This service registers the CampaignCheckoutCompletionListener which will consume the event and record the audit.

This approach to code usage has a small race condition where two checkouts can simultaneously use the same code if they hit submit in the same few seconds. This architectural decision is by design as other approaches (such as reserving or locking the code) have significant downsides with regard to use and ability to scale the function. For implementations that see this as a concern, it is preferable in most cases to provide post checkout audits prior to fulfillment rather than to handling during the submit checkout flow.

Other Code Restrictions

In addition to being single use, codes can be restricted to certain users. This can be done across the whole campaign by using an Email Regular Expression such as *@mycompany.com or with individual emails on each code.

Codes can be also be restricted by date.

Code Import / Export

Codes can be imported and exported into a campaign. This is designed to support offline merging of codes and qualifying emails. For example, if you have generated a set of codes, you can then export these codes to be used in an email campaign. Further, you could optionally marry an email address with each code to further restrict the use of the code to a specific customer.