The PromotionImportExport
component contains the main methods used for importing and exporting promotions. Both processes start and end with startImportExportSession()
and endImportExportSession()
methods.
Warning: The atg.commerce.promotion.PromotionImportExport
class on which this component is based allows you to run multiple concurrent import/export sessions. However, it provides no safeguards against making multiple concurrent updates to a given repository item.
The sections that follow describe the methods in this component at a high level. See the ATG Platform API Reference for additional details.
startImportExportSession()
To import promotions, first call startImportExportSession()
. This method sets up the import session, and must be called before doing the import itself.
The method performs the following tasks:
If the session ID is not specified, the method generates a session ID randomly and creates a new
PromotionImportExportSession
object.The method retrieves the promotions repository, using the
PromotionTools
component.If the promotions repository is versioned, the method calls the
PublishingWorkflowAutomator.startWorkflowSession()
method to set up the Content Administration project workflow. ThePublishingWorkflowAutomator
performs the following tasks:Creates a new
PublishingWorkflowSession
objectCreates a project name by appending the session ID to the
PublishingWorkflowAutomator
component’sprojectNameStub
property, separated by a dash. The workflow is configured in thePublishingWorkflowAutomator
component; see Configuring the PromotionImportWorkflowAutomator Component.Performs the necessary interactions with Content Administration security
Creates the process and workspace for the project
The method creates a new transaction in preparation for the import-export session.
The method checks the component’s
integrators
property to establish whether or not any integrators have been configured. (See Using the PromotionImportExportIntegrator Interface.) For each configured integrator, call itspreImportExportSession
method, passing the session object as a parameter.
The method returns a PromotionImportExportSession
object.
importPromotion()
This method enables you to create or update an individual promotion and its associated items (such as closeness qualifiers, promotion folders, coupons, and coupon folders), depending on the action specified.
Always make sure that you have a PromotionImportExportSession
object before using importPromotion()
.
The method performs the following tasks:
Creates a new
PromotionImportExportStatus
object.Checks the component’s
integrators
property to establish whether or not any integrators have been configured. For each configured integrator, call itspreImportPromotion
method, passing the session object and the promotion object, as parameters.
The action
property on the PromotionImportExportInfo
object determines whether the repository item is created, updated, or deleted. Each item associated with the promotion also specifies its own action, but the available actions depend on the parent promotion’s action, as shown by this table:
Promotion Action | Supported Closeness Qualifier Actions | Supported Coupon Actions |
---|---|---|
| UPDATE | DELETE |
| (none) | (none) |
When adding promotions, property values from the template manager take precedence over the equivalent values specified in the PromotionImportExportInfo
object; for updates, the opposite holds.
The method returns a PromotionImportExportSessionStatus
object.
exportPromotionsById()
This method enables you to export promotions by specifying a list of promotion item IDs (for an alternative export method, see the exportPromotionsByRQLQuery section.
This method first calls the PromotionManager.getPromotionsById()
method using the specified list of promotion IDs (if the list is null, all promotions are returned). The getPromotionsById()
method returns a list of promotion repository items. The exportPromotionsById()
method then processes each of the returned promotion repository items as follows:
Create a
PromotionImportExportInfo
object.Populate the object’s
promotionPropertyValues
,templateId
andtemplateValues
properties from the promotion repository item.Retrieve the promotion’s folder (if not null).
For each closeness qualifier in the
closenessQualifiers
property of the promotions repository item, execute the following tasks:Call the
PromotionImportExportTools.getClosenessQualifier()
method to get theclosenessQualifier
repository item.Create a new
ClosenessQualifierImportExportInfo
object.Populate its
closenessQualifierPropertyValues
map from the repository item properties.Add the
ClosenessQualifierImportExportInfo
object to theclosenessQualifiers
list property in thePromotionImportExportInfo
object.
Call the
ClaimableTools.getCouponsForPromotion()
method to retrieve the coupon details associated with the promotion. That method returns a list of coupon repository items. For each coupon item in the list, execute the following tasks:Create a new
CouponImportExportInfo
object and populate itscouponPropertyValues
map from the repository item properties.If the coupon repository item’s
parentFolder
property is not null, then call theClaimableTools.getCouponFolderPath()
method. That method returns the full path for the coupon folder, which is used to set thecouponFolderPath
property in theCouponImportExportInfo
object.Add the
CouponImportExportInfo
object to the coupons list property in thePromotionImportExportInfo
object.
Add the
PromotionImportExportInfo
object to the list to be returned to the caller.Return the list of
PromotionImportExportInfo
objects.
exportPromotionsByRQLQuery
This method enables the user to export promotions by specifying a list of promotion via an RQL query.
This method calls the PromotionImportExportTools.getPromotionsByRQLQuery()
method to query the promotions item descriptor. The method returns a list of promotion repository items. Once the list of repository items has been returned the remaining processing is identical to that of the exportPromotionsById
method.
endImportExportSession
The endImportExportSession()
method ends your import session. The method performs the following tasks:
If the session ID is not specified, throws an exception.
Checks the component’s
integrators
property to establish whether or not any integrators have been configured. (See Using the PromotionImportExportIntegrator Interface.) For each configured integrator, call itspostImportExportSession
method, passing the session object as a parameter. In case of exceptions, thePublishingWorlflowAutomator
’sendWorkflowSession
method must be called to clean up the session.Checks if the current transaction is marked for roll back; if it is, then the roll back is executed, otherwise, the transaction is committed.
If running against a versioned repository and the
sessionStatus
is set toSESSION_ERROR
, the workflow session is rolled back by calling theabandonWorkflowSession
method on thePublishingWorkflowAutomator
component.If running against a versioned repository and the
sessionStatus
is set toSESSION_OK
, then the workflow session is committed by calling thestopWorkflowSession
method on thePublishingWorkflowAutomator
component.
After finishing the import, the workflow advances to the next stage.