Tridion Sites 9 - Content API with GraphQL

SDL announced with upcoming Tridion Sites 9 that they also release a new version of their Unified Delivery Platform (UDP). The most promising feature of it will be a completely new public-facing Content API. This API is the new endpoint for content delivery for Sites and Docs and help customers enabling more dynamic and cleaner solutions for their channels.

Unified Delivery Platform update

SDL marketing is trying to rename their technology all the time. We have seen it with Tridion to Web to Tridion. And now what once was Content Delivery (CD) was renamed to UDP and now the introduced a new term: Dynamic Experience Delivery (DED). I will keep UDP for now in this article. :-)

Before we dive into Content API, a short highlight of the other key features of UDP 11:

  • Multiple namespace support. Now one for Sites and one for Docs. This can be extended to more areas in the future.
  • Content mashups possible. Mix content from Sites and from Docs in a single web application.
  • Full-text search supported with Elastic Search technology. Index and Query support is expected with Sites 9.1
  • Docker support. Making cloud orchestration for the microservices easier (scaling and failover scenarios).
  • Content API

Content API

The new content API uses GraphQL which has roots in Facebook technology stack. GraphQL has several benefits compared to other query languages:

  • Single endpoint without versioning required
  • Efficient querying: specify the information you need and get data in one single-trip request
  • Stability: changing data doesn't require changing clients
  • Documentation: simple understandable Graph schema with self-documented feature
  • Support: large community resulting in a large number of GraphQL client tools

Since GraphQL can be consumed by a lot of other platforms it is likely that it will replace the OData web services at some point in time.

Example GraphQL query for the Content API

When installing the Content API the default endpoint will be something like https://YOURSERVER/udp/content. Note that there is also another endpoint for developers without caching. One requirement is that the content is published as DXA (DD4T) rendered JSON. So if you have this in your broker database, no republish actions are required at all and you're good to go.

In the GraphQL example below, we request 3 properties of a published page by URL.

{
  myPageByUrl: page(namespaceId: 1, publicationId: 5, url: "/index.html") {
	url, 
	itemId,
	title
  }
}

myPageByUrl is the container where the query result can be found in the response. The namespaceId corresponds with Tridion Sites and the publicationId and url is the rest of the actual search query. In the inner query we declare 3 properties what we want to receive in the response: url, itemId and title.

A possible response from the Content API could be:

{
	"data": {
		"myPageByUrl": {
			"url": "/index.html",
			"itemId": 123,
			"title" : "000 Home"
		}
	}
}

More complex GraphQL queries

The given example is fairly straightforward and simple. More complex and useful queries can be made as well. To give you an impression of the almost endless possibilities:

  • Get the binary component by ID and by URL 
  • Get contained ComponentPresentation's by page ID and by URL
  • Get items as paginated results
  • Get first X publications
  • Get category and its children keywords
  • Query for component presentations based on taxonomy
  • Get keywords and structure groups related to the page, find parents and expand children
  • Mashup queries (retrieving content from Sites and Docs namespaces in single request)
  • Get items based on query with custom metadata

Probably during Tridion Developer Summit there will be presentations about the Content API with rich GraphQL demos. TDS is hosted in Amsterdam on 6th and 7th september. It is still possible to register and maybe see you there!

Tridion Sites 9 - How to upgrade?

As you may know, SDL has announced that Tridion Sites 9 will be released by the end of this year. The prepare us for the upcoming release SDL has scheduled a series of webinars. The first one is about Technical Readiness: what is required and what are the options to upgrade?

There are a lot of improvements: better cloud support (DB), experience optimization (XO) and rolling upgrades scenarios with zero downtime.

Requirements & software versions

As always, there are two sides:

  • Content Manager side (windows only)
  • Content Delivery side (now a.k.a. Unified Delivery Platform / UDP)

Start with CM requirements: Windows 8.1 (and higher), .NET Framework 4.7.2, Java 8.

The CD requirements: same as CM, but also including support for Linux RHEL 6.9/7.4.

Both sides support the following DB storages: SQL Server Azure, Amazon RDS, MS SQL Server 2016SP1 / 2017

XO: Experience Optimization

On the UDP side, there is a new module available: eXperience Optimization. XO enables prescriptive personalization with relevant content. There will be a webinar around this topic. For now, all you should know is that you need to install Elastic Search (5.5 and higher) on UDP side to make it available.

Upgrading to Sites 9

SDL really wants to make it easier to upgrade to reduce risk and costs with zero downtime. Upgrade paths available from Tridion 2013SP1 HR2 and up.

