Sitecore Corner

It has been almost a year from my first post about The Amazing World of Razl and the second part finally found its place in the posts pipeline. In this post I am going to dig deeper into one of the most amazing and useful Razl features – Scripting. Also for the brave ones who reach the end of the article there will be a sneak peak of the new Razl version! 🙂

First, let’s go through a real life scenario that every single Sitecore developer faced at some point. Many times we find ourselves slammed with bugs, which are caused by differences in content in our QA and Production Instances. So every single time we need to explain that our QA instance is not up to date with the latest Production content and that it is normal to have these issues. After that the frequent scenario is – “Can you please update the content, so we can regression test feature X”. Following that, we need to go to our Production CM, export a content package, and install it on our QA instances. The huge problem, with this, is that it happens pretty frequently. Especially on big projects with many content dependencies (i.e. I want to test the search boost I requested but I get only 2 search results in total). This is the case in which the Razl Scripting mode shines.

Razl scripts are actually a fairly simple xml files which can be executed from the command line. They have 2 main components – connections and operations.

Connections

Connections are actually a way to describe a Sitecore Instance that Razl needs to connect to. The basic XML for Razl looks like this:

<connection name="" readOnly ="" install="" preset="">



<url></url>



<accessGuid></accessGuid>



<database></database>



<path></path>



</connection>

So let’s explore what the different parameters and attributes do:

• name – This is the main identifier that is going to get used by the operations to determine the Instance they are going to execute on.
• readOnly – The possible values are true and false. Specifies if the connection is read only, i.e. if we try to execute a write command on a read only connection – it will not get executed. It is a good practice in your scripts to set your connection to read only.
• install– The possible values are again true or false. Specifies if the script should install the Razl Service if it is not already installed. If set to true – the path parameter must be specified.
• url– Used to define the url of the Sitecore Instance we want to connect to.
• accessGuid– Defines the access Guid which is used by Razl to access the Sitecore Instances. If Razl is already installed on the Sitecore Instance – the Guid can be obtained by reading it`s value from the web.config defined in [Webroot]\_CMP.
• database– The database which is going to be used by the connection. Nothing fancy here.
• path– The UNC path to the Sitecore instances. It is used only when you want to install the Razl Service on the server. My recommendation is to preinstall the Razl Service on all servers you want to script on, so you won`t have to expose your servers file systems.
• preset– If you already have the connection in the RAZL desktop application and you are too lazy to write some xml – you can use the preset property to pass the name as it is in your RAZL application. I usually advice against that, because you cannot be sure which presets are actually installed on the server and in most cases you won`t be the only person using the script.

There is no upper limit on how many connections you can define and naturally, you should have at least 2 connections defined in the script – because you are going to use it on at least 2 Instances (or 2 Databases of a single instance).

Operations

Operations are the way of script telling RAZL what needs to be executed. The basic operation XML looks like this:

<operation name="" source="" target="">

<parameter name="param">

<value></value>

...

</parameter>

</operation>

So let’s take a look at what the different attributes do:

• source– The name of the connection you want to use for sourcing Sitecore Instance/Database Combo (Copy From :))
• target– The name of the connection you want to use for targeted Sitecore Instance/Database Combo (Copy To :))
• name– Name is actually used for the operation types – CopyItem, CopyAll and CopyHistory. I will cover what each of the 3 operation types do later in this post as we need to get familiar with the parameters first 🙂

Every operation can have one or more parameters. All parameters have a name attribute, every operation type has a list of supported parameter names. Parameters themselves can be single valued and multi-valued.

Here is an example of a

1. Single valued parameter xml:

<parameter name="">[value]</parameter>

2. Multi-valued parameter

<parameter name="">

<value>[value]</value>

<value>[value]</value>

.....

</parameter>

As different operation types accept different types of parameters, I will describe them in a separate section.

Operation Types

Copy Item Operation

Base Syntax:

<operation name="CopyItem" source="" target="">



<parameter name="itemId"></parameter>



</operation>

Functionality:

The Copy Item operation copies a single item from the source to the target database. It requires one parameter – itemId which is the ID of the item in the source database. Nothing fancy here.

Copy All Operation

Base Syntax:

<operation name="CopyAll" source="" target="">



<parameter name="itemId"></parameter>



<parameter name="overwrite"></parameter>



</operation>

Functionality:

The Copy All operation copies an item and its descendants from the source to the target database. It requires 2 parameters – itemId which is the ID of the starting item in the source database from which the copying starts and overwrite is a parameter which determines what to do with items which are present in the target database, but are missing in the source database, i.e. if the setting is set to true and there is an item in the target database that is not present in the source – it will get deleted, if the setting is set to false – the item will be skipped.

Copy History Operation

Base Syntax:

<operation name="CopyHistory" source="" target="">



<parameter name="from"></parameter>



<parameter name="to"></parameter>



<parameter name="recycle"></parameter>



<parameter name="include">



<value></value>



</parameter>



<parameter name="exclude">



<value></value>



</parameter>



</operation>

Functionality:

I am sure many of you are familiar that Sitecore comes with a very powerful History Engine. The history engine uses a SQL Table to store all events that happened to an item. The history engine is enabled by default in the recent releases of Sitecore, before that you needed to enable that manually from the web.config.

The Razl copy history operation will read the actions from this table in the source database which occurred in a certain time frame and execute them over the target database. As this operation is more risky:) it accepts several parameters to give you better control over what is going on.

• The “from” parameter specifies the start time from which Razl should start reading events from the history table. The date needs to be in the following format: yyyy-MM-ddThh:mm:ss. This is the only required parameter of the operation.
• The “to” parameter specifies the end time when Razl should stop reading events from the history table. The date format is the same like the one for the “from” parameter: yyyy-MM-ddThh:mm:ss. Parameter is optional and if it is not set every event up to now will be executed.
• The “recycle” is a boolean parameter and it specifies what Razl should do with deleted items. If set to true it will move them to recycle bin and if set to false it will remove them (they will just be deleted not recycled). I strongly advise of always setting this parameter to true as you cannot be sure what the content editors might have done. The parameter is optional with a default value of true.
• The other two parameters (includeand exclude) are multi-valued and control which items (and their descendants) should be included/excluded when performing events. Both parameters work with item paths and exclude has bigger power over include (in case a path is included in both parameters). If the parameters are left blank – all actions will get executed. If there is a single path in the include – only actions over this item and its descendants will be executed.

I also created a small set of scripts which can be used for a good starting point when you are writing your own. The scripts can be found on BitBucket.

RAZL 2.6

And now – some spoilers! 🙂

There is a new release of Razl coming soon! 🙂

With the new release there are several new features, along with huge improvements to the scripting mode! Here are some of the highlights of the new release!

Lightning Mode

Razl 2.6 will introduce a new Lightning Mode for comparison. It increases comparison speed dramatically by using only the revision number when comparing!

Deep Compare

One of the most requested Razl features, deep compare will ship with the new release! Now you will be able to deep compare items without the need to go down the tree !

Scripting Mode Improvements

Razl 2.6 will introduce 5 new operation types:

1. CopyVersion – For copying a specific version of an item.
2. DeleteItem – For deleting items.
3. MoveItem – For moving items in the content tree.
4. SetFieldValue – For setting field values from a Razl Script.
5. SetPropertyValue – For setting property values !

Also – a new parameter lightningMode will be introduced for CopyAll and CopyHistory operations to use the new lightning mode for quick comparison of huge trees.

Make sure you stay up to date with the new Razl Features by

Razl Website: http://razl.net/

Hedgehog Development Website: http://www.hhogdev.com/

Our Twitter: @hhogdev

Happy Razling !