Tridion developer articles and tutorials

Write Deployer extension as add-on for Tridion sites

Neetesh Narvaria — Wed, 15 Jan 2025 15:38:52 GMT

To Write deployer extension for Tridion Sites with following steps

Create a custom step class which implements "ExecutableStep" (com.sdl.delivery.deployer.api.processing.pipeline.ExecutableStep) interface
- interface is available on udp-deployer-api-x.x.x-xxxx.jar which can be found on maven repo or in the deployer service installation directory.

Override methods in CustomStep class

configure

 @Override

 public void configure(Configuration configuration) throws ConfigurationException {

 //this is section where we initialize step

 }

process

 @Override

 public ExecutableStepResult process(ProcessingContext processingContext, StepDataProvider stepDataProvider) throws ProcessingException {

 LOG.debug("Starting ExampleExtension");

 var location = getPackageUnzipLocation(processingContext, stepDataProvider);

 LOG.debug("ExampleExtension getPackageUnzipLocation location {}", location);

 TransportPackage transportPackage = new TransportPackage(location, stepDataProvider.getBinaryStorage());

 LOG.debug("ExampleExtension transportPackage {}", transportPackage);

 final String action = transportPackage.getAction();

 LOG.debug("PageStateNotifier action {}", action);

 final String transactionId = transportPackage.getTransactionId().toString();

 LOG.debug("Process Action {} for Transaction {}", action, transactionId);

 switch (action) {

 case DEPLOY_ACTION:

 LOG.info("Publish action triggerred");

 break;

 case UNDEPLOY_ACTION:

 LOG.info("UnPublish action triggerred");

 break;

 default:

 LOG.error("Invalid action {}", action);

 throw new ProcessingException("Invalid transport package action " + action);

 }

 return null;

 }

Write a spring configuration
- configuration class should be on package "com.sdl.delivery.spring.configuration"
- Let's name it ExampleConfiguration
```
 package com.sdl.delivery.spring.configuration;
```
```
 import org.springframework.context.annotation.ComponentScan;

 import org.springframework.context.annotation.Configuration;
```
```
 @Configuration

 @ComponentScan(basePackages = {"org.rws.example"})

 public class ExampleConfiguration {

 }
```
- above class allows your deployer extension to be developed on specific package for example in above ExampleConfiguration it scans package "org.rws.example" then you can implement your CustomStep on step 1 inside package "org.rws.example".
Please also include following minimum java libraries for development of Tridion Sites deployer extension
- udp-common-config-api-x.x.x-xxxx.jar
- udp-common-config-x.x.x-xxxx.jar
- udp-common-util-x.x.x-xxxx.jar
- udp-core-x.x.x-xxxx.jar
- udp-data-legacy-transport-x.x.x-xxxx.jar
- udp-deployer-api-x.x.x-xxxx.jar
- udp-deployer-web-extension-x.x.x-xxxx.jar
x.x.x-xxxx denotes version of api available on installation directory of deployer service.
After creating CustomStep, based on your project setup (i.e. maven or gradle) configure build steps which could generate a add-on package file in zip.
zip file contains generated jar file and dependent jars those are not available on deployer service libraries, and manifest file requires for Addon service to specify type of Add-on.
you can refer maven project which is having build step to generate Addon-package https://github.com/neeteshnarvaria/deployer-extension/blob/master/pom.xml
example maven project generates example-deployer-extension.zip
after all the steps we need to configure/update deployer-conf.xml
- open in notepad and add custom pipeline after following pipelines, specifically after highlighted one in screenshot below
- custom pipeline
```
 <Pipeline Id="Tridion-Example-Step" Action="Deploy,Undeploy" Verb="Process">

 <Steps>

 <Step Id="ExampleExtension" />

 </Steps>

 </Pipeline>
```
after configuring/update deployer-conf.xml save and close the file.
add the generated package on add-on using upload
select add-on
after upload on add-on it will show as "Pending State"
We need to restart deployer service to activate the deployer extension add-on.
Deployer status should show "Success".
it is ready to use and we can check functionality by adding some logs.

Refer following git repo which contains sample deployer extension having custom step: https://github.com/neeteshnarvaria/deployer-extension

Tridion Community Releases Digital Experience Accelerator (DXA) Java 2.3

Philip Medcraft — Thu, 21 Mar 2024 16:04:46 GMT

Following the announcement by Velmurugan Arjunan regarding the DXA .NET 2.3 release, we are pleased to announce the launch of our Java DXA, version 2.3. This version resolves several security vulnerabilities with 3^rd party dependencies some of which could only be resolved by moving to Spring Framework 6. This was the main motivation for this new version.

Platform Support

Please refer to the compatibility matrices from:

https://github.com/RWS/dxa-web-application-java?tab=readme-ov-file#compatibility-matrices

Compatibility and Considerations

The Java DXA 2.3 coexists with its predecessor, Java DXA 2.2, providing users with flexibility and choice. However, there are important compatibility considerations to note:

Version 2.3 is compatible with Java 17 running with Spring Framework 6.
Spring Framework 6 utilizes the new Jakarta Servlet API (replacement for the old javax.servlet API). This means that the Java DXA 2.3 is no longer compatible with Tomcat 9, so would need moving to Tomcat 10.
The Java JRE and Tomcat versions would only need updating for the content delivery web application. There is no need to update the DXD/microservices.

