Batch Services

There are four services that facilitate the updating of the catalog in batch mode. All batch services can be run on demand or in scheduled mode. They are:

Each service performs functions that can be selectively executed using the function names.

Each service keeps in memory a history of all information, warning and error level messages. They are exposed through a set of API, getWarningMessages, getErrorMessages, getInfoMessages and getCurrentMessage. They can be viewed using the View Status option on the Commerce Administration Page. For more information see Running the Batch Services from the Commerce Admin Page.

Each service creates a global lock at the start of execution, using the global lock management, and releases it upon completion. This prevents services that use the same lock name from executing simultaneously on the same server, or other servers in the cluster.

Each service has the following configurable property values

Property	Description
`schedule`	Schedule on which the service will execute. If this property is valued, the service will schedule itself accordingly when it is first instantiated.
`availableFunctions`	A list of function names that the service can perform. Function names are used to identify specific processes that can be performed by the service such as, AGS_GENCATALOGS to generate ancestor catalogs. AGS_GENANCESTORS to generate ancestor categories.
`functionsToPerformByDefault`	This property is used to configure a default set of function names that are executed when none are provided, such as in schedule mode, or through the Java API. It can be any of the functions exposed by the `availableFunctions` property.
`saveMessages`	Can be set to true or false. If true, the info, error, and warning messages from the last execution of the service are retained in memory. These messages are used for the maintenance log display on the Commerce Administration pages. Default is true.
`maxItemsPerTransaction`	The number of repository items that are updated before restarting the transaction. This can be used in the case of very large catalogs to spread updates across several transactions.
`jobName`	The scheduler job name used when the service is scheduled.
`jobDescription`	The scheduled job description.
`lockTimeOut`	Time in milliseconds before a timeout when acquiring the global lock.
`lockName`	The name used for the global lock.

AncestorGeneratorService

Component: /atg/commerce/catalog/custom/AncestorGeneratorService

The AncestorGeneratorService updates the following property values for each of the catalog item types. This service must be executed after making catalog updates in order for catalog navigation and search to work correctly.

Item Type	Property Names
Categories:	`catalogs catalog ancestorCategories`
Products:	`catalogs` `ancestorCategories` `parentCategoriesForCatalog`
SKUs:	`catalogs` `ancestorCategories`

Available Functions

AGS_GENCATALOGS: generates the catalog and catalogs properties

AGS_GENPARENTCATS: generates the parentCategoriesForCatalog property

AGS_GENANCESTORS: generates the ancestorCategories property

CatalogVerificationService

Component: /atg/commerce/catalog/custom/CatalogVerificationService

The CatalogVerificationService verifies/validates various relationships between catalog items. It validates the following property values for each catalog item type.

Item Type	Property Names
Catalogs	`ancestorCategories` `allRootCategories` `directAncestorCatalogsAndSelf` `indirectAncestorCatalogs` `subCatalogs` (only if configured to use. See CatalogUpdateService`computeSubCatalogs`)
Categories	`fixedRelatedCategories` `categoryInfos` `parentCategory`
Products	`fixedRelatedProducts` `catalogsRelatedProducts` `productInfos` `parentCategoriesForCatalog`
SKUs	`fixedReplacementProducts` `catalogsReplacementProducts` `skuInfos`

Available Functions

CVS_VERIFYCATALOGS: verifies catalog item properties

CVS_VERIFYCATEGORIES: verifies category item properties

CVS_VERIFYPRODUCTS: verifies product item properties

CVS_VERIFYSKUS: verifies SKU item properties

CatalogUpdateService

Component: /atg/commerce/catalog/custom/CatalogUpdateService

The CatalogUpdateService updates the same catalog properties that are updated by the dynamic service CatalogCompletionService, but in batch mode. Because the CatalogCompletionService can be disabled and may not be actively updating the catalog property values in real time, this service can be used to batch update them on an as needed basis.

This service updates the following property values for each of the catalog item types.

Item Type	Property Names
Catalog	`directAncestorCatalogsAndSelf` `indirectAncestorCatalogs` `ancestorCategories` `allRootCategories` `subCatalogs(optional)`
Categories	`parentCatalog` `parentCategory`

Available Functions

CUS_UPDATECATALOGS: Updates all item properties in the catalog

CatalogMaintenanceService

Component: /atg/commerce/catalog/CatalogMaintenanceService

This component is an extension of a standard batch service. It is a container of other batch maintenance services. It provides a single point of access to other batch services and a consolidated view of their processing results.

The CatalogMaintenanceService exposes the history log for each of its registered services, which can be viewed from the Commerce Administration pages. Note that the viewable history log is maintained only in memory and is discarded after a recycle of the Dynamo server. The Dynamo logs can be used as a historical reference to the service logs.

