The Amazing World of RAZL Part 2 – Script Like A Boss

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>

  1. 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 !

The Amazing World of Razl – Part 1

As a Hedgehog employee I have the pleasure of playing around with all of their tools. I find it strange that many Sitecore developers haven`t realized the potential of Razl. Most of us consider it a DB compare tool which we can only use once or twice in our day-to-day job. While Razl is a DB compare tool, Razl has much more usages than most people think it does, so I decided to put a blog post around a couple of things that can be done with Razl.

Automated Content Synchronization between Production and Staging/QA Environments

Many Sitecore developers face the problem that the Staging/QA environments don’t have fresh content. A quality assurance team working with fake/old data, is not ideal and might cause some issues. For example, imagine a client disapproving a working module because it is hard to show how  it will work once it gets to production. This is a situation in which Razl shines. Razl’s APIs allow us to write which can synchronize the Staging/QA environments with fresh content on a daily/hourly basis. The scripts are fairly simple to write and they are even simpler to execute. The scripts can be run with your favorite scheduling mechanism. For more information about Razl Scripting you can check the following articles:

Introducing Razl Scripting (Follow @me_mikeshaw)
Official Razl Documentation About Scripting 
Razl Script Mode (Follow @mikeedwards83)

Setting Up New Development Environments

When adding new people to the team, setting up their Development Environments might be a long and painful process, especially with complex solutions. Razl makes it easy for the new developer to grab all the content and/or some other necessary pieces (custom modules, things from the core database, etc.) and start working.

On Demand or Automated Synchronization between Production and Development Environments

There are some situations in which bugs are caused by the live content and are hard to reproduce on development workboxes. Razl makes it easy to get the pieces that caused issues, bring it to their local environment and now the developers to properly debug them.

Keeping Track on Content Changes

Razl comes with History View that uses the Sitecore History Engine. The history view provides an amazing option to track what has been changed and who has changed it, so when something goes wrong it is easier to check what the cause is and who caused it. For more information about Razl History View, you can check the following articles:

Official Razl Documentation About History View
Razl History View (Follow @mikeedwards83)

Simple Way to Visually Compare CMS/Master Database and CDS/Web Database

Sometimes there might be problems with content publishing from CMS to CDS Servers. Razl makes it easy to track and resolve these kinds of problems. If anything goes wrong with the publishing process, and republish is not an option, Razl can be used to compare the Master and the Web Database. It allows us to check what was left unpublished and helps us identify the problem.

Simple Way to Migrate Content from QA/Staging Content to Production

Sometimes, especially in tight deadline situations, the content is entered on some of the Pre-Production Environments. Here Razl comes in handy to easily move the content between environments.

In conclusion these are just some of the core functionalities that Razl offers in our day-to-day work. It can also be used in other automation scenarios like automatic content synchronization on deploy, moving content across environments via workflow and etc.

Make sure to check out this places for more invaluable Razl Information:

The official Razl Documentation
Hedgehog Development Razl Posts
Mike Edwards Razl Posts

Happy Razling ! 🙂

The Amazing World of RAZL Part 2 – Script Like A Boss