Philip Medcraft

Tuesday, 14 January 2020

Enabling https in DXA Spring Boot Application

In my previous article, I presented the steps for converting a Java DXA webapp to a Spring Boot application. I would now like to present the steps for enabling https in this context.

Spring Boot's documentation specifies a few simple configuration additions to the application.properties file to enable https. However, in my experience these were insufficient to make the DXA Spring Boot application connect to the Tridion Sites microservices over https.

The alternative working approach involved extending the embedded Tomcat application server by setting some properties against the Connector and Http11NioProtocol.

The following bespoke properties were added to the dxa.properties file.

# Tomcat connector configuration
server.tomcat.port=8080
server.tomcat.ssl.enabled=true
server.tomcat.ssl.key-alias=ssl-key-alias.com
server.tomcat.ssl.key-store=certificates/key-store-file.jks
server.tomcat.ssl.key-password=SslKeyPassw0rd!
server.tomcat.ssl.key-store-type=JKS
server.tomcat.ssl.trust-store=certificates/trustStore.jks
server.tomcat.ssl.trust-store-password=SslTrustStorePassw0rd!
server.tomcat.ssl.certificate-fs-store-location=DXA/certificates

The certificate files are placed within the /src/main/resources/certificates folder in the application. This means these files will be embedded in the built WAR file inside the /certificates folder.

The certificate files cannot be referenced using the absolute path when deployed by Spring Boot inside an embedded Tomcat application server, so these need to be written to the file system onto the location specified by the server.tomcat.ssl.certificate-fs-store-location property.

IMPORTANT NOTE: if using Maven with a <resource> configuration entry specifying <filtering>true</filtering>, this will cause the certificate files (.jks in this example) to become corrupted.

The bespoke properties are referenced in the Spring Boot application using the @Value annotation.

@Value("${server.tomcat.port}")
private Integer port;

@Value("${server.tomcat.ssl.enabled:false}")
private boolean enableSsl;

@Value("${server.tomcat.ssl.key-alias:}")
private String sslKeyAlias;

@Value("${server.tomcat.ssl.key-store:}")
private String sslKeyStore;

@Value("${server.tomcat.ssl.key-password:}")
private String sslKeyPassword;

@Value("${server.tomcat.ssl.key-store-type:}")
private String sslKeyStoreType;

@Value("${server.tomcat.ssl.trust-store:}")
private String sslTrustStore;

@Value("${server.tomcat.ssl.trust-store-password:}")
private String sslTrustStorePassword;

@Value("${server.tomcat.ssl.certificate-fs-store-location:}")
private String certificateFileSystemStoreLocation;

An org.springframework.core.io.ResourceLoader is autowired to support reading the .jks certificate files from the configured location (i.e. certificates/key-store-file.jks).

The customization is implemented by invoking the addConnectorCustomizers method against the TomcatEmbeddedServletContainerFactory as shown below.

@Bean
public EmbeddedServletContainerCustomizer addConnectorCustomizers(){
return container -> {
if(container instanceof TomcatEmbeddedServletContainerFactory){
TomcatEmbeddedServletContainerFactory factory =
(TomcatEmbeddedServletContainerFactory)container;
factory.addConnectorCustomizers(connector -> {
connector.setPort(port);
if (enableSsl) {
Http11NioProtocol protocol =
(Http11NioProtocol)connector.getProtocolHandler();
connector.setScheme("https");
connector.setSecure(true);
protocol.setSSLEnabled(true);
try {
FileSystemResource keyStoreFile = new
FileSystemResource(getResource(sslKeyStore,
sslKeyPassword));
FileSystemResource trustStoreFile = new
FileSystemResource(getResource(sslTrustStore,
sslTrustStorePassword));

System.setProperty("javax.net.ssl.trustStore",
trustStoreFile.getFile().getAbsolutePath());
System.setProperty("javax.net.ssl.trustStorePassword",
sslTrustStorePassword);

protocol.setKeyAlias(sslKeyAlias);
protocol.setKeyPass(sslKeyPassword);

protocol.setKeystoreFile(keyStoreFile.getFile()
.getAbsolutePath());
protocol.setKeystorePass(sslKeyPassword);

protocol.setTruststoreFile(trustStoreFile.getFile()
.getAbsolutePath());

protocol.setTruststorePass(sslTrustStorePassword);
}
catch (Exception exception) {
throw new RuntimeException(
"Error setting up the SSL configuration [" +
exception.getMessage() + "]");
}
}
});
}
};
}

Resources

