Category: Sitecore 8

Sitecore Experience Accelerator (SXA) is a great productivity tool as it reduces your development time by giving you pre-built components. There were few new concepts and features that were also introduced with SXA like Page design and Partial design, pluggable themes, grid and column layout etc, but as the topic suggest, I will be focusing upon “Rendering Variant” concept and will try to explain how can this change the way you architect your website (assuming that is based on SXA).

Problem Statement

Let’s begin with a problem statement, the UX team have prepared a landing page and they have the various content components on the page displaying Image, Rich Text and Link all in a box but in various styles as below:

Half-width component with Image and Text

Half-width component with Image, Text and Link

Full-width component with Image on Left, Text and Link on Right

Full-width component with Image on Right, Text and Link on Left

They also want the content authors to have the ability to add them, remove them and order them in any way they like.

Sounds familiar ?

If I am not using SXA module, one of the approach would be to make these different components available via Experience Editor which content editor can add/remove/order from the content page. This means that there will be different “View Renderings” for each of the components types. Different view rendering mean different Data Source Templates and Data Folder Templates. So for the simple content based components above, we end up having 4 different view renderings, which more or less have same content but it is displayed differently.

SXA Approach

There is nothing wrong with the above approach, but if you website is based on SXA module you would have another tool to meet your goal in a more effective manner.

The SXA provides a feature called Rendering Variant which optimizes the process of showing different variations of the same component. The variations can be setup via content editor and can also be supplemented with predefined styles and scripts.

The best way to explain Rendering Variants is by an example. I will be using the out of the box “Promo” component that comes with SXA. I am only interested in 3 data fields PromoText, PromoIcon and PromoLink (there are other properties too, but let’s keep it simple)

Promo Data Template

Rendering Variants are located under the /Site/Presentation/Rendering Variants node. In my case, the location was:

Out of the box there was one rendering variant already present as ‘Default’.

Default rendering variant

I made a copy of that component and called it ‘Promo with Image and Text’

Promo with Image and Text rendering variant definition

I then deleted last child item ‘Promo Link’ from the recently created rendering variant and clicked save. The ‘Default’ rendering variant was renamed to ‘Promo with Image Text and Link’ for readability purposes. And just by doing these few content item operations, I was able to achieve my 2 component variations (under like 1 minute, thanks to SXA)

To verify my changes I tested them out in experience editor. First I added a column splitter component to divide the page into 2 equal halves, then I uploaded some stock images, added the Promo component from the Toolbox in each of the half , added random text and selected my variants via the dropdown. They worked like a charm!

Promo with Image and Text, Promo with Image, Text and Link

Similarly, I created a copy of the existing variants and called it “Promo with Image left” . I then added a ‘Section’ item for the variant definition and called it ‘Container’. I then moved “Promo Icon” under it. I also added the bootstrap class of ‘col-xs-6’ to ‘Container’ item and to the ‘Promo Text’ item.

As you can see in the screen shot above, there are other types of variant definition items as well, check them out from the official site and see how flexible they are to give you almost any kind of rendering variation that you like.

For “Promo with Image Right” I created a copy of the “Promo with Image Left” and just reversed the order ‘Promo Text’ and ‘Container’ sections:

Image Left and Image Right rendering variant definitions

To verify my changes, I navigated to the Experience Editor, dropped the ‘Promo’ component on the page and changed its rendering variant via the dropdown to get the results below:

Promo component with Image LeftPromo component with Image Right

And that’s it, without even writing a single line of code, I was able to get all 4 component variations. In theory the number of variations that could be achieved using rendering variants are unlimited and totally depend upon your UX and Design.

Conclusion

If you are starting a new website based upon SXA module, you must consider rendering variants for your components as it will change the way you architect the website. This was a simple post but it showed the true power of SXA and how Rendering Variants can reduce back-end development efforts and also improve the content authoring experience. Kudos to SXA development team for this awesome feature!

Have fun

Note: If you want to play around with the, here is the link to the rendering variant package. I have used Sitecore 8.2 update 5 and SXA 1.5.

Back in May 2017, we started working an new and exciting project with Sitecore version 8.2 update-3. I was setting up the continuous integration/auto deployment for the project. Once CI/CD was setup as described in my previous blog posts I encountered the issue that Sitecore Ship module, which is responsible for synchronizing the Sitecore content items, was not working as expected. It was showing a 200 OK response in the Team City logs but in reality it was failing silently.

Doing a quick google about the issue I found at that I am not the only one having the issue, there are other people who are experiencing the same issue as well. I also came across this blog by another Sitecore developer who was facing exactly the same issue and he decided to switch to TDS package deployer instead of Sitecore Ship.

