The Oracle ATG Commerce Reference Store is ATG’s demo application showcasing ATG development best practices.  Many developers use the ATG Commerce Reference Store as an environment for building and testing custom modules because the Commerce Reference Store is very similar to most production ATG applications. Besides being a vessel for development, many ATG projects use the Commerce Reference Store as a building base for their own applications. This practice speeds up development, but contributes to bloated source trees and code that nobody understands. Basing an entire application on CRS is not recommended.

The ATG Commerce Reference Store is a fully functional eCommerce store with many, many features.  In version 10, the Commerce Reference Store picked up Multisite support, among other new features.  If you’ve never dealt with the Commerce Reference Store, or have used an earlier version, browse the ‘ATG Commerce Reference Store Overview’ found here.

Most developers face the daunting task of setting up the Store.  The ATG manual for setting up and configuring the Commerce Reference Store is long and dry.  Setting up the Commerce Reference Store for the first time is a confusing process for someone new to ATG.  Hopefully by the end of this, we will end up with a fully functional application that starts the first time.

We’re going to setup ATG Commerce Reference Store 10.0.X with a Publishing instance.  Since the Store is so huge, any combination of additions could be added.  This setup is most of what anyone needs to do 90% of ATG development.  Additional add-ons to think of adding are Search and Service (Customer Service Center).  Search can be a hassle, and is not critical for many things, so it is omitted.  Information on adding additional products can be found in the Commerce Reference Store Installation and Configuration Guide.

Prerequisites

  • ATG 10 installed and configured
  • A database ready for use with ATG.  I’m assuming we’re all using Oracle in this guide.

The Set Up Process

1. Download the CRS installers from Oracle.com.  If you plan on adding Search, Service, or anything else, make sure those installers are present too.

2. Run the CRS installers that basically add the CommerceReferenceStore module to your DYNAMO_ROOT directory.

3. Setup the initial users in your database:

Setting Up ATG Reference Store Locally 1

4. Run the ATG Configuration and Installation Manager (CIM) to help us configure the Commerce Reference Store.  It’s found at $DYNAMO_HOME/bin/cim.sh (or cim.bat).

5. Choose products to install:

        ATG Platform and Content Administration
        ATG Site Administration
        ATG B2C Commerce
        ATG Commerce Reference Store

6. Choose add-ons:

        Preview Server
        Switching DS
        Configure Preview to run on the CA server
        CRS add-ons:
                Storefront demo app
                International
        Storefront without publishing
        Full sample data

7. After initial configuration, you’ll need to setup and load your database with data for the Store.  If you have a slow computer, this could take a bit of time (1+ hours).

Enter in the correct connection details for each user.  Create, and then load each with the initial data.

CRS_PUB >> Publishing (38 imports)

CRS_SWITHCING_A >> Switching A (9 imports)

CRS_SWITCHING_B >> Switching B (9 imports)

CRS_CORE >> Production Core (5 imports)

8. After setting up your database, you’ll need to create two ATG servers to house your application.  You can accept all the default options when creating the servers, except: your publishing ports should have ‘port-binding ports-01’.  This staggers the ports the server runs on by 100.  This is necessary because the two servers must be running simultaneously, and they cannot operate on the same ports.

Note: In this step we’re creating ATG server configurations that are found in $DYNAMO_HOME/servers.  They house some configurations for the products for which they will be running, for example, Content Administration configurations on the Publishing server.

9. Next head into ‘Application Assembly and Deployment’ to create two new servers for your applications to sit on.  I’m using JBoss, but this will be the same for any application server.

When prompted for a server to copy, select the default/atg server.  It doesn’t matter because they are the same.

Assemble and deploy the applications using all the defaults.  When you reach the CIM main menu again, note the runAssembler arguments and module list.  You’ll need this info when creating and deploying your own custom CRS applications without CIM in the future.

Ex.

Current runAssembler arguments :
-server crs_pub -layer preview

Top Level Module List:

DCS-UI.Versioned BIZUI PubPortlet DafEar.Admin B2CCommerce.Versioned DCS.Versioned DCS-UI Store.EStore.Versioned Store.Storefront

