Tips to troubleshoot SDL Tridion Reference Implementation installation

Installing STRI is not a difficult process, however there are a several manual steps and actions, that we can (and will) forget. Hope that the following tips, based on my own mistakes help you save some time debugging, if I have not made all possible mistakes … I’m probably very close!

IMPORT ISSUES

When running the import script, the process may be aborted with some errors. These errors will appear directly on the PowerShell script

1.- Powershell Error

 

ERROR:

Initializing types for ImportExport …

Add-Type : Could not load file or assembly ‘file:///D:\Install\SDL Tridion Reference Implementation v1.0

GA_tcm89-21378\ImportExport\Tridion.ContentManager.ImportExport.Client.dll’ or one of its dependencies. Operation is

not supported. (Exception from HRESULT: 0x80131515)

At D:\Install\SDL Tridion Reference Implementation v1.0 GA_tcm89-21378\import\import.ps1:73 char:5

+     Add-Type -Path “$($localDllFolder)Tridion.ContentManager.ImportExport.Client …

+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    + CategoryInfo          : NotSpecified: (:) [Add-Type], FileLoadException

    + FullyQualifiedErrorId : System.IO.FileLoadException,Microsoft.PowerShell.Commands.AddTypeCommand

Possible Cause:

  • Windows has blocked some of the DLL’s after download. Before extracting SDL Tridion Reference Implementation zip file, check the file properties, and click on the “Unblock” button

2.- Unblock

  • Powershell has not been started using Administrator permissions

 

ERROR:

Tridion.ContentManager.FilterException: The Filter condition ‘ForRepository’ is invalid. The item tcm:0-3-1 does not exist.

Possible Cause:

  • An ECL Event Handler is interfering with the import Script. Disable ECL Handlers on %TRIDION_HOME%\config\Tridion.ContentManager.config

3.- ECL Disable

ERROR:

Exception calling “StartImport” with “2” argument(s): “There was no endpoint listening at

http://http//cms.electridion.com/webservices/ImportExportService2013.svc/basicHttp that could accept the message. This

is often caused by an incorrect address or SOAP action. See InnerException, if present, for more details.”

Possible Cause:

  • [string]$cmsUrl parameter is probably wrong configured on import.ps1
  • You are trying to install STRI in a version of SDL Tridion previous to 2013 SP1, where there was no ImportExport service. Although it is technically possible to use STRI in some of the previous versions, some modifications are required and you should know what you are doing.

PUBLISH ISSUES

When publishing we can find a few issues, but most of them are easy to identify and fix. The place to check is usually the Publish Transaction, processed Items tab

4.-Transaction2

ERROR:

Could not load file or assembly ‘System.Web.Helpers, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35’ or one of its dependencies. The system cannot find the file specified.”