I haven’t personally tried out the TDS Sitecore package deployer before and looking at the blog post decided to take this approach. It was fairly easy to configure package deployer and after adjusting some of the Team City build steps, the .update package deployment started working!!

After testing package deployer with the continuous integration setup for few days, I realized that although the build process is copying across the .update files, there is no feedback from the package deployer (or a 200 OK response) that package has been installed successfully. In order to confirm, I have to RDP or FTP to the server and check that .update files have been correctly installed or if they have failed for any reason.

So back to square 1, let’s figure out what is wrong with Sitecore Ship ?

Interestingly, there was also a pull request #69 submitted to fix this issue with 8.2 update-2 in Jan 2017 which had some really positive feedback. As of today, this pull request has not been merged to the main repository or available via NuGet gallery.

In my case, the project was on 8.2 update-3 (one update higher than the submitted pull request version), and it wasn’t a straight forward fix. I was skeptical but I decided to repeat what has been done in pull request #69 and compile it against 8.2 update-3 version of the Sitecore and try it out.

This is what I did to get my fix:

1-Cloned the GitHub repository locally

2-Updated the solution’s .NET version to 4.5.2

3-Updated the Sitecore NuGet package version to 8.2 update 3

4-Modified the code for Sitecore.Ship.Update.UpdatePackageRunner class as mentioned in the comment section (and below)

5-Build and compiled the code and then replaced the dlls in the bin folder on QA server.

6-Ran the Team City build server script again and it worked like MAGIC!

The underlying issue, as mentioned in one of the comments ,was that there has been some updates to the Sitecore.Update.dll and the code that was responsible for deploying the items was not working any more. Also the solution’s target .NET version has to be upgraded to 4.5.2.

I believe that the pull request will be tested and merged into the main repository soon so everything is available via standard NuGet packages. However if have read till here and using either 8.2 update 3 or update 5 for your CI/CD setup, you can download the compiled dlls from my dropbox and give it a go!

For 8.2 udpate-4 you either wait for the NuGet package or do what I mentioned above.

By default, we can use emails as notifications whenever CI server triggers a build or when source control detects a check-in, but in my opinion, this is not the most effective way. Depending upon your team size, there may be many check-ins every day, and many CI builds. If you start getting hundreds of emails everyday, you will simply create a rule/folder where all such emails will be directed and forgotten.

Also, not all of your team members will receive such notifications emails and you still have to send a ‘pre deployment’ email to notify team and ‘post deployment’ email to confirm that deployment has ended.

If you are a team lead or QA or PM, I am sure you would have asked or heard questions like these:

‘When are we deploying latest build on QA?’

‘Is our latest build finished on QA?’

‘What all did we deploy?

… and so on.

There are better communication tools out there like Slack or HipChat. You can integrate either of them or another messaging tool of your choice. Personally, I like Slackand will be discussing how to integrate Slack with our TeamCity server and BitBucket project in this blog post.

Step 1: Create a Slack Channel

If you don’t have a Slack account, create a free one. Then create a free Slack channel for your project, invite all team members and also create 2 open public channels for incoming notifications:

#bitbucket

#teamcity

Step 2: Configure TeamCity for Slack Notifications

Navigate to Apps and Integration section and click on the link

Step 3: Generate a webhook for CI server

Within the slack admin interface, search for incoming hooks:

Select ‘Incoming Webhook’ and then select the one of your channel:

Once you click Add Incoming WebHooks integration, it will generate a unique Webhook URL, copy this URL for later.

Once it is installed correctly, for every build start, build finished and build failed you and every team member will get a notification in the channel. How cool is that 🙂

Step 6: Generate a webhook for BitBucket

Slack is also very friendly with BitBucket source control. Search for a BitBucket integration on Slack and generate a Webhook URL for your #bitbucket channel

Step 7 : Configure Bitbucket

Within your bitbucket admin interface for the project, navigate to settings and add a new webhook for the channel. Copy/paste the URL that was generated.

Once it is done, commit and push some changes, you will start getting notifications in Slack!

…

So now every time someone in your team is going to do a check-in, you and all your team will get a notification. Install Slack for mobile and desktop and keep tracking those notifications.

With this blog post, we have come to the end of the Sitecore DevOp Series.

Thanks for the reading the blog post and the series, I hope it will benefit the Sitecore community. Any comments feedback will be appreciated.

Naveed.

Updated April 2017

My Talk at DC Sitecore User Group

Short video demo

Updated September 2017

Extending To Helix Principles