Release Information

DXA 2.3 ships with DXD 12
Support for the "Audience Manager" and "UGC" modules has been removed
All the Java DXA artifacts are available from Maven Central
- DXA Framework: https://central.sonatype.com/search?q=com.sdl.dxa
- DXA Modules: https://central.sonatype.com/search?q=com.sdl.dxa.modules

Please join the community and consider contributing to further evolve the DXA. Feel free to reach out to RWS Professional Services for assistance with your upgrade projects.

Tridion Community Releases Digital Experience Accelerator (DXA) .NET 2.3

Velmurugan Arjunan — Thu, 07 Mar 2024 09:24:49 GMT

We are excited to announce the launch of the latest version of our Digital Experience Accelerator (DXA), version 2.3. This release brings a host of enhancements and new features to streamline your development process and enhance your digital experien...(read more)

How to build custom connector using Tridion Integration framework

Anand Sarangapani — Wed, 21 Feb 2024 13:28:31 GMT

Tridion Integration Framework helps you to write and deploy Connectors for integrating Tridion Sites with third-party applications. The Tridion Integration Framework is provided for the various Application Clients that it supports. The method of installation the framework may differ from client to client.

RWS Documentation Reference : https://docs.rws.com/1099777/729801/tridion-sites-10-connectors/building-a-new-custom-connector

API reference documentation reference : https://docs.rws.com/1099777/918320/tridion-sites-10-connectors/api-reference-documentation-downloads

Step 1) Installed on your machine .NET 6. Download the .NET SDK

Step 2) Install the connector Template based on the Tridion Sites Version listed below.

Step 3) Open a command line and run the following command to install the template:

dotnet new install Tridion.Connector.Template

The command installs the template to your .NET Core environment. You can verify that it's properly installed by running only the dotnet new command

Step 4) Create a folder where you want to generate a new connector project. – Example C:\Connector

Step 5) From a command line, go to the folder you created in the previous step and run the following command:

dotnet new tridionconnector --n PROJECT_NAME

Where PROJECT_NAME is the name you want to use for the new project. As a best practice, we suggest you use the same name as the folder containing the project.

The command builds the connector project with everything you need to build your custom connector. The project includes the following resources and samples:

Entity types
Capability implementations
Test data
Icons
Add-on manifest
Connector configuration

Step 6) Edit the manifest.json file, as needed.

Step 7) From the command line, run the following command to generate the Add-ons package:

dotnet build

Note: You can also build the package from within your IDE.

Step 8) Logon to Tridion Content Management System and Create a folder called Stubs and Copy the tcm URI example : tcm-2-167-2

Step 9) Navigate to the folder where the json file is created Example : DemoConnectorConnector.json edit the file change the value from Default Value "stubFolders": ["tcm:4-67-2"] to tcm-2-167-2 and Save the file

Step 10 ) Upload the package (as a ZIP file) to the Add-ons feature.

Access the Add-on URL and click on the Upload Addon Package

Upload the json configuration file

access the Content Manager CME and refresh the Add-on to show the connector is activated successfully

Step 11 ) Logon to Content Manager and you will see the Demo Connector with few Folders and Files

Tridion Sites Content Manager REST API

Anand Sarangapani — Tue, 05 Dec 2023 22:18:52 GMT

Content Manager REST API

Tridion Sites Rest API Using Swagger

http://hostname/ui/api-docs/ ( CMS hostname ) redirects to Swagger URL

Get a list of all Publications ( No Parameters )

Click on Try it Out

Click on Execute

Response (Response content Type – application/json)

Curl GET Request
Server Response – 200
Response Body
Response Header

Click on Download the Out put to view the JSON Response

How to generate token using postman to access the Tridion Sites Content Manager API.

Step 1) Open Postman create new URL Add the following Rest API URL to get Publications

GET http://hostname/api/v2.0/publications

Step 2) go to Authorization Tab and Select OAuth 2.0 Type from the dropdown

Step 3) after you select OAuth 2.0, Enter the following details

Token Name: Core Service Rest API
Grand Type: Select (Client Credentials)
Access Token URL: http://hostname/access-management/connect/token
Client Authentication: Send client credentials in body

Step 4) Get Client ID and Client Secret

Access the Access Management URL and click on service account

Double click on Tridion Sites Content Manager API Client (admin)

Copy the Client ID from Access Management

Click on Add Client Secret to generate the value , please delete the old value if you don’t remember and generate a new client secret

Enter the Client ID and Client Secret copied from access management to Postman

Step 5) Click on Get New Access Token Button

Click on Proceed

Click on Use Token

Click On Send to list all publications based on the URL http://hostname/api/v2.0/publications

Tridion Sites 10 - UI Extensibility Rich Text Editor

Anand Sarangapani — Fri, 03 Nov 2023 12:36:56 GMT

Using the example that we published to GitHub, we'll go through the steps of customizing the rich text area

Extend Rich Text Editor

Operation	Example
Customization of the RTF field using custom plugin	rtf-plugin-color-text-addon
Customization of the RTF field using built-in plugin	rtf-plugin-wordcount-addon
Remove wrapping paragraph for single-line text in RTF content	rtf-remove-single-line-wrapping-paragraph-addon

TinyMCE is a rich-text editor that allows users to create formatted content within a user-friendly interface. please refer to the documentation for more details https://www.tiny.cloud/docs/tinymce/6/