For completeness, the supporting code and property extracts can be found here.

	#@formatter:off
	## You can find the complete list of properties on DXA documentation page.
	## This file is an example of how to override DXA properties and configure your DXA application.

	dxa.caching.required.caches=defaultCache, pageModels, entityModels, failures

	# Disabling ADF results in a significant performance gain,
	# but ADF is needed for XPM Session Preview, Experience Optimization and Context Expressions.
	dxa.web.adf.enabled=false

	dxa.csrf.allowed=true

	### ===================================================================================================================
	### Model Service client configuration
	### ===================================================================================================================
	# By default DXA gets the URL of Model Service through Discovery Service. If you are not happy with this for any reason,
	# you can specify the URL to your Model Service, which will be used instead.
	dxa.model.service.url=https://model-service-url:9082

	# Model Service doesn't have its own CIS capability and registers as a part of Content Service. This property sets a key name for the URL in extension properties of CS.
	dxa.model.service.key=dxa-model-service

	# These four properties set a default mapping of MS REST endpoints. Unless you really know what you're doing, don't change them.
	dxa.model.service.url.entity.model=/EntityModel/{uriType}/{localizationId}/{componentId}-{templateId}
	dxa.model.service.url.page.model=/PageModel/{uriType}/{localizationId}/{pageUrl}?includes={pageInclusion}
	dxa.model.service.url.api.navigation=/api/navigation/{localizationId}
	dxa.model.service.url.api.navigation.subtree=/api/navigation/{localizationId}/subtree/{siteMapId}?includeAncestors={includeAncestors}&descendantLevels={descendantLevels}

	# Tomcat connector configuration
	server.tomcat.port=8080
	server.tomcat.ssl.enabled=true
	server.tomcat.ssl.key-alias=ssl-key-alias.com
	server.tomcat.ssl.key-store=certificates/key-store-file.jks
	server.tomcat.ssl.key-password=SslKeyPassw0rd!
	server.tomcat.ssl.key-store-type=JKS
	server.tomcat.ssl.trust-store=certificates/trustStore.jks
	server.tomcat.ssl.trust-store-password=SslTrustStorePassw0rd!
	# The certificates embedded inside the Spring Boot executable cannot be referenced, so need to be written to the file system to the location specified below
	server.tomcat.ssl.certificate-fs-store-location=DXA/certificates

	#@formatter:on

view raw dxa.properties hosted with ❤ by GitHub

	package com.sdl.webapp.main;

	import com.sdl.dxa.DxaSpringInitialization;

	import org.apache.coyote.http11.Http11NioProtocol;

	import org.slf4j.Logger;
	import org.slf4j.LoggerFactory;

	import org.springframework.beans.factory.annotation.Autowired;
	import org.springframework.boot.context.embedded.EmbeddedServletContainerCustomizer;
	import org.springframework.boot.context.embedded.tomcat.TomcatEmbeddedServletContainerFactory;
	import org.springframework.beans.factory.annotation.Value;
	import org.springframework.context.annotation.Bean;
	import org.springframework.context.annotation.Configuration;
	import org.springframework.context.annotation.Import;
	import org.springframework.core.io.FileSystemResource;
	import org.springframework.core.io.Resource;
	import org.springframework.core.io.ResourceLoader;

	import java.io.File;
	import java.io.FileOutputStream;
	import java.io.IOException;
	import java.security.KeyStore;
	import java.security.KeyStoreException;
	import java.security.NoSuchAlgorithmException;
	import java.security.cert.CertificateException;

	@Import(DxaSpringInitialization.class)
	@Configuration
	public class SpringInitializer {

	private static final Logger LOG = LoggerFactory.getLogger(SpringInitializer.class);

	@Value("${server.tomcat.port}")
	private Integer port;

	@Value("${server.tomcat.ssl.enabled:false}")
	private boolean enableSsl;

	@Value("${server.tomcat.ssl.key-alias:}")
	private String sslKeyAlias;

	@Value("${server.tomcat.ssl.key-store:}")
	private String sslKeyStore;

	@Value("${server.tomcat.ssl.key-password:}")
	private String sslKeyPassword;

	@Value("${server.tomcat.ssl.key-store-type:}")
	private String sslKeyStoreType;

	@Value("${server.tomcat.ssl.trust-store:}")
	private String sslTrustStore;

	@Value("${server.tomcat.ssl.trust-store-password:}")
	private String sslTrustStorePassword;

	@Value("${server.tomcat.ssl.certificate-fs-store-location:}")
	private String certificateFileSystemStoreLocation;

	@Autowired
	private ResourceLoader resourceLoader;

	@Bean
	public EmbeddedServletContainerCustomizer addConnectorCustomizers() {
	return container -> {
	if (container instanceof TomcatEmbeddedServletContainerFactory) {
	TomcatEmbeddedServletContainerFactory factory = (TomcatEmbeddedServletContainerFactory)container;
	factory.addConnectorCustomizers(connector -> {
	connector.setPort(port);
	if (enableSsl) {
	Http11NioProtocol protocol = (Http11NioProtocol)connector.getProtocolHandler();
	connector.setScheme("https");
	connector.setSecure(true);
	protocol.setSSLEnabled(true);
	try {
	FileSystemResource keyStoreFile = new FileSystemResource(
	getResource(sslKeyStore, sslKeyPassword));
	FileSystemResource trustStoreFile = new FileSystemResource(
	getResource(sslTrustStore, sslTrustStorePassword));

	System.setProperty("javax.net.ssl.trustStore", trustStoreFile.getFile().getAbsolutePath());
	System.setProperty("javax.net.ssl.trustStorePassword", sslTrustStorePassword);

	protocol.setKeyAlias(sslKeyAlias);
	protocol.setKeyPass(sslKeyPassword);
	protocol.setKeystoreFile(keyStoreFile.getFile().getAbsolutePath());
	protocol.setKeystorePass(sslKeyPassword);
	protocol.setTruststoreFile(trustStoreFile.getFile().getAbsolutePath());
	protocol.setTruststorePass(sslTrustStorePassword);
	}
	catch (Exception exception) {
	throw new RuntimeException("Error setting up the SSL configuration [" +
	exception.getMessage() + "]");
	}
	}
	});
	}
	};
	}

	private File getResource(String keyStorePath, String keyStorePassword) throws KeyStoreException,
	NoSuchAlgorithmException, CertificateException, IOException {
	Resource resource = resourceLoader.getResource(keyStorePath);
	KeyStore keyStore = KeyStore.getInstance(sslKeyStoreType);
	keyStore.load(resource.getInputStream(), keyStorePassword.toCharArray());
	File dir = new File(certificateFileSystemStoreLocation);
	if (!dir.exists())
	dir.mkdirs();
	File file = new File(dir.getPath() + "/" + resource.getFilename());
	try (FileOutputStream fos = new FileOutputStream(file)) {
	keyStore.store(fos, keyStorePassword.toCharArray());
	}
	return file;
	}
	}