The project setup shown in blog series was simple as it was intended for the newer audience and I didn’t want to add complexity of Helix principles. Having said so, if you are starting a new project based upon Helix principles, you can easily extend the automated deployment setup as shown below.

All you have to do is add foundation, feature or project specific TDS projects for content item serialization and add additional steps for TDS projects in the Team City server. More details about deployments using helix principles can be found here

I am assuming that you have gone through the previous 6 parts and completed them as this blog post will depend upon them. I am also assuming that you have a brand new CI server with following applications installed:

This is a pretty lengthy blog and contains with lots of screen shots for every step of the TeamCity server configuration. If you get stuck at any point please look at the CI build logs, QA server logs and utilize Google to resolve your errors/issues.

The blog series is aimed at newer audience and developers who are setting up CI for the first time.

Step 1: Create TeamCity Project

Once TeamCity is installed, create your TeamCity project:

Once the project is created, you will have the ability to configure it with your source control:

Step 2: Configure with Source Control

Select ‘Create build configuration from URL‘ and give the source control URL of your project along with login details.

If your connection details are correct, you will see the confirmation screen like below:

Step 3:Configure Build Steps

Now its time to configure your build steps. The TeamCity will try to auto-detect your build steps:

If everything on the server has been configured correctly, it will configure the VS build step:

Step 4: Configure NuGet step and re-order

Create a new step by clicking on ‘Add build step’ and add a ‘NuGet Installer’ step type. Specify the path to the solution:

The build steps will be executed in the sequence they are ordered, so you need to re-order them. Click on ‘Reorder build steps‘ and put NuGet installer step before the VS build step:

If you are using any front-end frameworks, like Gulp or Grunt, you can also add a step for them using Node.Js as runner type.

Step 5: Configure Parameters

As we have added 2 steps, at this point we should test our CI server with only these 2 steps and try to fix any errors before proceeding further. Before we run the build, we need add some configuration parameters and tell TeamCity to use our QA publish profile so it can correctly transform the config files. The configuration parameters can be added in-line within the build steps but a better way is to add them as system parameters. Navigate to the ‘parameter‘ section to add parameters:

By clicking ‘add new parameters‘ a dialog box will show up, you can then add ‘System‘ parameters for your build as shown:

Repeat the process of adding new parameters and add all of the following parameters for your initial build. Update the system.username and system.password values relevant to your CI server. The system.PublishProfile should also be updated as per your VS project’s publish profile name:

Step 6: Run a Test Build

Click on the ‘Run’ button and test your build for the 2 steps that you have added:

I only had 2 steps, but I still got some errors on the first build which I resolved by looking at the ‘Build log‘ (like I missed a file to push to bitbucket and then my password was incorrect). After few attempts, I saw the green tick which was very re-assuring. So if your build fails for the first time, it’s OK, work through the build log and remove errors:

Step 7: Configure Sitecore.Ship

As of now, we were only deploying code files from VS with our 2 steps. But we also want to deploy our Sitecore Items generated through TDS update packages. By default, you can use TDS to deploy .update packages, however, there are other alternatives too. I am going to use an open-source module Sitecore.Ship which deploys update packages over http requests. The module should be configured as NuGet package with you main web project:

Once you install this, you will notice that there are some changes in your web.config files as well, check-in all of your changes and push them to the server.

Step 8: Configure TDS.Master

The next step is to configure TDS.Master to generate an update package. Navigate to MyProject.TDS.Master project’s properties, make sure the build mode is ‘Release‘ and update the settings as shown below:

Once you will build this, it will generate an .update package at a location bin/package_release

Step 9: Add a build step for TDS Master

An update package has been generated, now we want to deploy and publish this package along with our code to the QA server. We will be using curl to post HTTP request for update packages. Chocolatey is a package manager which can give us access to curlthrough its command line.

The deploy and publish step depends upon some configuration parameters. Navigate to parameters section and add the following configuration parameters:

Step 10: Run a test build for TDS.Master

There were few tools and configuration were settings introduced in the previous steps and to make sure everything works as expected perform a test build. If it fails, look through the logs and try to resolve issues. Some places where you also want to look are Sitecore Logs (in the data folder) on the QA server and website/temp folder on the QA server.

When I ran the first build, I got 500 error in the TeamCity build log for the TDS.Master deploy step. The error messages within the build log for Sitecore.Ship are not exact messages and may be misleading, you need to check the logs on the QA server for correct messages.

When I checked if Sitecore.Ship is installed and accessible fromm the CI server, I was getting 401 error:

and when I checked this from the QA server, I was getting everything is OK

When I checked the Sitecore logs on QA server, I got the following message