TinyMCE is an incredibly powerful, flexible and customizable rich text editor. This section will help configure and extend the editor by using TinyMCE plugins.

Extension Name :Customization of the RTF field using custom plugin - Color Text

Extension Source Path : https://github.com/RWS/tridion-sites-extensions-examples/tree/main/sites-10-ux-update/content-editor/rtf-plugin-color-text-addon/rtf-plugin-color-text

Commands

"npm i" this installs the project
"npm run build" this builds the solution
"npm run pack" this creates the package

If you wan to run the extensions from you local , please run "npm run dev"

Editor can select the color option to highlight the text , example : Blue or Pink

Extension Name :Customization of the RTF field using custom plugin - Word Count

Extension Source Path : https://github.com/RWS/tridion-sites-extensions-examples/tree/main/sites-10-ux-update/content-editor/rtf-plugin-wordcount-addon/rtf-plugin-wordcount

Commands

"npm i" this installs the project
"npm run build" this builds the solution
"npm run pack" this creates the package

If you wan to run the extensions from you local , please run "npm run dev"

Tridion Sites 10 - UI Extensibility - Getting External Data in the Content Editor

Anand Sarangapani — Tue, 24 Oct 2023 11:41:22 GMT

In this article we'll go through and example of pulling in External Content into the content editor. We'll base this walkthrough on the examples that were published to GitHub.

External Data Select

Extension Name : external data select

Extension Source Path : https://github.com/RWS/tridion-sites-extensions-examples/tree/main/sites-10-ux-update/content-editor/external-data-select-addon/external-data-select-field

Commands

"npm i" this installs the project
"npm run build" this builds the solution
"npm run pack" this creates the package

Upload the Add-on using add-on Manager

Example: Create a Schema with a text field and add (externalDataSelect name under CustomURL) or add a text field on one of the existing schema

Create a Component based on the Schema Created

You see the external data is loaded on the defined Text Field in this case externalData

Tridion Sites 10 - UI Extensibility - Customizing the Primary Navigation

Anand Sarangapani — Tue, 24 Oct 2023 10:36:56 GMT

Using the example that we published to GitHub, we'll go through the steps of customizing the primary navigation.

Customize Navigation

Please refer to the https://github.com/RWS/tridion-sites-extensions-examples/tree/main/sites-10-ux-update/primary-navigation

This repository contains examples of extensions for Tridion Sites. It covers different extension points and also demonstrates usage of a wide range of hooks, components and utility methods.

Operation	Example
Navigation item with restricted access	restricted-page-addon
Dynamic navigation item that depends on the async request	async-page-addon
Navigation items customization	customize-navigation-addon
Publish transactions navigation item	publish-transactions-addon
Classic UI navigation item	classic-ui-addon

Extension Name : Customize Navigation

Extension Source Path : https://github.com/RWS/tridion-sites-extensions-examples/tree/main/sites-10-ux-update/primary-navigation/customize-navigation-addon/customize-navigation

Commands

"npm i" this installs the project
"npm run build" this builds the solution
"npm run pack" this creates the package

If you wan to run the extensions from you local , please run "npm run dev"

Upload the package using Add-on

Add-on Install Success

After Installed Add-on : View the customized navigation add-on

Disable the Add-on

Access the Experience Space ( new UI)

The three ways to use the Content Delivery API (GraphQL)

Alvin Reyes — Wed, 02 Aug 2023 17:19:17 GMT

This post describes the main three ways to get content from the Dynamic Experience Delivery Content API in the context of Tridion Sites and concludes with some tips for managing hyperlinks across content. Spoiler alert: it's not by manual links. You ...(read more)

Instant Campaign v1.3

Niclas Cedermalm — Fri, 23 Oct 2020 14:28:00 GMT

The new version (v1.3) of Instant Campaign is now out with support for SDL Tridion Sites 9.1/9.5 and DXA 2.2.
It is available for download on the SDL AppStore: https://appstore.sdl.com/web-content-management/app/instant-campaign/748/

Instant Campaign makes it possible for digital agencies to create engaging campaigns with a rich experience without the need of creating custom templates in Tridion. The agency delivers the campaign as a ZIP file which is uploaded into Tridion. The Tridion editor can then edit textual content, images, links etc in the campaign. The campaign content can also be localized and sent for translation. The sweet spot for Instant Campaign is primarily for short-lived campaign pages and experience-rich product detail pages. But it can be used for any rich content to shorten the time to market without the need of involvement of IT to develop new templates.

Instant Campaign is free, open-source and is fully supported by SDL. You find the source code here: https://github.com/sdl/dxa-flexible-campaign-content

SDL Tridion Sites 9.5 Inline Field Validation Example

Alvin Reyes — Fri, 24 Jul 2020 15:59:00 GMT

If you take advantage of the inline Schema (xsd) constraints in SDL Tridion Sites 9.5's Experience Space UI, you might need an example. SDL Tridion Sites has long had the ability to constrain the values that editors can enter into&nb...(read more)

SDL Tridion Docs 14SP2 - Windows Authentication setup

Velmurugan Arjunan — Thu, 23 Jul 2020 18:57:00 GMT