Staged upgrade scenario is changed (including rolling upgrades). This was CD first and CM later. Now it is switched to CM first, since CD is often out-scaled and can be run side-by-side. Upgrading mainly consists of these steps: upgrade CM datastore, upgrade CM instance. Install Elastic Search for XO. Upgrade UDP datastore and UDP microservices. 

Rolling upgrades is now supported and has major benefits:

  • no downtime
  • no content freeze
  • upgrade CM database from web 8 to sites 9. Database keeps working with web 8 due to backwards compatibility.
  • upgrade a single CM instance to Sites 9 to test for issues
  • upgrade CD database and keep microservices running on web 8. And upgrade service by service to sites 9.
  • easier and less costly to upgrade

Important facts to keep in mind:

  • Upgraded CM database is backward compatible with Web 8.5
  • UDP microservices can do rolling upgrades from Web 8.5 to Sites 9
  • SDL is working on Docker container support

Other improvements

There were several other improvements mentioned:

  • High availability support for CM: removed local file storage dependencies (like MM types, Custom Pages and AM)
  • Audience Manager synchronization
  • Out-scaling the deployer service in active/active mode. (AFAIK was already part of SDL Web 8.5, but has now more performance)
  • SAML 2.0 Support in Web UIs for single-sign-on

Publication Administration right. Did you know?

Since SDL Web 8.5 there is a feature available that hasn't got a lot of attention. It is minor but can improve the lives of many content managers (and system admins): Publication Administration right.

When this right configured for a user it allows them to check-in any versioned item in that Publication that another user had checked out. This is particularly useful when people go on vacation and they forgot to submit their work. So no more e-mails to system admins to resolve versioning issues!

Before setting such rights, please take note of the other operations possible. From the SDL docs

  • creating, reading, updating or deleting any item in the Publication
  • publishing any item in the Publication
  • checking in any versioned item in the Publication that another user had checked out
  • undoing the check-out by another user of any versioned item in the Publication
  • reading, unlocalizing or deleting non-checked-in items

Tridion Hackathon story with Alchemy

Last week I participated in a Hackathon for our client. It all started with a kickoff meeting with business users. They shared their daily experience of the Tridion system and implementation. Likes and dislikes were discussed and also where they lose time working with cms (amount of clicks). It was a fruitful session, I must say. After voting about business value and guestimates on developer effort we got an ordered list of issues to tackle.

Hackathon development phase

After the business users left the developers brainstormed about possible solutions. To name a few:

  • Additional user training
  • Installing existing extensions from the Alchemy Webstore.
  • Developing new Alchemy extensions
  • Automation via the event system
  • Extend DD4T rendering
  • ...

During the next couple of days, we started building. At the end of our available time, we developed 3 very useful Alchemy extensions (and some other improvements). The extensions itself are too much targetted for the customer implementation, but what I can share are some very useful tips and tricks.

Top 5 Alchemy developer tips

#1 - Starting and learning Alchemy

The best way to start with Alchemy development is to read the docs, install the VS project templates.

To learn about development, clone and inspect the BigBox of Samples plugin. Also, browse the Alchemy gallery to see what is there for inspiration. Also to not reinvent the wheel. Most plugins are open source and have a source code link. In case you wonder, how did they do XYZ... If no source available you could opt for downloading the A4T, rename the file to .ZIP and browse it. Javascript is easy, for the server-side code you need a decompiler to peek.

#2 - Custom configuration settings in client-side javascript

It is possible to create custom configuration settings for your extension. By default, you can use them in your serverside controller. Optionally, you can use them in your javascript command file. Then you must not forget to add the client=true attribute in a4t.config:

<settings>
    <InitialSize client="true">400px</InitialSize>
</settings>

#3 - Disable Alchemy Webstore popup 

By default everytime you do a build in VS, you will be prompted with an upload-to-alchemy popup window. While developing locally you do not need it and luckily there is a way to turn it off. Right-click the project and unload the project. Then right-click again to edit the project file and search for:

<AlchemyUploadDialog>DEBUG|RELEASE</AlchemyUploadDialog>

If you remove DEBUG| it will only prompt when building in release mode.

#4 - Deploy on VS build

Peter Kjaer developed various very useful Powershell modules for Tridion. There is a stable Alchemy module available to install, update and uninstall Alchemy extensions. If you install it, you can configure you VS project post-build event to install/update your plugin automatically. Then you only need to refresh the GUI for loading you extension.

#5 - Choose between client- and server-side

Working with the minimal documented Tridion Anguilla javascript framework can be a very time-consuming experience. Sometimes certain logic can be implemented with Tridion Core Service, so use the Controller to implement logic there. It is easier to get things done server side.