Which meant that I have to update the ‘allowRemote’ settings to ‘true’ in the web.config to allow remote package installation. The feature is disabled by default for security reasons. I also added IP address of the TeamCity server to the whitelist section and made my remote deployments IP protected:

Once checked-in and pushed to the server, I got some more errors related to missing folders and permissions. I was able to resolve them by checking the logs and giving NETWORK SERVICE permissions to the folders.

Eventually, the deploy step succeeded and I was able to see Sitecore.Ship posting my entries from the CI server to the QA server:

This is great news, it means that when I check-in TDS items and related code, I do not need a package to update the QA server ‘manually’. I can just run the build and it will pick up the latest changes and deploy them.

Step 11: Configure a TDS publish step

The previous step has only deployed our update package. We also want to publish our package post deployment. We can configure a publish step through curl and Sitecore.Ship

Navigate to the ‘Build Steps‘ section and add another ‘Command Line‘ step for publishing. Add the custom script as shown below:

Re-order the steps so you have core packages deploying before the master packages. Your build steps should look like below:

Depending upon your project and business requirements, you may want to add more steps like ‘Unit Testing’ or ‘Integration Test’ or other steps.

Step 13: Configure Triggers (Optional)

One optional thing to do is to configure trigger for the QA server, so that every time someone pushes the code to the source control, an automated build is started:

This is optional and you shouldn’t be configuring this step for the production environments

More Environments

The blog post only showed how to add build steps for the QA environment, but you may have a UAT environment, a staging environment and a production environment. You can repeat the build configuration process and add more automated deployments for each of your environment.

The steps mentioned here are only an example and meant to provide the basics of setting up CI integrations. Once you get comfortable, you can enhance number of steps and/or use different deployment strategies.

Final Thoughts

As you have seen, it took few blog posts to get the Continuous integration working, but once it is established, it will save you tons of time during the application development and even post-launch. If your organizations sets up projects frequently, the time to setup QA, DB and CI servers and local environments can be further reduced by using standard PowerShell scripts.

One final optional blog post about Slack notifications is coming up next few days and then it will be a wrap.

Assumptions

I am assuming that you have RDP access to at least 3 Windows based server within your local network/organization. From the diagram below, the QA server will host CM and CD part of the website (qa.myproject.local). The DB server will host SQL server and MongoDB databases. The CI server will host the TeamCity server (teamcity.myproject.local). The blog series is based upon Sitecore version 8.2

This is only a QA setup diagram, for staging and production environments, it is strongly recommended to add separate CD and CM servers.

Setup MongDB to run as Window Service and open the relevant ports from the windows firewall utility on the DB server for incoming and outgoing connections.

Alternatively, if you are new to MongoDB and not sure how to configure and install MongoDB, you can also use mlab free Sandbox environment which gives 500 MB of free storage. You can setup your MongoDB servers following this post and just update the connection strings for the QA server config file.

Step 2 : Install Sitecore Databases

RDP to the DB server and install Sitecore using the official installer. During the wizard steps, select the ‘New Instance‘ option and then select ‘Database Only‘ option:

Follow the installation wizard as per the installation guide and complete it.At the end, you should have the following 5 SQL databases:

Core, Master, Web, Analytics and Session

Step 3 : Configure QA Server

RDP to the QA server and using the official installer, select ‘New Instance’ and ‘Client Only’ option:

Follow the installation wizard and complete all steps. Update your local DNS server or your own hostfile so that http://qa.myproject.local point towards the QA server. Login via the CMS interface using default admin credentials and complete the post-deploy steps from the installation guide.

Step 4: Configure Web Deploy on QA Server

Web Deploy is an IIS extension/utility that provides ability to deploy new updates on the website using IIS only. If your server does not have this utility for IIS, install it via standard installer.

Publish Profile for QA server

Open the VS project and import the profile for the QA site. You can open the publish profile using notepad and re-name the profile name. Make sure you can validate the connection for the publish profile. If you are getting errors, please resolve them using this post before proceeding further:

XML transform files for QA profile

Add XML transform files for the new ‘qa‘ publish profile. As a minimum, add transforms for ConnectionStrings.config and Sitecore.config. You will be required to update values for connection strings and dataFolder:

Try to publish to the QA server via VS project, if everything has been done correctly, you should see the successful message. Navigate to http://qa.myproject.local and ensure everything is correct. If there are errors, resolve them before proceeding further.

This ensures that Web Deploy is configured correctly and there are no permissions or network issues. This is only the initial part, what we really want to build and deploy from our CI server and not from a local machine of a developer.