view raw SpringInitializer.java hosted with ❤ by GitHub

Tuesday, 7 January 2020

Converting Java DXA Webapp to Spring Boot APP

In this article, I would like to present the steps for converting the Java DXA (v2.2.1) application into a Spring Boot application.

Executable Artifact

As stated in Spring Boot’s documentation (https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-jsp-limitations), when running a Spring Boot application that uses an embedded servlet container (and is packaged as an executable archive), there are some limitations in the JSP support. The recommended approach is to build the solution as an executable WAR file, which can be launched with java -jar just like a normal jar executable.

Spring Boot dependencies

I have utilized an alternative to the starter spring-boot-starter-parent project since many implementations have a custom Maven parent. It is still possible to benefit from the spring-boot-starter-parent project's dependency tree by adding a dependency spring-boot-dependencies into our project in import scope.

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>1.5.21.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>

The chosen Spring Boot version (1.5.21.RELEASE) automatically provides all the Spring dependencies in the version (v4.3.24.RELEASE) required by the DXA 2.2.1 framework. This way no other Spring Framework dependencies are needed in the Maven pom file.

The other required Spring Boot dependencies are:

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>1.5.21.RELEASE</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
<version>1.5.21.RELEASE</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.apache.tomcat.embed</groupId>
<artifactId>tomcat-embed-jasper</artifactId>
<version>8.5.40</version>
<scope>provided</scope>
</dependency>

The spring-boot-starter-tomcat and tomcat-embed-jasper dependencies are added to enable running the built executable WAR file inside an embedded Tomcat application server.

The spring-boot-maven-plugin is utilized to repackage the standard WAR build into an executable WAR file.

<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>1.5.21.RELEASE</version>
<configuration>
    <executable>true</executable>
</configuration>
<executions>
    <execution>
      <goals>
        <goal>repackage</goal>
      </goals>
      <configuration>
        <classifier>spring-boot</classifier>
        <mainClass>com.sdl.webapp.main.WebAppInitializer</mainClass>
      </configuration>
    </execution>
</executions>
</plugin>

A full pom example can be viewed here.

Initializing the Application

The WebAppInitializer class is the starting point of the Spring Boot application.

package com.sdl.webapp.main;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class WebAppInitializer {
public static void main(String[] args) {
SpringApplication.run(WebAppInitializer.class, args);
}
}

This class is annotated with @SpringBootApplication, which among other things, tells Spring to look for other components, configurations and services inside the same package. Therefore, I placed the SpringInitializer class inside the same package annotated with @Import(DxaSpringInitialization.class) in order to kick off the DXA initialization process.

package com.sdl.webapp.main;

import com.sdl.dxa.DxaSpringInitialization;

import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;

@Import(DxaSpringInitialization.class)
@Configuration
public class SpringInitializer {
}

Application Properties

The spring.profiles.active property had to be moved from the dxa.properties file into Spring Boot's application.properties file.

Here are the contents of the application.properties file.

logging.config=classpath:logback.xml
spring.profiles.active=cil.providers.active,search.solr

Deploying the Application

The built executable WAR file is deployed from the command-line using:

java -jar dxaSpringBoot-2.2.1-spring-boot.war

The DXA application is started inside an embedded Tomcat application server.

Resources

For completeness, the supporting code and property extracts can be found here.

	logging.config=classpath:logback.xml

	# Multiple-line configuration is possible
	# search.solr - Activates SOLR in Search, Not compatible with search.aws
	# dynamic.navigation.provider - Dynamic navigation provider to be used instead of static
	# adf.context.provider - Activates ADF instead of ContextService
	spring.profiles.active=cil.providers.active,search.solr