SiteAdmin.Versioned Store.EStore.International.Versioned

10. Test out your installation by starting the production server and seeing the storefront for the first time.  In your server’s configuration directory, CIM has created a batch or shell script to start the server.  Use this for the first time.

>$DYNAMO_HOME/servers/crs_prod/./startDynamoOnJBoss.sh

If everything was successful, head to localhost:<http-port>/crs/storeus  to find the Store.  It should look similar to this:

Setting Up ATG Reference Store Locally 2

 11. Next start the publishing server.  The Business Control Center is the UI for ATG’s own content management system.  In the next step, we’ll use the BCC to transfer assets like scenarios, user segments and HTML files from the publishing to the production server.  At this point, these assets exist on the publishing server, but must be deployed onto the production environment to be accessible from the storefront.

Navigate to localhost:<http-port>/atg/bcc and log into the BCC with publishing/publishing.  You should see something like this:

Setting Up ATG Reference Store Locally 3

12. Navigate to: Content Administration >> Admin Console >> Configuration tab >> “Add site” button

Site Name: Production

Repsitory Mappings (7):

/atg/commerce/catalog/ProductCatalog >>> /atg/commerce/catalog/ProductCatalog_production

/atg/commerce/claimable/ClaimableRepository >>> /atg/commerce/claimable/ClaimableRepository_production

/atg/commerce/pricing/priceLists/SecurePriceLists >>> /atg/commerce/pricing/priceLists/PriceLists_production

/atg/multisite/SiteRepository >>> /atg/multisite/SiteRepository_production

/atg/seo/SEORepository >>> /atg/seo/SEORepository_production

/atg/store/stores/StoreRepository >>> /atg/store/stores/StoreRepository_production

/atg/userprofiling/PersonalizationRepository >>> /atg/userprofiling/PersonalizationRepository_production

Save

Setting Up ATG Reference Store Locally 4

13. Click the Agents tab near the top, then “add agent to site”

Agent Name: ProdAgent

Transport URL: rmi://localhost:<production-rmi-port>/atg/epub/AgentTransport

Include both file systems

Save

Click ‘back to deployment administration configuration’ link near top

Make Changes Live button

Setting Up ATG Reference Store Locally 5

The deployment will now start.  To view its progress, click the Overview tab (under Deployment Administration on the top-left).

After the deployment has completed, head back onto your storefront and browse around.  If you go into the ACC and poke around, you can see the newly added assets that were pushed over from publishing.

At this point, you should be left with a fully functional development environment.  Take some time to poke around each server.  Place an order on the storefront and see it through into the ACC to verify everything is up to par (a dummy Visa number is 4111111111111111.  That’s a 4 with 15 1’s after it).  Next, go into the BCC and create an asset and deploy it over to production.

Troubleshooting

Installing the Commerce Reference Store is very hit or miss – either you’ve done it right or it’s wrong.  If things aren’t working at the end, remember these things:

1. Check that you’re using the exact supported versions of things.  Ensure your application server, database and ATG versions are all compatible with each other.  The ATG Commerce Reference Store is very picky about that sort of thing.

2. Sometimes CIM can fail on a task, and then report is as successful.  This has happened with me while importing data.  To verify everything is happening correctly behind the scenes, browse $DYNAMO_ROOT/log/cim.log and check for any errors.

3. If the errors you’re getting are connection-related, you may have configured some ports wrong.  Verify the ports you set in the BCC match with the ports CIM configured.

4. If your deployment fails after a fresh install, you are completely out of luck.  Doing a deployment in the BCC is like walking on a tight-rope.  It’s a very peculiar system that requires everything to match up perfectly.

The best case-scenario when facing an error with a fresh CRS install is that it’s something minor that was forgotten.  More times than not, though, your errors won’t resolve, not matter how much time you put into them.

I’ve found it easier to first drop and reimport the schema of data corresponding to the product with the errors.  If that doesn’t work, I don’t hesitate to wipe it and reconfigure from the ground up.  The time you’ll spend trying to fix something after a fresh install isn’t worth it.  If you’re fast, you can reinstall everything in less than an hour.  Then, it’s another roll of the dice to see if you’ve gotten a winning combination.