Using the CatalogMaintenanceService, functions from any of the contained services can be selectively executed. Therefore, this service can be scheduled to sequentially execute other services it contains, as opposed to scheduling each service individually.

The CatalogMaintenanceService has a related /atg/epub/CatalogMaintenanceHelper component. This component is used by installations that use Content Administration to manage their catalogs; it listens for Content Administration deployments and runs catalog maintenance services automatically. For ATG Commerce purposes, the component’s important property is extraTriggeringAffectedItemDescriptors. By default, the CatalogMaintenanceHelper listens for changes to standard catalog items (catalog, category, categoryInfo, product, productInfo, sku, and skuInfo) such as catagories and products. If you have created custom subtypes based on these item types, you can add them to this property, so that changes to these item types can also trigger catalog maintenance services. For example:

extraTriggeringAffectedItemDescriptors+=myCustomDesc1,myCustomDesc2

Additional property information:

Property	Description
`availableServices`	An array of nucleus paths to each contained service component. Each component is resolved by path and added to the `servicesMap` property.
`catalogRepositories`	A list of catalog keys that will be updated. If null the standard catalog repository is updated.
`availableFunctions`	A consolidated list of all the `availableFunctions` provided by the contained services.
`functionsToPerformByDefault`	This property is used to configure a default set of function names that are executed when none are provided, such as in schedule mode, or through the Java API. It can be any of the function names exposed by the `availableFunctions` property. In the case of the `CatalogMaintenanceService` this property can contain any of the function names exposed by the contained services.

Available Functions

All function available to the contained services.

Running the Batch Services from the Commerce Admin Page

Catalog Maintenance batch services should be run the in the staging environment. They should be run after any structural changes are made to the catalog. For example, it should be run after adding new categories, products, or SKUs.

The catalog batch maintenance services are available from the Commerce Administration page. For more information on accessing the Dynamo Administration UI, see the Installation and Configuration Guide for your application server.

Important note: If you are using custom catalogs and are running ATG Content Administration, you must configure one agent server on your target site cluster to run the Catalog Maintenance Service. For more information, see the Getting Started chapter of the ATG Merchandising User Guide.

There are four options available on the menu; Catalog Update, Catalog Verification, Basic Catalog Maintenance and View Status

Catalog Update

This CatalogUpdateService will batch update the custom catalog property values that are normally updated incrementally by the CatalogCompletionService. When this service is enabled all updates to the catalog using the ACC or the Repository API will trigger these properties to be computed and updated dynamically.

However, if the DCS catalog is updated outside of these processes or if the CatalogCompletionService is disabled, this process should be used to batch update the appropriate property values. The default is to run all the functions of the CatalogUpdateService.

To run CatalogUpdateService from the Commerce Administration Page, click on the Catalog Update link. Click on the Start Process button at the bottom of the Catalog Update page.

Catalog Verification

This process verifies catalog component relationships for accuracy. The default is to run all the functions of the CatalogVerficationService.

To run CatalogVerficationService from the Commerce Administration Page, click on the Verify Catalog link. Click on the Start Process button at the bottom of the Verify Catalog page.

Basic Catalog Maintenance

This process will execute the standard batch maintenance services against the DCS catalog. The default configuration runs all the functions of the AncestorGeneratorService and CatalogVerificationService.

To run Basic Catalog Maintenance from the Commerce Administration Page, click on the Basic Catalog Maintenance link. Click on the Start Process button at the bottom of the Basic Catalog Maintenance page.

View Status

The View status page let you view the information, errors and warnings from the last execution of maintenance on the server. To view the status log from the Commerce Administration Page, click on the View Status link. The status from the last execution displays. For example:

Running a Batch Service from the ACC

To alternatively use the ACC to execute a service

In the Components > by Path window, select the component by path. For example: /atg/commerce/catalog/custom/CatalogMaintenanceService
Choose File > Open Component.
The Component Editor opens.
If the component is not currently running, choose Component > Start Component.
Select the Methods tab.
Click the Invoke button next to the performService method.

Batch Maintenance Form Handler

Component: /atg/commerce/catalog/RunServiceFormHandler

There is one form handler that is used to execute the batch services from the Commerce Administration Pages. This form handler executes the CatalogMaintenanceService, passing a configurable set of functions for each available option. The execution of the CatalogMaintenanceService is started in a new thread, then the View Status page is shown. The View Status can be refreshed to monitor the progress of the batch maintenance run.

Property information:

Property	Description
`basicMaintenanceFunctions`	These are the function names passed to the `CatalogMaintenanceService` for the execution of the Basic Catalog Maintenance option
`verifyFunctions`	These are the function names passed to the `CatalogMaintenanceService` for the execution of Verify Catalog option
`updateFunctions`	These are the function names passed to the `CatalogMaintenanceService` for the execution of Update Catalog option

ATG Commerce Programming Guide