SDL Tridion Docs - The default system that manages user identity for Tridion Docs is ISHSTS (Infoshare Security Token Service), In the Post-installation SDL Tridion Docs can be enabled to authenticate uses through the customer's STS system or Windows Authentication rather than Infoshare STS, In this post will explain the steps to integrate the SDL Tridion Docs with Windows Authentication, In the next article will explain about the SSO/ADFS setup for SDL Tridion Docs.

Tridion Docs Prerequisites

SDL Tridion Docs System should be connected to Windows Active Directory
IIS Windows Authentication feature should be enabled

Step1: Configure application server for Lightweight Windows Authentication

RDP to SDL Tridion Docs Installed system
Take a whole Infoshare folder backup and also take the database backup
Locate the PowerShell script SDL.ISH-ISHSTS-Configure for Windows Authentication.ps1 in the folder \InfoShare\App\Setup\STS\ISHSTS\Scripts
Open PowerShell with elevated administrator privileges. Run As Administrator. If the PowerShell session is not running with administrator privileges, the script will launch a new session, and administrator privileges will be requested to the user.
This task requires a PowerShell session with Execution Policy set to Unrestricted.
- If it is not set, you need to set it permanently by executing the following:
```
Set-ExecutionPolicy Unrestricted
```
Navigate to the script folder \InfoShare\App\Setup\STS\ISHSTS\Scripts
a. cd \InfoShare\App\Setup\STS\ISHSTS\Scripts
Execute script SDL.ISH-ISHSTS-Configure for Windows Authentication.ps1
- .\SDL.ISH-ISHSTS-Configure for Windows Authentication.ps1

cd \InfoShare\App\Setup\STS\ISHSTS\Scripts
& '.\SDL.ISH-ISHSTS-Configure for Windows Authentication.ps1'

Step 2: Configure the Content Manager to switch internal accounts to Windows AD accounts

On Content Manager, set the following:
User type to "External"
External ID to AD login username (domain\velmurugan)

Step3: Enable Windows Authentication

Open the PowerShell with administrator mode and run this below script

#Ensure windows authentication IIS feature enabled
Enable-WindowsOptionalFeature -Online -FeatureName IIS-WindowsAuthentication

$deploymentName="InfoShare"
Set-ISHSTSConfiguration -ISHDeployment $deploymentName -AuthenticationType "Windows"

Note:

If the database is SQL Server and the connection string utilizes integrated authentication then we need to grant the computer account permissions to the database.

Configuring the Content Manager SQL Server database for Windows Authentication

References
SDL Documentation
PS Documentation

SDL Tridion Docs 14SP2 - Windows Authentication setup
I hope it helps if you have any questions regarding post your question in Tridion StackExchange.

TDS event presentation DXA 2.2 NET + Dynamic Documentation Module + SDL Tridion Docs 14 + DXD 11.1

Velmurugan Arjunan — Mon, 27 Apr 2020 12:58:00 GMT

Tridion Developer Summit has been held at Meervaart Theater Nov 4th and 5th, I also had the opportunity to present and speak in the event, about DXA 2.2 NET + Dynamic Documentation Module + SDL Tridion Docs 14 + DXD 11.1 and followed by Demo.

The presentation can be downlod it from here.

DXA 22 NET + Dynamic Documentation Module + SDL Tridion Docs 14 + UDP 111 from TDS on Vimeo.

Introduction to Dynamic Documentation Module

DXA Dynamic Documentation module enables you to retrieve structured content (in the DITA standard) stored in an SDL Tridion Docs database and present it through your DXA web application.

The Dynamic Documentation module includes a Dynamic Documentation web application, or more briefly the Dynamic Documentation, which provides users with a responsive interface for viewing, navigating, and interacting with content published from SDL Tridion Docs.

Benefits

Single-page web application designed as a documentation portal
Modern, graphical user interface design
Responsive design for mobile support
Highly extensible and customizable
Includes search and commenting capabilities

DXA Dynamic Documentation prerequisites

Tridion Docs 14
DXD 11.0 Supported
DXD 11.1 Prefered
- Discovery Service
- Deployer Service
- Content Service
- IQ Index Service
- IQ Query Service or IQ Combined service
DXA .NET websites
- Microsoft .NET Framework 4.6.2
- IIS or IIS Express with ASP .NET module
GUI Building
- NodeJs v6.x or higher (64bit)
- Webpack
- Gulp
Front End
- JavaScript (ES6)
- TypeScript
- React
- Redux
- HTML
- LESS
- CSS

DXA DD Module Installation / configuration

Download the following OOTB sources and modules from github:
https://github.com/sdl/dxa-web-application-dotnet/tree/release/2.2
https://github.com/sdl/dxa-modules/tree/release/2.2
https://github.com/sdl/dxa-modules/releases/download/DXA_2.2.2_Hotfix/SDL.DXA.DynamicDocumentation.Module.2.2.2.zip
Extract both sources zip and Go to dxa-modules-release-2.2\webapp-net this folder and copy DynamicDocumentation and Search folder modules and also DxaModulesCommon.Props file
Go to dxa-web-application-dotnet-release-2.2 folder and paste those folders and DxaModulesCommon.Props file here
Open the DxaFramework.sln and click ok to ignore the unsupported Sdl.Web.Documentation project errror message
Right click DxaFramework solution to add the following existing projects
- DynamicDocumentation\Sdl.Web.Modules.DynamicDocumentation.csproj
- Search\Sdl.Web.Modules.Search.csproj
- Search\SI4T.Query.CloudSearch\SI4T.Query.CloudSearch.csproj
Go to Sdl.Web.Site project references and then right click and add reference and then click left side Projects and select the following projects
- Sdl.Web.Modules.DynamicDocumentation
- Sdl.Web.Modules.Search
- SI4T.Query.CloudSearch
Right click Sdl.Web.Modules.DynamicDocumentation project and build
Once succesfull build - expand the Sdl.Web.Modules.DynamicDocumentation project and copy the Areas folder and go to Sdl.Web.Site project paste it in the root folder.
Right click Sdl.Web.Modules.Search project and build
Once succesfull build - expand the Sdl.Web.Modules.Search project and copy the Areas folder and go to Sdl.Web.Site project paste it in the root folder.