view raw application.properties hosted with ❤ by GitHub

	#@formatter:off
	## You can find the complete list of properties on DXA documentation page.
	## This file is an example of how to override DXA properties and configure your DXA application.

	dxa.caching.required.caches=defaultCache, pageModels, entityModels, failures

	# Disabling ADF results in a significant performance gain,
	# but ADF is needed for XPM Session Preview, Experience Optimization and Context Expressions.
	dxa.web.adf.enabled=false

	dxa.csrf.allowed=true

	### ===================================================================================================================
	### Model Service client configuration
	### ===================================================================================================================
	# By default DXA gets the URL of Model Service through Discovery Service. If you are not happy with this for any reason,
	# you can specify the URL to your Model Service, which will be used instead.
	dxa.model.service.url=http://model-service-url:9082

	# Model Service doesn't have its own CIS capability and registers as a part of Content Service. This property sets a key name for the URL in extension properties of CS.
	dxa.model.service.key=dxa-model-service

	# These four properties set a default mapping of MS REST endpoints. Unless you really know what you're doing, don't change them.
	dxa.model.service.url.entity.model=/EntityModel/{uriType}/{localizationId}/{componentId}-{templateId}
	dxa.model.service.url.page.model=/PageModel/{uriType}/{localizationId}/{pageUrl}?includes={pageInclusion}
	dxa.model.service.url.api.navigation=/api/navigation/{localizationId}
	dxa.model.service.url.api.navigation.subtree=/api/navigation/{localizationId}/subtree/{siteMapId}?includeAncestors={includeAncestors}&descendantLevels={descendantLevels}

	#@formatter:on

view raw dxa.properties hosted with ❤ by GitHub

	<?xml version="1.0" encoding="UTF-8"?>
	<project
	xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
	http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<version>2.2.1</version>
	<artifactId>dxaSpringBoot</artifactId>
	<packaging>war</packaging>
	<name>Spring Boot DXA</name>
	<properties>
	<java-version>1.8</java-version>
	<dxa-bom.version>2.2.1</dxa-bom.version>
	<dxaversion>2.2.1</dxaversion>
	<dxa-release-branch>release/2.2</dxa-release-branch>
	</properties>
	<dependencyManagement>
	<dependencies>
	<dependency>
	<groupId>com.sdl.delivery</groupId>
	<artifactId>udp-iq-api-common</artifactId>
	<version>11.0.0-1049</version>
	</dependency>
	<dependency>
	<groupId>com.sdl.delivery</groupId>
	<artifactId>udp-core</artifactId>
	<version>11.0.0-1044</version>
	</dependency>
	<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-dependencies</artifactId>
	<version>1.5.21.RELEASE</version>
	<type>pom</type>
	<scope>import</scope>
	</dependency>
	</dependencies>
	</dependencyManagement>
	<dependencies>
	<!-- Dependencies -->
	<dependency>
	<groupId>com.sdl.dxa</groupId>
	<artifactId>dxa-common-api</artifactId>
	<version>${dxaversion}</version>
	</dependency>
	<dependency>
	<groupId>com.sdl.dxa</groupId>
	<artifactId>dxa-common</artifactId>
	<version>${dxaversion}</version>
	</dependency>
	<dependency>
	<groupId>com.sdl.dxa</groupId>
	<artifactId>dxa-tridion-provider</artifactId>
	<version>${dxaversion}</version>
	</dependency>
	<dependency>
	<groupId>com.sdl.dxa.modules</groupId>
	<artifactId>dxa-module-core</artifactId>
	<version>${dxaversion}</version>
	</dependency>
	<dependency>
	<groupId>org.json</groupId>
	<artifactId>json</artifactId>
	<version>20140107</version>
	</dependency>
	<dependency>
	<groupId>org.apache.httpcomponents</groupId>
	<artifactId>httpclient</artifactId>
	<version>4.5.9</version>
	</dependency>
	<dependency>
	<groupId>org.slf4j</groupId>
	<artifactId>slf4j-api</artifactId>
	<version>1.7.28</version>
	</dependency>
	<!-- Spring Boot -->
	<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-web</artifactId>
	<version>1.5.21.RELEASE</version>
	</dependency>
	<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-tomcat</artifactId>
	<version>1.5.21.RELEASE</version>
	<scope>provided</scope>
	</dependency>
	<dependency>
	<groupId>org.apache.tomcat.embed</groupId>
	<artifactId>tomcat-embed-jasper</artifactId>
	<version>8.5.40</version>
	<scope>provided</scope>
	</dependency>
	<dependency>
	<groupId>javax.servlet</groupId>
	<artifactId>jstl</artifactId>
	<version>1.2</version>
	</dependency>
	</dependencies>
	<build>
	<plugins>
	<plugin>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-maven-plugin</artifactId>
	<version>1.5.21.RELEASE</version>
	<configuration>
	<executable>true</executable>
	</configuration>
	<executions>
	<execution>
	<goals>
	<goal>repackage</goal>
	</goals>
	<configuration>
	<classifier>spring-boot</classifier>
	<mainClass>com.sdl.webapp.main.WebAppInitializer</mainClass>
	</configuration>
	</execution>
	</executions>
	</plugin>
	</plugins>
	</build>
	</project>