Hope this helps. If you have anything to add, please let me know!

Handling rich text content fields in SDL Tridion CMS

In this article, I will explain a little bit about Rich Text Fields in SDL Tridion CMS and how to customize and restrict the usage of styling to some extent with a basic example.

Introduction to RTF fields in Tridion

Tridion supports Rich Text Fields for allowing content managers to create better-looking content. All kinds of HTML elements are supported like the typical Italic, Bold and Underline. By default when enabling RTF features for a text field in your schema design all common tags are allowed:

  • Editing (or copy/paste) as HTML
  • Possible to select some text and apply a style via the buttons in the ribbon bar:

Customization options in Tridion

All this freedom for a content manager may drive front-end developers insane since they need to support all of it with their CSS. Luckily, there are 3 customization options within Schema design to limit the RTF features:

  1. Disable buttons in the ribbon bar
  2. Configure custom styles (matching the class names in CSS)
  3. Filter unwanted HTML (with help of XSLT)

These can be configured per schema content field:

Example case - Transforming HTML

XSLT is a complex but powerful language for transforming XML from one format to another. HTML is just a form of XML and thus XSLT can be used to free RTF content from unwanted tags.

Here, I want to demonstrate how to implement the following requirements:

  1. Make sure all bold texts are using <strong> tag element (and not <b> tag, which is default). This mechanism can later also be applied for converting italic <i> tag to <em> tag, etc.
  2. Only paragraphs, breaks and bold should be allowed in the HTML. This results in the following HTML tags: <p>, <br /> and <strong>

Converting from one HTML tag to another

The 1st requirement can be implemented by inserting the following fragment into the default XSLT:

  <xsl:template match="b">
        <xsl:element name="strong">
          <xsl:apply-templates select="node()"></xsl:apply-templates>
        </xsl:element>
  </xsl:template>

What it does is: when a tag is <b> found, replace it with a <strong> tag and continue XSLT rendering for the inner value of the node.

Filtering unwanted tags

For filtering you basically have two approaches:

  • Black-listing: unwanted tag elements. Use when you want to allow all tags, and exclude a few unwanted tags.
  • White-listing: specify the tag elements you want to keep. Use when the set of allowed tags is known.

In general (as in security), white-listing is the preferred method. Explicitly allowing specific tags gives you the most control over the output and rule out any 'forgotten' tags to appear in the HTML. 

The 2nd requirement can be implemented by using the following fragment in XSLT:

<xsl:template match="/ | node() | @*">
    <xsl:copy>
      <xsl:apply-templates select="/ | p | b | br"></xsl:apply-templates>
    </xsl:copy>
</xsl:template>

This fragment is basically processing all X(HT)ML elements and it copies only the allowed tags to the output to be processed further.

Complete XSLT solution

Below the complete file, including a conversion for <i> to <em>.

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  <xsl:output omit-xml-declaration="yes" method="xml" cdata-section-elements="script"></xsl:output>
  <xsl:template match="*[      (self::br or self::p or self::div)     and      normalize-space(translate(., ' ', '')) = ''     and      not(@*)     and      not(processing-instruction())     and      not(comment())     and      not(*[not(self::br) or @* or * or node()])     and      not(following::node()[not(         (self::text() or self::br or self::p or self::div)        and         normalize-space(translate(., ' ', '')) = ''        and         not(@*)        and         not(processing-instruction())        and         not(comment())        and         not(*[not(self::br) or @* or * or node()])       )])     ]">
    <!-- ignore all paragraphs and line-breaks at the end that have nothing but (non-breaking) spaces and line breaks -->
  </xsl:template>
  <xsl:template match="br[parent::div and not(preceding-sibling::node()) and not(following-sibling::node())]">
    <!-- Chrome generates <div><br /></div>. Renders differently in different browsers. Replace it with a non-breaking space -->
    <xsl:text> </xsl:text>
  </xsl:template>
  <!-- added bold to strong conversion -->
  <xsl:template match="b">
        <xsl:element name="strong">
          <xsl:apply-templates select="node()"></xsl:apply-templates>
        </xsl:element>
  </xsl:template>
  <!-- added italic to em converter -->
  <xsl:template match="i">
    <xsl:element name="em">
          <xsl:apply-templates select="node()"></xsl:apply-templates>
        </xsl:element>
  </xsl:template>
  <xsl:template match="/ | node() | @*">
    <xsl:copy>
      <xsl:apply-templates select="/ | p | b | i | br"></xsl:apply-templates>
    </xsl:copy>
  </xsl:template>
</xsl:stylesheet>