XTM Connector

Overview

The XTM Connector provides an out-of-the-box integration with XTM Translation Services. For more information about XTM, visit https://xtm.cloud/.

When to Use

Use the XTM Connector to automate translation workflows between Bloomreach Content and XTM Translation Services.

Prerequisites

Access to an XTM account. Register for an account if you do not have one.
Bloomreach Content instance with the Translations Add-on installed.

Installation

Add the translations-addon-connector-xtm dependency to your project as described on the installation page.
Configure the connector class in the repository:

/hippo:configuration/hippo:modules/translation-services-daemon/hippo:moduleconfig/translationsaddon:connector-xtm/className=
    com.bloomreach.cms.translations.connector.xtm.XTMTranslationConnector

Obtain the required configuration values from your XTM account.

Configuration

Environment Variables (Recommended)

You can configure the connector using environment variables to avoid storing sensitive values in the JCR. The following table lists the supported environment variables:

Property	Environment Variable
xtm.apiURL	XTM_APIURL
xtm.companyName	XTM_COMPANYNAME
xtm.password	XTM_PASSWORD
xtm.callbackURL	XTM_CALLBACKURL

If these environment variables are not set, the connector will use system properties as a fallback, and then the JCR configuration.

JCR Configuration

Configure the following properties at the translationsaddon:connector node:

String Property	Default Value	Description
xtm.apiURL		Required. URL of the XTM API (e.g., https://api-test.xtm-intl.com/project-manager-api-rest/)
xtm.companyName		Required. Company name for XTM (e.g., Bloomreach)
xtm.password		Required. Password for XTM API (BASIC AUTH)
xtm.localesMap	{"en":"en_US", "de":"de_DE", "nl":"nl_NL", "fr":"fr_FR", "en_GB":"en_GB"}	Required. JSON string mapping CMS locales to XTM locales
xtm.templateId		Required. XTM templateId (e.g., 3669)
xtm.callbackURL		URL for callback (e.g., http://somesiteurl/rest/xtm/jobFinished)
xtm.customerId		Required. XTM customerId (e.g., 23)
xtm.userId		Required. XTM userId (e.g., 20)

Callback Webhook

When a linguist submits a translated file in XTM, XTM posts the translated document to a callback URL. This URL must be configured and accessible from the public internet.

To support the callback:

Install a REST resource in the site module.
The REST resource receives the GET request from XTM and triggers a translation event for backend processing.

Selecting a Callback URL

The callback URL must be publicly accessible.
The URL must end with /xtm/jobFinished. For example:
- http://www.example.com/rest/xtm/jobFinished
- https://callback.example.com/xtm/jobFinished
Since version 6.2.0, the REST resource checks for configuration at the root path /xtm/.

Ensure your web server (e.g., Apache httpd, nginx) routes the callback URL to the site web application.

HST Hosts Configuration

Configure the HST to map the callback URL (excluding the /xtm/jobFinished suffix) to the plain REST pipeline in a mount. For example, for www.example.com, configure the following node structure under /hst:hst/hst:hosts/production:

+ com [hst:virtualhost] 
  + example [hst:virtualhost] 
    + www [hst:virtualhost]
      + hst:root [hst:mount]
        + rest [hst:mount]
          - hst:alias: rest
          - hst:ismapped: false
          - hst:namedpipeline: JaxrsRestPlainPipeline
          - hst:types: [rest]

Note:
For versions prior to 6.2.0 (see release notes), you must also configure the API URL and credentials at the mount level in addition to the connector node:

          - xtm.apiURL: URL of XTM API (e.g., https://api-test.xtm-intl.com/project-manager-api-rest/)
          - xtm.companyName: company name for XTM (e.g., Bloomreach)
          - xtm.password: XTM password for BASIC auth
          - xtm.userId: XTM user id for BASIC auth (integer)

Verification

Confirm that the connector can communicate with the XTM API using the configured credentials.
Submit a translation job and verify that translated content is posted back to the configured callback URL.
Check that the REST resource processes the callback and triggers the translation event.

Troubleshooting

If translations are not returned, verify that the callback URL is accessible from the internet and correctly routed to the site web application.
Ensure all required configuration properties are set and match your XTM account details.
For authentication errors, confirm that the API credentials are correct and active in XTM.