view raw pom.xml hosted with ❤ by GitHub

	package com.sdl.webapp.main;

	import com.sdl.dxa.DxaSpringInitialization;

	import org.springframework.context.annotation.Configuration;
	import org.springframework.context.annotation.Import;

	@Import(DxaSpringInitialization.class)
	@Configuration
	public class SpringInitializer {
	}

view raw SpringInitializer.java hosted with ❤ by GitHub

	package com.sdl.webapp.main;

	import org.springframework.boot.SpringApplication;
	import org.springframework.boot.autoconfigure.SpringBootApplication;

	@SpringBootApplication
	public class WebAppInitializer {
	public static void main(String[] args) {
	SpringApplication.run(WebAppInitializer.class, args);
	}
	}

view raw WebAppInitializer.java hosted with ❤ by GitHub

Tuesday, 16 April 2019

Complete a Task Step in SDL WorldServer using the REST API

In this article, I would like to present a method for completing an active Task Step in SDL WorldServer using the REST API.

The method takes three parameters:

wsBaseUrl
token
completeTaskStepRequestBody

The wsBaseUrl must be the <serverURL>:<portnumber> where your WorldServer instance is running.

The second parameter is a security token, which can be retrieved by using the SDL WorldServer REST API as explained here.

The third parameter is a CompleteTaskStepRequestBody object containing the data to support the task step completion. This includes the id (task id), the transitionId and an optional comment to set as metadata. The task id and transition id can be retrieved by invoking the REST call described here for retrieving the tasks from a specified Project. The returned TaskDetails object provides the data.

The method returns a boolean value specifying whether the task step completion was successful.

	public class CompleteTaskStepRequestBody {

	private int id;
	private int transitionId;
	private String comment;

	public int getId() {
	return id;
	}

	public void setId(int id) {
	this.id = id;
	}

	public int getTransitionId() {
	return transitionId;
	}

	public void setTransitionId(int transitionId) {
	this.transitionId = transitionId;
	}

	public String getComment() {
	return comment;
	}

	public void setComment(String comment) {
	this.comment = comment;
	}
	}

view raw CompleteTaskStepRequestBody.java hosted with ❤ by GitHub

	public static boolean completeTaskStep(String wsBaseUrl, String token, CompleteTaskStepRequestBody completeTaskStepRequestBody)
	throws IOException, URISyntaxException {

	JsonObject jsonObject = doPost(wsBaseUrl, "/ws-api/v1/tasks/complete", token, Arrays.asList(completeTaskStepRequestBody));
	return StringUtils.equals(jsonObject.getAsJsonPrimitive("status").getAsString(), "OK");
	}

	public static JsonObject doPost(String wsBaseUrl, String restPath, String token, Object pojo)
	throws IOException, URISyntaxException {

	URI postUri = new URIBuilder(wsBaseUrl + restPath)
	.addParameter("token", token)
	.addParameter("content-type", "application/json")
	.build();

	HttpClient httpClient = HttpClientBuilder.create().build();
	HttpPost httpPost = new HttpPost(postUri);
	httpPost.setEntity(getStringEntity(pojo));

	HttpResponse response = httpClient.execute(httpPost);
	Gson gson = new GsonBuilder().create();

	return gson.fromJson(new InputStreamReader(response.getEntity().getContent()), JsonObject.class);
	}

view raw WSRestUtils06.java hosted with ❤ by GitHub

Download an asset associated with a TASK in SDL WorldServer using the REST API

In this article, I would like to present a method for downloading a file (asset) associated with a Task in SDL WorldServer using the REST API.

The method takes six parameters:

wsBaseUrl
token
taskId
assetName
downloadLocation
assetLocationType

The wsBaseUrl must be the <serverURL>:<portnumber> where your WorldServer instance is running.

The second parameter is a security token, which can be retrieved by using the SDL WorldServer REST API as explained here.

The third parameter is the id of the Task in SDL WorldServer to download the asset from.

The fourth parameter is the name of the asset to download. This can be retrieved by invoking the REST call described here for retrieving the tasks from a specified Project. The returned TaskDetails object provides the targetAsset attribute containing the path to the target asset. Use this path to work out the file (asset) name.

The firth parameter is the path to the download location where to place the downloaded file.

Finally the sixth parameter is used to determine the location type: SOURCE, TARGET or SOURCE_TARGET.

The method returns a String containing the path to the downloaded file.

	public enum AssetLocationType {
	SOURCE,
	TARGET,
	SOURCE_TARGET
	}

view raw AssetLocationType.java hosted with ❤ by GitHub

	public enum AssetResourceType {
	TASK,
	PROJECT,
	PROJECT_GROUP
	}

view raw AssetResourceType.java hosted with ❤ by GitHub

	public static String getAssetFromTask(String wsBaseUrl, String token, int taskId, String assetName,
	String downloadLocation, AssetLocationType assetLocationType)
	throws IOException, URISyntaxException {

	File translatedFile = new File(downloadLocation, assetName);

	URI getUri = new URIBuilder(wsBaseUrl + "/ws-api/v1/files/asset")
	.addParameter("token", token)
	.addParameter("resourceId", String.valueOf(taskId))
	.addParameter("assetLocationType", assetLocationType.toString())
	.addParameter("resourceType", AssetResourceType.TASK.toString())
	.build();

	HttpClient httpClient = HttpClientBuilder.create().build();
	HttpGet httpGet = new HttpGet(getUri);

	HttpResponse response = httpClient.execute(httpGet);
	byte[] bytes = EntityUtils.toByteArray(response.getEntity());
	FileUtils.writeByteArrayToFile(translatedFile, bytes);

	return translatedFile.getPath();
	}