Go to SDL.Web.Site and open web.config update the following configs sections

In the modelBuilderPipeline section, add the Dynamic Documentation model builder to the pipeline, placing it first in the list and before the Default model builder.
<add type="Sdl.Web.Modules.DynamicDocumentation.Mapping.ModelBuilder, Sdl.Web.Modules.DynamicDocumentation" />

In the appSettings section Update the Web.config to change the default module to DynamicDocumentation 
<add key="default-module" value="DynamicDocumentation" /> 
Also update the following configs to as per your cusotomer environment.

<add key="discovery-service-uri" value="http://staging.dev.dxa.sdldev.net:8082/discovery.svc"/> 
<add key="oauth-client-secret" value="xxxx" />

Update to Add the following Unity Declaration settings in Unity.config

<assembly name="Sdl.Web.Modules.DynamicDocumentation" />
<namespace name="Sdl.Web.Modules.DynamicDocumentation.Localization" />
<namespace name="Sdl.Web.Modules.DynamicDocumentation.Providers" />
<namespace name="Sdl.Web.Modules.DynamicDocumentation.Navigation" />

Update the existing INavigationProvider type to Set Unity Type Mapping to DynamicNavigationProvider

<type type="INavigationProvider" mapTo="DynamicNavigationProvider">
   <lifetime type="singleton" />
</type>

Update Unity.config for IContextClaimsProvider to AdfContextClaimsProvider instead of ContextServiceClaimsProvider

<type type="IContextClaimsProvider" mapTo="AdfContextClaimsProvider">
   <lifetime type="singleton" />
</type>

Go to Site project root folder and create this folder path \system\assets\gui New-Item -Path ".\system\assets\gui" -ItemType Directory | Out-Null Copy the gui folder from DDMoudle\web\ to your project and go to gui root folder and run this below commands npm install -registry https://nexus.sdl.com/content/groups/npm/ npm run-script buildCopy the dist\assets folder to \system\assets\gui in websiteCopy cd_ambient_conf.xml config to keep in the website bin\config folder (File can be copied from SDL Tridion Sites Installation Media \Content Delivery\roles\api\rest\dotnet\config\cd_ambient_conf.xml)

Installing the Search module in the web application

Open Unity.config to update to add the following config sections

Add UnityDeclaration:
<assembly name="Sdl.Web.Modules.Search" /> 
<namespace name="Sdl.Web.Modules.Search.Providers" />

Set UnityTypeMapping:
<type type="ISearchProvider" mapTo="IQSearchProvider" />

Update web.config to add elastic index name
<add key="iq-search-index" value="udp-index" />

Dynamic Documentation GUI Building In order to build make sure you have Node.js installed (v6 or higher). Installing the necessary packages

npm install gulp-cli -g
npm install

Gulp tasks

# Build (debug)
gulp build

# Build everything and setup a server (debug)
gulp serve

# Build everything and setup a server (release)
gulp serve:dist

# Build (release)
gulp

Note: For a DXA for Dynamic Documentation implementation, you must install at least the Dynamic Documentation module. All other modules are optional.

I hope it helps if you have any questions regarding post your question in Tridion StackExchange.

Developing connectors using the new Tridion Integration Framework

Niclas Cedermalm — Mon, 30 Mar 2020 07:44:00 GMT

This blog post will describe how you can get started to develop connectors using the Tridion Integration Framework. It will describe step-by-step on how you generate connector projects for Java and .NET and how to install & configure connectors.

Introduction

The Tridion Integration Framework (TIF) is a new framework for writing connectors on the SDL Tridion DX platform. It was first made available in SDL Tridion Sites 9.1. Currently we are looking into how to make the framework available for SDL Tridion Docs as well.

TIF is agnostic framework that allows deployment both on Content Management and the Dynamic Experience Delivery (DXD) side. The framework is also agnostic to programming languages. Currently C# and Java is supported, but other languages might be supported in future versions.

In SDL Tridion Sites 9.1 you can write connectors that can be consumed by External Content Library (ECL) and the Public Content API (PCA). More extension points will follow. Via the ECL extension point connectors will appear as a mountpoint on the same level as Tridion native content in the Tridion Content Manager. This allows you to consume external content, multimedia & other external data in the same way you do with native content. In PCA the connector will be exposed through GraphQL allowing you to perform various CRUD, list and search requests towards the external system/service.

There are currently commercial TIF connectors available to Aprimo DAM, SAP Commerce Cloud and Salesforce CRM. More are coming later this year.

Installing Connectors