Possible Cause:

  • NET MVC5 is not installed. You can download it from its website: [http://www.asp.net/mvc/mvc5]

ERROR:

‘C:\Program’ is not recognized as an internal or external command, operable program or batch file.

Possible Causes:

  • JS is not installed. Download it from its website: http://nodejs.org
  • We have modified the default installation directory of Node.JS. In this case it is also required to modify it on “\100 Master\Building Blocks\Settings\Core\Site Manager\HTML Design Configuration” configuration component

5.- HTMLDesignConfiguration

 

ERROR:

ENOENT,  stat ‘C:\Windows\system32\config\systemprofile\AppData\Roaming\npm’

Possible Cause:

  • This is a known issue. Due to a glitch on Node.js installation, we need to create the specified folder manually and grant read / write permissions to “Network Service”

ERROR:

The publication fails on transport

6.-Tansport Failed

Possible Cause:

  • The size of the publication package is higher than those one allowed on the default configuration. It is required to create a web.config file on the root folder of the HTTP Upload web application

The web.config should contain the following:

 

<?xml version=”1.0″?>

<configuration xmlns=”http://schemas.microsoft.com/.NetConfiguration/v2.0″>

<system.web>

<httpRuntime executionTimeout=”1200″ maxRequestLength=”512000″ useFullyQualifiedRedirectUrl=”false” minFreeThreads=”8″ minLocalRequestFreeThreads=”4″ appRequestQueueLimit=”100″/>

</system.web>

<system.webServer>

<security>

<requestFiltering>

<requestLimits maxAllowedContentLength=”524288000″ />

</requestFiltering>

</security>

</system.webServer>

</configuration>

 

ERROR:

I can’t publish the pages on 400 Example site. There are no options on the publishing dialog

7.- notargets

Possible Cause:

  • Your publication target is not created, or not attached to the 400 Example Site publication
  • The permissions are not set on the Target Type or the current user is not allowed to user the target type

 

WEBSITE ISSUES

A number of issues can happen when trying to run STRI for the first time. These are the most complicated to troubleshoot, as the error is usually not very descriptive.

 

ERROR

 

Unhandled Execution Error
Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code.

Exception Details: Java.Lang.Exception

Source Error:
An unhandled exception was generated during the execution of the current web request. Information regarding the origin and location of the exception can be identified using the exception stack trace below.

Stack Trace:

[Exception]
Codemesh.JuggerNET.JavaClass.ThrowException(Exception ex) +88

 

Possible causes:

  • If you find in site.log a long stack trace with the following error: “Caused by: org.hibernate.exception.SQLGrammarException: Could not open connection”. It is very likely that Database credentials on cd_storage_conf.xml are wrong.

ERROR:

Value cannot be null.
Parameter name: paths
Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code.

Exception Details: System.ArgumentNullException: Value cannot be null.
Parameter name: paths

This error is very common, and means that your web application cannot fetch the configuration resources form the Broker database. However this can be caused by a number of configuration issues

Check The cd_core log configured on your web application logback file.

If you find the following error, then this is as easy one:

ERROR BinaryMetaFactory – BinaryMetaFactory.getMetaByUrl(): Could not query by URL /system/_all.json in publication 3:

com.tridion.broker.StorageException: License is not valid or expired, the requested DAO was mapped to non-filesystem binding and could not be loaded

It is quite self-explanatory. You need to copy your cd_license.xml file, inside /bin/config folder of your web application.

 

If you see the following error:

 java.lang.ExceptionInInitializerError

2014-09-23 21:07:02,361 [1] ERROR – Could not initialize class com.tridion.storage.StorageManagerFactory

================================================

Some configured classpath roots cannot be found

================================================

     ClassPath           : C:\inetpub\wwwroot\TestStaging\bin\bin

…..

 

  • It is possible that sqljdbc4.jar driver has not been copied into the lib folder of your web application. You can download the SQL driver from: http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a737000d-68d0-4531-b65d-da0f2a735707&displaylang=en
  • It is also possible that “Publish Settings” page has not been published to Broker Database. The best way to make sure they have been published is to check into the Database items table of the broker database. You can use the following query: SELECT * FROM [Tridion_Broker].[dbo].[ITEMS] where TITLE like ‘Publish%’

If you are sure that the page has been published, but it appears nowhere on the Database, double check your deployer and make sure that you are publishing to the Broker Database and not to Filesystem. STRI needs you to publish to Database. Another good indicator that you are publishing to file system is that your Web Application folder is suddenly cramped with new folders and pages

  • If there is no error on the logs, it is very likely that cd_dynamic_conf.xml is not properly configured.

Make sure that <Publication Id=”3″> node maps to your website ID. And make sure that the HOST node is properly configured:

<Host Domain=”localhost” Port=”99″ Protocol=”http” Path=”” />

When your web application is running directly on the domain name as host, it is not required to add anything on the path attribute, don’t let the error misguide you.

 

If none of the previous tips helped, you can also check the permissions of your website folder in the file system, and grant read/write permissions for the identity user running your website. However I have seen this issue in very rare cases

Getting your hands dirty

Still stuck after trying all previous tips?, it is time to debug the application for real. You can find instruction to setup the Visual Studio project on the following SDL Live Content links:

Debugging your application step by step will allow you to dig deeper into the STRI Example website, learn more about its architecture and hopefully fix your bugs.

 

Found any other common error? Post a comment and I will get it added to this guide!

Who moved my Renderer?

After my previous post where are my TCDL tags executed?, a colleague, asked me. “But those are not the custom renderers I know!?”

And indeed I might have been sucked into the terminology confusion existing on the renderer term, so lets make things clear.

There are two types of “Renderers” involved in a Tridion publishing transaction. One takes place on the Publisher and is not related to TCDL at all, and the other (the one I was talking about), happens on request time.

It seems like in the early stages of introducing the content delivery side renderers, the official name was Dynamic renderer, however I could not find this term on SDL Live Content anymore. Anyway I like that name to create a clear distinction and updated my previous post to use it. So from now on, I will plead for this terminology.

What are these publisher custom renderers? Custom renderers are used to modify the output of the rendering process. So right after the publisher has combined your component and your template, the custom renderer will kick in to make any other modifications required.

1.- Content Distribution Extended2

 

Zoom in

2.- Publisher_service_zoomin2

Custom renderers have much more in common with custom resolvers than with Dynamic Renderers. In fact, they belong to the same parent namespace: Tridion.ContentManager.Publishing and are registered in a similar way in the Tridion.ContentManager.config file, also making clear that we are dealing with a CM side component.

Publisher Custom Renderer Deployer Dynamic Renderer
Executed on the Publisher service Executed on request
Implements Tridion.ContentManager.Publishing.Rendering.IRenderer interface Implements com.tridion.tcdl.TagRenderer
Configured in Tridion.ContentManager.config Configured in Configured on cd_dynamic_conf.xml

 

The use case for a Custom Renderer is not very clear, as most the actions you would be tempted to hook in here, have another more appropriate extensions point.
When NOT to use a custom renderer: When NOT to use a custom renderer:

    • When you want some actions to be triggered after your page is published. You have the Event System for that purpose
    • To deploy your renderer content to a different content repository, location. You must use a Deployer or Storage extension here for multiple reasons like transactionality, be able to keep track of published/unpublished items, receive the correct status on the publishing queue, get your TCDL resolved… it would be a big mess and would skip the whole content delivery layer
    • To post-render your rendered templates. So you want to render, and re render again with code hidden on an obscure point out of the compound templating framework? Don’t make things harder than they are and just use a .NET TBB. If you want to apply these code to every template, create a “Finish Action” compound TBB and store it there

A valid use case for Custom Renderers A valid use case for Custom Renderers

    • From my experience, the only situation where I have found myself using publisher custom renderers is to modify the Publish Instructions. Specifically my requirements were to modify the publishing time of pages, to match certain requirements. IRenderer interface allows us to access to the PublishInstruction object, which contains among other members, the StartAt or DeployAt Modifying these DateTime values will result on a scheduled publishing transaction or separate deploy transaction. This action can be manually performed by the editors on the publishing dialog. However if we want to enforce a policy or implement some business logic rules, a custom renderer is the perfect place to do so.
CME Dialog to schedule content publishing

CME Dialog to schedule content publishing

Top 10 features of Tridion Reference Implementation V1

For as long as I have been working with SDL Tridion, the most similar thing to an example implementation was the, non-openly available, SDL education implementation. But finally the much awaited Tridion Reference Implementation is released. You will be able to find it rather modestly under the extensions section of SDL Tridion World

This V1 is still a “work in progress”, and is meant as a (fully working) preview of what’s to come in SDL Tridion 2015. Integration with other SDL modules like SmartTarget, Audience Manager, Media Manager and a Java version with functional parity are still to come, but for now, let’s have a glimpse of some of the 10 best features we can find in the current package

1 Semantic Model Mapping

1.- Model Mapping

At the very core of the TRI, we can find the semantic model mapping engine. During its inception, there was a very clear vision of creating a frontend framework which would be agnostic of all Tridion concepts. Content Manager Schemas would not be relevant for our MVC application, so there would be a different content model on the presentation domain, which would make sense with the content and design and should be generated automatically. Oh! And the presentation domain models should also contain semantic meaning, plus embed it on the output HTML. Sounds awesome, what if we also backtrack the CMS model to be able to create the XPM tags automagically? Done.

Of course the full detail of what happens here is much longer, and not so romantic, but it is important to understand how all these concepts come together. However that’s another story for another time.

 

2 PowerShell Installation Helpers

I refrained from using the term, installer, as these PowerShell scripts don’t fully qualify yet as installers, because guess what, Tridion is still Tridion, and will always require a smart guy on the other side of the keyboard. Thankfully we are there.

 

2.- Powershell Import

These scripts will make your life much easier though, by creating a (simplistic) blueprinting, importing the default folder structure, schemas, TBBs, templates, content, pages and then deploying the website code.  There are still some tasks you will have to do manually, like configuring the publication targets. This is an action that is not possible to automate via API currently, but as “Publication Targets will be deprecated in SDL Tridion 2015” that may not be so relevant for the final version of TRI…

 

3 Modular Architecture

3.- Modular Architecture

TRI has been built thinking ahead on terms of modularity. There are a group of functionalities, which are part of the “Core”. These are the pieces that have been considered to be common to every Tridion implementation (a set of basic, schemas, tbb’s and functionalities). On top of this, new modules can be added on a modular and documented way. So you can expect future search extensions, Instagram extensions, analytics extensions… or anything you can imagine… Can this be the bridge to a future TRI Module Shop? Further look into the license terms would be needed, but what about commercial TRI modules?

 

4 Responsive, XPM Enabled, Fully Working HTML 5 Website

4.- Website

Out of the box your get a withe label website, simple and clean enough to use as a playground or as a base to build your own. The HTML is tested with XPM, so most of those glitches that result of XPM wrestling your CSS should be solved. Moreover the HTML 5 designed for this website, can (and should) be used as a framework by your design team, to create your own pages. This HTML is in the download Zip file, under the HTML folder, and is built using bootstrap, grunt, less, node.js and all the new buzzwords that will make your designers excited to work with.

 

5 Official Documentation

Yes, as part of the efforts for revamping and elevating quality standards for SDL Tridion documentation, we can find the official TRI implementation on SDL Live Content from day one. This should grow into the one stop shop for administrators installing the software, developers looking to extend the functionality and even editors.

5.- Official Documentation

 

6 Contextual Image Delivery

This tiny part of the Contextual Web Delivery allows us to send the right image size for the right device [LINK http://www.createandbreak.net/2014/04/what-does-contextual-image-delivery.html]. If you use a portable device, we will send a smaller, less heavy image, if you use a retina device; we can send you a high resolution stunning version of the same picture. That useful, that simple… as long as you know your maths

 

7 Navigation

I don’t know you, but I’m pretty tired of building the almost exact same navigation implementation again and again. If I don’t have to ever do it again, the TRI will be worth it for me (I know, keep dreaming). TRI Navigation works as you would expect by SDL Tridion best practices, there is a Sitemap page on your website which will update your navigation when published.

 

7.- Navigation

 

Out of the box you get:

  • Top navigation
  • Left navigation
  • Breadcrumb
  • Sitemap Page
  • Google sitemap

Easy, simple, code required: 0

 

 

 

 

 

8 Multi Language Website Functionalities

Tridion is top class in multi-language, CM side is fully prepared to accommodate your language structure and translations needs, but again, how many times have you recreated the same Multilanguage modules on the website. Yes, I’m referring to the language drop down on the header, and the website being aware of the current language

8.- Multilanguage

Did you ever get your website all screwed up as soon as you added a second language after the development phase was completed? … Exactly

 

9 integration with the most common social networks

You can start sharing, tweeting, g+’ing your Tridion reference implementation pages out of the box, and who wouldn’t want to do that? Also embedding Youtube videos, so it’s time to retrieve all your lolcats videos and share them with pride… and in style

9.- SharingButtons

10 Security model

10.- SecurityIt all starts with “Why can’t just make everyone administrator?”, or “After all, everyone should be able to see everything”… and minutes later I have to wheel out my axe to reinstate the law and order. Do yourself a favor and start with a proper security model. Tridion Reference Implementation security model will not be enough for a real life scale organization, as it only includes 3 roles “Site Manager, Editor and Developer”, but it reinforces the idea that you should always start with a security model. It will hide complexity from your editors, lead to a less bloated interface, faster GUI response times and well… security… so people won’t touch things they are not intended to. Oh, btw, my first quote finished with a: “Why can’t I delete this publication?”

 

When are my TCDL tags executed?

TCDL tags add yet another extra layer of abstraction in our Tridion implementation, but also yet another layer of confusion. I have noticed a common question, when are these TCDL tags being executed? Or it’s variant, when are dynamic renderers executed?

First thing to know is that there are 2 types of TCDL Tags: Renders and Handlers

According to SDL Live Content, Handlers get executed on publishing time, while Dynamic Renderers get executed on request time. However this is not entirely accurate, as handlers are executed during the publish transaction, but are actually executed by the deployer, not by the publisher service.

 

1.- Architecture Diagram

The fact that handlers are configured on the cd_deployer_conf.xml already gives us a hint, but if we inspect the transport package on the incoming folder, we will see that the files, ready to be picked up by the deployer still content TCDL tags.

Apart from this, if you have ever seen code examples for either TCDL renderers or handlers, you will notice that they look very similar. And actually they are, the logic performed inside is pretty much the same, the main differences are:

 

Tag Handler

Tag Renderer

Executed on deployment Executed on request
Results in language specific server side code Results in final markup
Implements com.tridion.tcdl.TagHandler Implements com.tridion.tcdl.TagRenderer
It is published JSP or ASP.NET target It is usually published to a REL target
Used in a component template, set the Output format property to JSP Scripting or to ASCX Web Control Dynamic Component Template, Output format property: REL
Configured on cd_deployer_conf.xml.

Configured on cd_dynamic_conf.xml

 

When to use a Handler

  • The main use case is here, is to have language agnostic code on our templates. This way you can have your TCDL tags on your templates, and this code will later be transformed into .NET Controls, JSP Tags, or non-standard technology Web site content

Does this approach ring a bell? Yup, exactly, that’s how dynamic component links and dynamic component presentations are managed by default.

When to use a Renderer

  • Renderers are very useful to integrate our dynamic content with external data, which is constantly changing and therefore cannot be pre-rendered on publish. For example retrieving the price of a product, from an external web service. Our DCP’s are published to the broker containing a TCDL tag with the product ID, and on DCP retrieval the TCDL tag will execute and output the product price
  • Another common scenario to use a Renderer is to implement logic to be executed when retrieving a Page or DCP from the OData Web Service

These are some of the typical reasons to use TCDL tags. Have you found other scenarios were TCDL tags were useful? Leave a comment!

Reused content propagation, “Finish Editing” button and a simple custom resolver tweak

Leveraging your CMS potential is all about content reutilization. Reutilization in multiple pages, multiple channels and even multiple languages. If you were to re-create the same content (and maintain it) over all your delivery channels, you would be missing the core potential of SDL Tridion

 

Use Case: The summary-detail couple

We are going to dive into one of the most typical reuse scenarios in SDL Tridion to reuse content: The Summary / Detail Combination.

This requirement aims to reuse the same piece of content, in at least two pages of our website, with different design. We have a Summary Page, listing small descriptions of products, news, articles… and link to the full version of this element, with all the full featured detailed information, large images, specifications… Some information will be displayed in one presentation, some in other, some in both, but we are referring to the same piece of content.

 

Summary–Detail from the visitor point of view:

From a visitor point of view, we can see a summary page with a number of listed products. Whenever one of these items is clicked, the user is redirected to the detail page, expanding on the item information.

 

1.- Summary-Detail-Tuple

 

Summary–Detail from the content editor side

Now, how does all this look into Tridion. Thanks to the content-centric model of Tridion, we only have one component, containing the information for both pages.

In this article we are only going to explore a static approach:

  • The component will be embedded using a static component template on the Detail Page
  • The component will be embedded using a static component template on the Summary Page, together with all the other item components listed

 

Editorial Process

Imagine the editor wants to modify a field shared by both the summary and details, the process will be something like:

 

Experience Manager

Workflow 1: Modify and Publish to staging

Actions:

  • Access the detail page in experience manager mode and modify the field
  • Click “Finish Editing” button.

Result:

  • Both the Page and the component will be published in separated transactions to the publishing queue, resulting in both pages getting the updated content. Success!

Workflow 2: Publish our changes to live

Actions:

  • The editor can see the changes in staging, and is proud enough of them to publish to live, therefore, still in Experience Manager, publishes the modified detail page to Live

Result:

  • Only the detail page is published. Resulting in an unhappy editor, out of sync content and requiring either publish the component manually (which can also be easily done in XPM), or publish all the other pages

2.- Before-Resolver ResolvedItems

 

What happens here is that XPM is trying to help the editor after clicking “Finish Action”, by publishing all the Components in the page, but when the editor is publishing the page explicitly XPM does not kick in to help. This is expected behavior, but kind of inconsistent for the editors and creates confusion and extra work

 


TIP:

When publishing, Experience Manager Breadcrumbs will tell you what element of the page you are about to publish. Editors understanding Tridion publishing behavior can use this to their advantage

 

3.- Breadcrumbs Page

 

 

4.- Breacrumbs Component

 

 


 

 

CME

Workflow 3: Modify component and Publish component

Actions:

  • The editor access component in the CME and modify the component field
  • Explicitly publish the component to any target.

Result:

  • All pages where the component is used statically get republished. Our content is updated everywhere. Success!

Workflow 4: Modify component and Publish detail page

Actions:

  • The editor access component in the CME and modify the component field
  • The editor publishes the Detail Page

Result:

  • Only the Detail page gets updated. We are actually in the same case than Workflow 2, the only difference is the interface used is CMS instead of XPM

Editing in the CME assumes a greater understanding of SDL Tridion behavior than XPM, however the inconsistencies with the “Finish Editing” button can be frustrating for the editors

 

Making editor’s life easier with custom resolving

One of our main goals when designing an implementation should be to make editors life easier. Think that time spent on the implementation, will pay back many times, when the editors are working on the system, day after day, repeating the same operations, for many years. Making your editors life easier will make yours easier too.

 

Replicating ¨Finish Editing¨ behavior

From a functional point of view, we will try to mimic the behavior of the “Finish Editing” button when explicitly publishing a page.

From a technical point of view our best extension hook is writing a custom resolver that will add our component into the transaction.

 

2.- Before-Resolver ResolvedItems

 

 

Show me some code:

 

 

This simple code will add every component embedded on the page to the publish transaction. Detailed information on how to develop/register a resolver extension can be found on SDL Live Content (Login Required)

As always when publish components take into account the Publish propagation risks, if your content model contains a high number of linked components.

 

After this, our published items list will also reflect the changes:

 

5.- After-Resolver ResolvedItems

Debrief

In this article we have analyzed how the editors experience content propagation of static shared content in experience manager, and how to tweak our implementation to make the experience more consistent for the editors. It is important to calibrate how advanced are our editors, to either tweak the system to be easier to use or allow more fine grain operations

What about DCPS? In a second article we will go through the same process, but using dynamic component presentations, which entails some differences