view raw WSRestUtils05.java hosted with ❤ by GitHub

Get a list of Tasks from a Project in SDL WorldServer using the REST API

In this article, I would like to present a method for retrieving a list of Tasks from a Project in SDL WorldServer using the REST API.

The method takes three parameters:

wsBaseUrl
token
projectId

The wsBaseUrl must be the <serverURL>:<portnumber> where your WorldServer instance is running.

The second parameter is a security token, which can be retrieved by using the SDL WorldServer REST API as explained here.

The third parameter is the id of the Project in SDL WorldServer to retrieve the tasks from.

The method returns a List of TaskDetails objects, one for each task returned, containing a subset of the JSON response data.

	public class CurrentTaskStep {

	private int id;
	private String name;
	private String displayName;
	private String type;
	private String typeName;
	private List<WorkflowTransition> workflowTransitions;

	public int getId() {
	return id;
	}

	public void setId(int id) {
	this.id = id;
	}

	public String getName() {
	return name;
	}

	public void setName(String name) {
	this.name = name;
	}

	public String getDisplayName() {
	return displayName;
	}

	public void setDisplayName(String displayName) {
	this.displayName = displayName;
	}

	public String getType() {
	return type;
	}

	public void setType(String type) {
	this.type = type;
	}

	public String getTypeName() {
	return typeName;
	}

	public void setTypeName(String typeName) {
	this.typeName = typeName;
	}

	public List<WorkflowTransition> getWorkflowTransitions() {
	return workflowTransitions;
	}

	public void setWorkflowTransitions(List<WorkflowTransition> workflowTransitions) {
	this.workflowTransitions = workflowTransitions;
	}

	public class WorkflowTransition {
	private int id;
	private int index;
	private String text;

	public int getId() {
	return id;
	}

	public void setId(int id) {
	this.id = id;
	}

	public int getIndex() {
	return index;
	}

	public void setIndex(int index) {
	this.index = index;
	}

	public String getText() {
	return text;
	}

	public void setText(String text) {
	this.text = text;
	}
	}
	}

view raw CurrentTaskStep.java hosted with ❤ by GitHub

	public class TaskDetails {

	private int id;
	private CurrentTaskStep currentTaskStep;
	private String targetAsset;

	public int getId() {
	return id;
	}

	public void setId(int id) {
	this.id = id;
	}

	public CurrentTaskStep getCurrentTaskStep() {
	return currentTaskStep;
	}

	public void setCurrentTaskStep(CurrentTaskStep currentTaskStep) {
	this.currentTaskStep = currentTaskStep;
	}

	public String getTargetAsset() {
	return targetAsset;
	}

	public void setTargetAsset(String targetAsset) {
	this.targetAsset = targetAsset;
	}
	}

view raw TaskDetails.java hosted with ❤ by GitHub

	public static List<TaskDetails> getTasksFromProject(String wsBaseUrl, String token, int projectId)
	throws IOException, URISyntaxException {

	Gson gson = new GsonBuilder().create();

	URI getUri = new URIBuilder(wsBaseUrl + "/ws-api/v1/tasks")
	.addParameter("token", token)
	.addParameter("projectId", String.valueOf(projectId))
	.build();

	List<TaskDetails> tasks = new ArrayList<>();

	JsonObject jsonObject = getItems(getUri);
	JsonArray items = jsonObject.getAsJsonArray("items");
	Iterator<JsonElement> itemIterator = items.iterator();
	while (itemIterator.hasNext()) {
	JsonObject item = itemIterator.next().getAsJsonObject();

	// Get the current task step details
	JsonObject jsonCurrentTaskStep = item.getAsJsonObject("currentTaskStep");

	CurrentTaskStep currentTaskStep = new CurrentTaskStep();
	currentTaskStep.setId(jsonCurrentTaskStep.getAsJsonPrimitive("id").getAsInt());
	currentTaskStep.setName(jsonCurrentTaskStep.getAsJsonPrimitive("name").getAsString());
	currentTaskStep.setDisplayName(jsonCurrentTaskStep.getAsJsonPrimitive("displayName").getAsString());
	currentTaskStep.setType(jsonCurrentTaskStep.getAsJsonPrimitive("type").getAsString());
	currentTaskStep.setTypeName(jsonCurrentTaskStep.getAsJsonPrimitive("typeName").getAsString());
	// Fetch the transitions
	List<CurrentTaskStep.WorkflowTransition> workflowTransitions = new ArrayList<>();
	Iterator<JsonElement> transitionsIt = jsonCurrentTaskStep.getAsJsonArray("workflowTransitions").iterator();
	while (transitionsIt.hasNext()) {
	workflowTransitions.add(gson.fromJson(transitionsIt.next(), CurrentTaskStep.WorkflowTransition.class));
	}
	currentTaskStep.setWorkflowTransitions(workflowTransitions);

	// Bundle everything together
	TaskDetails taskDetails = new TaskDetails();
	taskDetails.setId(item.getAsJsonPrimitive("id").getAsInt());
	taskDetails.setCurrentTaskStep(currentTaskStep);
	// Fetch the target asset (if present)
	JsonArray targetAssetsArray = item.getAsJsonArray("targetAssets");
	if (targetAssetsArray.size() > 0) {
	taskDetails.setTargetAsset(targetAssetsArray.get(0).getAsString());
	}

	// Add to the list
	tasks.add(taskDetails);
	}

	return tasks;
	}