To install connectors is very easy, thanks to the new Add-on Service introduced in SDL Tridion Sites 9.1. What you need is the following:

A ZIP file containing the connector DLLs/JARs + a manifest that described the connector (name, version, description, author etc)
A JSON configuration that holds configuration of the connector (endpoint, credentials etc) and in which environment it should be installed (for example Content Manager, Staging DXD etc).

The ZIP file you then upload to the Add-on service. The manifest information are used to identify the connector and display information about it. After successful upload the connector is shown in the list of installed add-ons.

As the connector needs configuration before it can be used by any parts of the system, a JSON configuration file needs to be uploaded as well. The JSON configuration has the following format:

{
  "configuration": {
    "<Connector name>": {
      "configuration": { 
         <Generic configuration for all environments>
      }
    }
  },
  "<Environment name, e.g. sitesCm, staging>": { 
    "isEnabled": <true/false>,
    "<Connector name>": {
      "namespaces": {
        "<Connector namespace>": {
          <Environment specific configuration that overrides generic configuration>
        }
      }
    }
  },
  ...
}

Each connector can deploy one or several namespaces, where each namespace can have its own unique configuration like endpoints, different repositories etc. In ECL this maps to different mountpoints. In GraphQL you use namespaces to scope your queries.

Example configuration (taken from the SAP Commerce Cloud connector configuration):

