Demandware: Programmatically adding custom Objects

There are various instructions on how to add and remove Custom Objects via the Demandware Business Manager. How to properly add or modify these with Demandware Script is unfortunately missing. While the theory is quite simple, there are a few details missing from Demandware documentation that can cause you to break your head around this for a while.

Since I have already done that I would like to share my findings.

Custom object definition

Before you can add custom objects, you first need to create the definition. This part is documented properly by Demandware (see the infoCenter link *login required).

Some tips though:

  • If you want to add Custom Objects via Demandware Script you cannot use the Data Replication setting. This does make sense, but isn't documented. So, just leave it off.
  • You can use the ID property to be able to quickly find Custom Objects instead of needing to search for them. So instead of using an default auto incremental ID, use a string. Of course this ID does need to be unique, so it might not work for you in all cases.

Create your script

Create a new Demandware Script file and add it to the pipeline where you want the custom objects to be added. Make sure to set this Script Pipelet to: Transactional = true. If you don't then your script will cause an error when you want to add or modify a Custom Object. And good luck finding a useful error message when that happens ;-)

Adding a Custom Object

The below code will look for a custom object by it's ID. In this case the ID is a user's email address. Since this always needs to be unique we can use it as the key, allowing for very quick selection of existing records.

importPackage( dw.system );
importPackage( dw.object );

function addSubscriber(email : String, gender : String){
    var result : String = "";
    try{
        var newsletterSubscriber : CustomObject = CustomObjectMgr.getCustomObject("NewsletterSubscriber", email);   
      if(!newsletterSubscriber){
          var newsletterSubscriber : CustomObject = CustomObjectMgr.createCustomObject("NewsletterSubscriber", email);
          result = 'added';
      } else {
          result = 'updated';
      }
      newsletterSubscriber.custom.gender = gender;
  } catch(e){
      result = 'failed';
  }
  return result;
}

There are a few things to note here:

  • Access to all Custom (and system) Object attributes happens via the Object it's "custom" property. Hence newsletterSubscriber.custom.gender instead of newsletterSubscriber.gender.
  • When you have got a custom object then changing its attribute value will happen by just assigning a new value to it. There is no "Save" method.
  • When the attribute is of type "Set of *", then some more work is needed, I will write about that in a follow up post.

Bottom line:

  • The custom Object definition cannot be set to be Replicable.
  • The script used for adding / changing Custom Objects needs to be transactional
  • To set attributes of a Custom Object instance you will need to use the custom property.

Well, that's it! I hope it helps someone, drop me a line via twitter if it did.

/Donovan