view raw WSRestUtils04.java hosted with ❤ by GitHub

Create Project Groups in SDL WorldServer using the REST API

In this article, I would like to present a method for creating a Project Group in SDL WorldServer using the REST API.

The method takes three parameters:

wsBaseUrl
token
projectGroups

The wsBaseUrl must be the <serverURL>:<portnumber> where your WorldServer instance is running.

The second parameter is a security token, which can be retrieved by using the SDL WorldServer REST API as explained here.

The third parameter is a List of ProjectGroup objects, each one containing the data required for creating each Project Group in WorldServer. This includes the name, description, projectTypeId, clientId, the list of files for translation (systemFiles) and the list of Locales (target locales). The systemFiles attribute (List of String) must be populated with each asset's internalName returned by the file upload process described here.

The method returns a List of CreateProjectGroupResponse objects, one for each project group created, containing the JSON response data. With this data, it is possible to verify if the call was successful and also retrieve the newly created project group id.

	public class CreateProjectGroupResponse {

	private String status;
	private List<Response> response;

	public String getStatus() {
	return status;
	}

	public void setStatus(String status) {
	this.status = status;
	}

	public List<Response> getResponse() {
	return response;
	}

	public void setResponse(List<Response> response) {
	this.response = response;
	}

	public class Response {

	private String status;
	private int response;

	public String getStatus() {
	return status;
	}

	public void setStatus(String status) {
	this.status = status;
	}

	public int getResponse() {
	return response;
	}

	public void setResponse(int response) {
	this.response = response;
	}
	}
	}

view raw CreateProjectGroupResponse.java hosted with ❤ by GitHub

	public class Locale {

	private int id;
	private String dueDate;

	public int getId() {
	return id;
	}

	public void setId(int id) {
	this.id = id;
	}

	public String getDueDate() {
	return dueDate;
	}

	public void setDueDate(String dueDate) {
	this.dueDate = dueDate;
	}
	}

view raw Locale.java hosted with ❤ by GitHub

	public class ProjectGroup {

	private String name;
	private String description;
	private int projectTypeId;
	private int clientId;
	private List<String> systemFiles;
	private List<Locale> locales;

	public String getName() {
	return name;
	}

	public void setName(String name) {
	this.name = name;
	}

	public String getDescription() {
	return description;
	}

	public void setDescription(String description) {
	this.description = description;
	}

	public int getProjectTypeId() {
	return projectTypeId;
	}

	public void setProjectTypeId(int projectTypeId) {
	this.projectTypeId = projectTypeId;
	}

	public int getClientId() {
	return clientId;
	}

	public void setClientId(int clientId) {
	this.clientId = clientId;
	}

	public List<String> getSystemFiles() {
	return systemFiles;
	}

	public void setSystemFiles(List<String> systemFiles) {
	this.systemFiles = systemFiles;
	}

	public List<Locale> getLocales() {
	return locales;
	}

	public void setLocales(List<Locale> locales) {
	this.locales = locales;
	}
	}

view raw ProjectGroup.java hosted with ❤ by GitHub

	public static CreateProjectGroupResponse createProjectGroup(String wsBaseUrl, String token, List<ProjectGroup> projectGroups)
	throws IOException, URISyntaxException {

	JsonObject jsonObject = doPost(wsBaseUrl, "/ws-api/v1/projectGroups/create", token, projectGroups);
	Gson gson = new GsonBuilder().create();

	return gson.fromJson(jsonObject, CreateProjectGroupResponse.class);
	}

	public static JsonObject doPost(String wsBaseUrl, String restPath, String token, Object pojo)
	throws IOException, URISyntaxException {

	URI postUri = new URIBuilder(wsBaseUrl + restPath)
	.addParameter("token", token)
	.addParameter("content-type", "application/json")
	.build();

	HttpClient httpClient = HttpClientBuilder.create().build();
	HttpPost httpPost = new HttpPost(postUri);
	httpPost.setEntity(getStringEntity(pojo));

	HttpResponse response = httpClient.execute(httpPost);
	Gson gson = new GsonBuilder().create();

	return gson.fromJson(new InputStreamReader(response.getEntity().getContent()), JsonObject.class);
	}

	private static StringEntity getStringEntity(Object pojo) {
	Gson gson = new GsonBuilder().create();
	String jsonString = gson.toJson(pojo);
	return new StringEntity(jsonString, ContentType.APPLICATION_JSON);
	}