Step 5: Setup CI server (TeamCity and Plug-ins)

Assuming it is a brand new Windows server with nothing installed, you need to download and install the following the TeamCity server

All of the above tools have a standard Windows base installer and they follow ‘Click Next’ type wizard to complete. Once all these utilities are installed, we will begin setting up the CI server in next blog post.

In this blog, we are going to add our VS project to a source control. As a developer or as an organisation you have many options available to select your source control like SVN, TFS, or Git . The choice of source control depends upon your business requirements or your client’s requirements.

For the purpose of the blog, I will be using bitbucket.org with repository type as Git. The blog series is aimed at newer audience and developers who are setting up CI for the first time.

Assumptions

I am assuming that the person reading this post has never used Git or Bitbucket before, so I will be doing a step-by-step description. If you have not used Git before please spend 1 hour reading about it’s basic operations and install a Git client like Tortoise Git or Source Tree. I will be using Tortoise Git for the blog post. If you are a git pro, you can ignore this blog post as all we are doing in the post is setting up our project with BitBucket.

Step 1 : Create a new repository

If you don’t have an account with bitbucket.org, create a free account. Then from Repositories top-menu create a new repository. For the blog series, I created ‘MyProject‘ repository as shown below:

once you have created the repository, you will get an admin interface that will look like this

Step 2 : Create repository locally

Once you have created repository on bitbucket.org, you want push your changes to the server. Before you can do that, you need to right-click the ‘MyProject‘ folder and select ‘Git create repository here‘ as show below: (you will get these options if you have installed Tortoise Git)

Step 3: Commit changes locally

The next step is to commit your changes locally. Few things to remember

Only commit what you think is required to be source controlled

Do not commit run time changes like /bin folder or /debug folder

Do not commit cache items as they will be local

For example, using tortoise git and right-clicking on the ‘MyProject‘ folder, if I do not want to add MyProject.TDS.Core/bin folder and all the files in that folder, I will just add that folder path to .gitignore file as shown below:

As a minimum, I will also add a .gitattributes file and add the following settings as a minimum:

Sitecore Glass

Sitecore Glass is an Object-Relation-Mappper (ORM) for Sitecore items. A common ORM that you may have worked previously would be Linq to SQL. Sitecore Glass helps in referencing Sitecore data item properties by using strongly typed C# objects. It is an open-source project and more information and tutorials are available from their official website.

Step 1 : Install Sitecore Glass for domain project

Sitecore Glass Mapper is available as NuGet package from the official Nuget feed server.
Assuming you have setup the ‘MyProject.Domain’ as per the previous post of the blog series, add a reference to the ‘Sitecore.Kernel.dll‘ within ‘MyProject.Domain‘ project:

Then add the official package via NuGet:

Remove the ‘App_Config‘ and ‘App_Start‘ folders from the ‘MyProject.Domain‘ project and add a custom class file as ‘Models.Generated.cs‘

Step 2 : Install NuGet package for main project

Install the same NuGet package for the ‘MyProject‘ , which is your main MVC project.

As of now, upon successful installation, you should see references to Glass.Mapper, Glass.Mapper.Sc and Glass.Mapper.Sc.Mvc.

Step 3 : T4 Templates for Auto-Code Generation

As a starter, download the T4 templates as provided by the HedghogDevelopment github repository .

Navigate to ‘TDS.Master’ project properties > code generation tab and check the box for ‘Enable Code Generation’. A folder will appear in the VS tree view as ‘Code Generation Templates’.

Copy the downloaded T4 Templates files (with extensions .tt) that you downloaded from github within that folder and include them in the project via VS.

Set the Target Project as ‘MyProject.Domain‘

Set the code generated file as ‘Generated.Models.cs‘

Set the base name as ‘Models‘

Set the header transform file as glassv3header.tt

Set the base project transform file as glassv3item.tt

When you hit save, the Models.Generated.cs should give you auto-generated code for the ‘Sample Item‘ template as below:

This is pretty amazing if you are doing it for the first time as now you can auto-generate your Sitecore data template properties and reference them in your main project as strongly typed objects. Every time you make a change to Sitecore templates, all you have to do is right-click the TDS.Master project, do a sync with Sitecore and it will update the code base. You can also ‘Re-Generate code for all items‘ as shown below:

Adding reference to Glass mapper and configuring TDS project with code generation will make sure that any field name changes that you make in data templates are reflected back in the code. If there are any compilation issues due to referencing make sure you .NET version is correct.

We are all done in setting up the project locally, the next step is to add our project to a choice of our source control so it can be shared with rest of the team and with our build server. This will be explained in the next blog post.