{
  "configuration": {
    "HybrisCommerce": {
      "configuration":  {
        "pageSize": 100,
      },
  },
  "sitesCm": { 
    "isEnabled": true,
    "HybrisCommerce": {
      "namespaces": {
        "hybris": {
          "displayName": "Hybris",
          "stubFolders": ["tcm:2-71-2"],
          "privilegedUserName":"Administrator",
          "configuration": {
            "url": "https://stage-hybris.company.com:9002",
            "clientId": "tridionapi",
            "clientSecret": "secret"
          }
        }
      }
    }
  },
  "dxd-staging": { 
    "isEnabled": true,
    "HybrisCommerce": {
      "namespaces": {
        "hybris": { 
          "configuration": {
            "url": "https://stage-hybris.company.com:9002",
            "clientId": "tridionapi",
            "clientSecret": "secret"
          }
        }
      }
    }
  },
  "dxd-live": {
    "isEnabled": false
  }
}

So each environment (Content Manager, DXD staging, DXD live etc) can have its own configuration or use a common one. In addition each namespace can have its own configuration as well, which means there can be three different levels of configurations.

More information on connector manifest files & configuration format:
https://docs.sdl.com/LiveContent/content/en-US/SDL%20Tridion%20Sites-v2/GUID-64B2DE72-6024-45D5-8727-C66C2BF841A3
https://docs.sdl.com/LiveContent/content/en-US/SDL%20Tridion%20Sites-v2/GUID-699C9AC1-76DD-4D77-B535-FCC80ED9171D
https://docs.sdl.com/LiveContent/content/en-US/SDL%20Tridion%20Sites-v2/GUID-604E96A9-2F3E-4CDC-BC0D-B6AACEC7E2B7

After the configuration has been uploaded to the Add-on Service, the connector is deployed in ECL and PCA. ECL will pickup the connector and deploy it on-the-fly, while the PCA service needs to be restarted to get the connector deployed.

Connector Templates

The next-coming sections will go through the steps to generate fully functional connector projects for .NET and Java using templates available in the NuGet/Maven public repositories. After completed the below steps you can use the connector right away, as it comes with some dummy data.

Writing .NET Connectors

There is .NET Core template available for TIF connectors. You need to have .NET Core SDK 2.2 or higher installed on your machine. To install the template on your machine you do the following:

dotnet new --install Tridion.Connector.Template

You can verify that it's properly installed by running only the dotnet new command. After this you are ready to create new connector projects using this template by using the following steps:

From a command line, go to a folder where you want the connector project generated and run the following command:
```
dotnet new tridionconnector --n <connector name>
```
Where <connector name> is the name you want to use for the new project. The command builds the connector project with everything you need to build your connector. The project includes the following resources and samples:
- Entity types (exposed data models)
- Connector capability implementations (e.g. get data, list data, search, create new)
- Test data
- Icons
- Add-on manifest
- Connector configuration
Edit the manifest.json file, as needed.
If using .NET Core 3.1 or higher you need to modify the the <connector name>.csproj file and modify the 'PublishWithoutBuilding' target. The 'GeneratePublishRuntimeConfigurationFile' dependency needs to be removed from the target:
```
<Target Name="PublishWithoutBuilding" DependsOnTargets="ResolveReferences;
ComputeAndCopyFilesToPublishDirectory;GeneratePublishDependencyFile;
GeneratePublishRuntimeConfigurationFile" />
```
From the command line, run the following command to generate the Add-ons package.
```
dotnet build
```
Note: You can also build the package from Visual Studio, IntelliJ Rider etc.
Upload the package (as a ZIP file) to the Add-on Service (you find it in the generated 'AddonPackage'-folder).
Open the <connector name>.json configuration file that is created from the template, and edit the configuration, as needed. For the "sitesCm" part (used by ECL), set a value for stubFolders where the value the URI of the folder that where ECL stubs items will be stored. You must manually create this folder, note the URI, and then specify that URI in this property.
The template only generates configuration for ECL. If you want to test the connector in PCA you need to add the following to the configuration:
```
,"staging": {
   "isEnabled": true,
    "<connector name>": {
      "namespaces": {
         "<connector namespace": {
         }
      }
   }
 }
```
Upload the configuration file to the details view of deployed connector in the Add-on UI.
If the Connector's integration uses Public Content API, then restart the Content Service.
If the Connector's integration uses ECL, then refresh the Content Manager Explorer UI or just the current publication.

Writing Java Connectors

There is a Maven archetype available to generate a fully functional Java TIF connector. You need to have Maven 3.x and JDK installed (JDK 8 or higher).

To generate a new connector project you do as following:

Go to a folder where you want to generate a new Connector project.
From a command line, go to a folder where you want to generate the connector and run the following command:
```
mvn archetype:generate
```

A list of all available Maven archetypes are shown. Type ’tcf’ to filter the output. The Tridion Connector Framework archetype should show up:

Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : tcf

Choose archetype:

1: remote -> com.sdl.tridion.connectorframework:tcf-archetype (Archetype to create SDL Tridion connectors)

Enter the number (’1’ in the example above) to select the connector archetype.
Select version. Normally you should pick the latest one in the list
After that you need to specify the following as input to the generation:

- groupId – the group id to use in the generated Maven file, for example ‘com.company.myconnector’
- artifactId – the artifact id to use in the generated Maven file, for example ‘myconnector’

- version – the version to use in the generated Maven file, for example ‘1.0.0’

- package – the base package for the generated Java classes. Is by default the same as the group id

- connectorName – name of the connector. Use pascal case here, for example ‘MyConnector’
After that you need to confirm the entered values by typing ‘Y’
The command generated the connector project with everything you need to build your connector. The project includes the following resources and samples:

- Entity types (exposed data models)

- Connector capability implementations (e.g. get data, list data, search, create new)

- Test data

- Icons

- Add-on manifest

- Connector configuration
Edit the manifest.json file, as needed.
From the command line (inside the generated project), run the following command to generate the Add-ons package.
```
mvn package
```
Note: You can also build the package from IntelliJ IDEA, Eclipse etc.
Upload the package (as a ZIP file) to the Add-on Service. You find the ZIP file under the 'target'-folder.
Open the <connector name>.json configuration file that is created from the template, and edit the configuration, as needed. For the "sitesCm" part (used by ECL), set a value for stubFolders where the value the URI of the folder that where the ECL stub items will be stored. You must manually create this folder, note the URI, and then specify that URI in this property.
The Java template generates configuration both for ECL and PCA.
Upload the configuration file to the details view of deployed connector in the Add-on UI.
If the Connector's integration uses Public Content API, then restart the Content Service.
If the Connector's integration uses ECL, then refresh the Content Manager Explorer UI or just the current publication.

Using the New Connector

Via Tridion Content Manager you will see the new connector as a new mountpoint which you can navigate through the demo folders and view a few test items. The metadata of the test items can be updated as well.

The connector is also available via the PCA GraphQL interface. You can use the embedded GraphQL client in the PCA (if it is enabled) to run the queries, which is available on the following URL: <content service address>/cd/api/graphiql (for example http://tridion.sdldemo.com:8081/cd/api/graphiql)

Below are a few examples of GraphQL requests that interacts with the connector. To use them in your environment you might need to modify the namespace ("dem") and the type names ("DemoFile" and "DemoFolder").

Get a single item:

{
 externalItem(
   identity: {
     namespace: "dem",
     id: "file1",
     type: "DemoFile"
   }) {
    ... on DemoFile {
      title
      thumbnail
      details {
        length
        numberOfAccess
      }
    }
  }
}

Response:

{
  "data": {
    "externalItem": {
      "title": "File 1",
      "thumbnail": "http://tridion.sdldemo.com:8081/cd/api/external/binary/dem/thumbnail/DemoThumbnail.jpg",
      "details": {
        "length": 100,
        "numberOfAccess": 5
      }
    }
  }
}

List a folder:

{
  externalItems(namespace: "dem"
    filter: {
      context: {
        id: "folder1"
        type: "DemoFolder"
      }
    }) {
    edges {
      node {
        ... on DemoFile {
          identity {
            namespace
            id
            type
          }
          title
        }
      }
    }
  }
}

Response:

{
  "data": {
    "externalItems": {
      "edges": [
      {
        "node": {
          "identity": {
            "namespace": "dem",
            "id": "file1",
            "type": "DemoFile"
          },
          "title": "File 1"
        }
      },
      {
        "node": {
          "identity": {
            "namespace": "dem",
            "id": "file2",
            "type": "DemoFile"
          },
          "title": "File 2"
        }
      },
      {
        "node": {
          "identity": {
            "namespace": "dem",
            "id": "file5",
            "type": "DemoFile"
          },
          "title": "File 5"
        }
      }
    ]
   }
 }
}

For more information about the connector GraphQL requests, see:
https://docs.sdl.com/LiveContent/content/en-US/SDL%20Tridion%20Sites-v2/GUID-C1540E2B-9C9A-4071-B4AD-3B490FBBD9B6
https://docs.sdl.com/LiveContent/content/en-US/SDL%20Tridion%20Sites-v2/GUID-8A849DCF-70AB-469F-8D8C-9DBE009FB304

Summary

Using the different templates for C# and Java can kickstart your development of new Tridion connectors. In addition the add-on service makes it easy to centrally configure and deploy your connectors to various parts of your Tridion system. In the next blog post I will describe more in details the concepts of the Tridion Integration Framework and go through an example connector.

In meantime here are a few additional resources:

Implementing Connectors: https://docs.sdl.com/LiveContent/content/en-US/SDL%20Tridion%20Sites-v2/GUID-20EB960E-25E8-4B5B-99F5-9136039B907A
Video recording from a TDS talk on the Tridion Integration Framework: https://vimeo.com/374369509

Content Mashup as Component Link

Sayantan Basu — Mon, 15 Jul 2019 22:29:00 GMT

You may already have seen the concept of doing content mashup using Tridion Sites Connector. If not you can check this blog from Manish to get an idea. Today I am going to share another way to do that between Sites and Docs.

Assume you have maintained all of your products on sites and you want to add a product specification (Topic) from Docs along with that.

Using sites connector is one of the options for that. But there is another way to achieve it using a component link.

Here is the approach for that –

I have segregated the implementation in 2 parts.

First Part-

I have created an MVC application (Not Mandatory, you can use ASP.Net application as well) to connect the Tridion Docs using service API and retrieve all the topics/publications from DOCS Content Manager and bind the result in a grid view.
- Here is the code to get all the Topics/Publication using DOCS service API

To retrieve the Topics:

public static List<Topic> ReadTopicsFromDocs(InfoShareWSHelper infoShareWsHelper)
{
List<Topic> topics = new List<Topic>();

//build a object of GetDocumentObj25Channel to retrieve the topics
var object25Channel = infoShareWsHelper.GetDocumentObj25Channel();

//define metadata wants to retrieve
string ishMeta =
"<ishfields>" +
"<ishfield name='FTITLE' level='logical'/>" +
"<ishfield name='FAUTHOR' level='lng'/>" +
"<ishfield name='FSTATUS' level='lng'/>" +
"</ishfields>";

//call Find() method to bring that data back from the DOCS environment
string obj = object25Channel.Find(ISHType.ISHModule.ToString(), StatusFilter.ISHNoStatusFilter, "", ishMeta);

topics = BindTopic(obj);
return topics;
}

To retrieve the Publications:

public static List<Publication> ReadPublicationFromDocs(InfoShareWSHelper infoShareWsHelper)
{
List<Publication> publications = new List<Publication>();

//Build a object of GetPublication25Channel to retrieve the publications
var object25Channel = infoShareWsHelper.GetPublication25Channel();

//define metadata wants to retrieve
string ishMeta =
"<ishfields>" +
"<ishfield name='FTITLE' level='logical'/>" +
"<ishfield name='MODIFIED-ON' level='lng'/>" +
"<ishfield name='FSTATUS' level='lng'/>" +
"<ishfield name='FISHPUBLICATIONTYPE' level='logical'/>" +
"</ishfields>";
string obj = object25Channel.Find(StatusFilter.ISHNoStatusFilter, "", ishMeta);
publications = BindPublication(obj);
return publications;
}

Deploy the application on the web server and run it. Here are the look and feel of the application
As you can see in the screenshot, there is an option to choose the item and click on the button ("Add To CMS") to add it to Tridion CMS. In a nutshell, the functionality is once the user clicks on that button the GUID of that selected topic/publication will be added as a link. For that, you need to add below necessary javascript on the view.
- Here is the Javascript I am using to add that
  
  $(document).ready(function () {
  $('#topic_table').DataTable();
  });
  
  $('input:checkbox').change(function () {
  $('input:checkbox').not(this).prop('checked', false);
  });
  
  $('#btnCreateAsset').click(function (event) {
  var topicId;
  $.each($("input[name='selectCheckBox']:checked"), function () {
  topicId = $(this).attr('id');
  });
  if (topicId != null) {
  alert("You Have Selected: " + topicId);
  var fields = window.dialogArguments.getFields();
  if (fields && fields.length > 0) {
  fields[0].setValues([topicId]);
  }
  }
  else {
  alert("Select a Topic First")
  }
  
  });
Now bind this URL with your schema field so that you can use it as Custom URL extension. ( If you are not familiar with custom URL extension, there is a nice blog on this from Neetesh Narvaria. You can follow this as a starting point.)

We have finished all the required step to mashup the content from the Tridion CMS side.

Second Part-

In this section, I will explain how to retrieve the actual content from DOCS based on that GUID using CPA on the web application end.

I am using SDL DXA on the web application side so I try to utilize the existing methods to retrieve the data.

First I have added an InputItemFilter to pass that GUID as InputCustomMetaCriteria. Here is the code snippet for that -

InputItemFilter finelFilterCriteria = new InputItemFilter{
CustomMeta = new InputCustomMetaCriteria
{
Key = Constants.PublicationID,
Value = query.DocsPublicationID,
Scope = CriteriaScope.Publication
}
};
Once InputItemFilter criteria are ready to use, call the Graphql client and call ExecuteItemQuery() method using the necessary parameter to get the result -

var client = ApiClientFactory.Instance.CreateClient();
var results = client.ExecuteItemQuery(filter, null, new Pagination{First = pageSize,After = queryParams.Cursor}, null, ContentIncludeMode.Exclude, false, null);

That’s all. Hope you like it. Happy coding. Here is the source code of Custom Application.