view raw WSRestUtils03.java hosted with ❤ by GitHub

	public static void createProjectGroup(Properties config, String token) throws IOException, URISyntaxException, NumberFormatException {

	if (!enableProjectCreation(config))
	return;

	// Upload assets
	Collection<File> assetFiles = getIncomingFiles(config);
	if (assetFiles == null \|\| assetFiles.isEmpty()) {
	System.out.println("There are no incoming files.");
	return;
	}

	List<FileUploadResponse> responses = WSRestUtils.uploadAssets(getWsBaseUrl(config), token, assetFiles);

	// Create project group
	List<String> internalNames = new ArrayList<>();
	for (FileUploadResponse fileUploadResponse : responses) {
	internalNames.add(fileUploadResponse.getInternalName());
	}

	ProjectGroup projectGroup = new ProjectGroup();
	projectGroup.setName("Project - " + internalNames.get(0));
	projectGroup.setDescription("Project created using the REST API.");
	projectGroup.setClientId(getClientId(config));
	projectGroup.setProjectTypeId(getProjectTypeId(config));
	projectGroup.setLocales(getLocales(config));
	projectGroup.setSystemFiles(internalNames);

	// Create the project group
	CreateProjectGroupResponse response = WSRestUtils
	.createProjectGroup(getWsBaseUrl(config), token, Arrays.asList(projectGroup));

	if (StringUtils.equalsIgnoreCase(response.getStatus(), "OK")) {
	System.out.println("Created project group with id: " + response.getResponse().get(0).getResponse());
	// Move the asset files to the processed folder
	File processedFolder = new File(getProcessedFolder(config));
	for (File file : assetFiles) {
	FileUtils.moveFileToDirectory(file, processedFolder, false);
	}
	System.out.println("Moved files to the processed folder");
	}
	}

view raw WSRestUtils04.java hosted with ❤ by GitHub

Upload files to SDL WorldServer using the REST API

In this article, I would like to present a method for uploading a collection of files to SDL WorldServer using the REST API.

The method takes three parameters:

wsBaseUrl
token
files

The wsBaseUrl must be the <serverURL>:<portnumber> where your WorldServer instance is running.

The second parameter is a security token, which can be retrieved by using the SDL WorldServer REST API as explained here.

The third parameter is a Collection of File objects for upload.

The method returns a List of FileUploadResponse objects, one for each uploaded file, containing data from the uploaded asset. With this information, it is possible to create Projects in WorldServer using the REST API and place these assets through translation.

	public class FileUploadResponse {

	private String name;
	private String internalName;
	private String fullName;
	private String url;
	private double size;
	private long creationTime;
	private boolean exists;
	private File[] files;

	public String getName() {
	return name;
	}

	public void setName(String name) {
	this.name = name;
	}

	public String getInternalName() {
	return internalName;
	}

	public void setInternalName(String internalName) {
	this.internalName = internalName;
	}

	public String getFullName() {
	return fullName;
	}

	public void setFullName(String fullName) {
	this.fullName = fullName;
	}

	public String getUrl() {
	return url;
	}

	public void setUrl(String url) {
	this.url = url;
	}

	public double getSize() {
	return size;
	}

	public void setSize(double size) {
	this.size = size;
	}

	public long getCreationTime() {
	return creationTime;
	}

	public void setCreationTime(long creationTime) {
	this.creationTime = creationTime;
	}

	public boolean isExists() {
	return exists;
	}

	public void setExists(boolean exists) {
	this.exists = exists;
	}

	public File[] getFiles() {
	return files;
	}

	public void setFiles(File[] files) {
	this.files = files;
	}
	}

view raw FileUploadResponse.java hosted with ❤ by GitHub

	public static List<FileUploadResponse> uploadAssets(String wsBaseUrl, String token, Collection<File> files)
	throws IOException, URISyntaxException {

	List<FileUploadResponse> fileUploadResponses = new ArrayList<>();

	for (File file : files) {
	String boundary = "--" + UUID.randomUUID() + "--";
	URI postUri = new URIBuilder(wsBaseUrl + "/ws-api/v1/files")
	.addParameter("token", token)
	.addParameter("content-type", "multipart/form-data; boundary=" + boundary)
	.build();

	MultipartEntityBuilder builder = MultipartEntityBuilder
	.create()
	.setMode(HttpMultipartMode.BROWSER_COMPATIBLE)
	.setBoundary(boundary)
	.addPart("file", new FileBody(file));

	HttpPost httpPost = new HttpPost(postUri);
	httpPost.setEntity(builder.build());

	HttpClient httpClient = HttpClientBuilder.create().build();
	HttpResponse response = httpClient.execute(httpPost);

	Gson gson = new GsonBuilder().create();
	FileUploadResponse fileUploadResp = gson
	.fromJson(new InputStreamReader(response.getEntity().getContent()), FileUploadResponse.class);

	fileUploadResponses.add(fileUploadResp);
	}

	return fileUploadResponses;
	}

view raw WSRestUtils02.java hosted with ❤ by GitHub