LiveWords Connector and Webhook

Connector Repository Configuration

To configure the LiveWords connector, set the following property in the repository:

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

Obtain configuration values from your LiveWords.com account. Register for an account if you do not have one.

The connector interacts with the LiveWords REST API to submit documents for translation. It is developed for LiveWords version 'pigwhale'.

Environment Variables (Recommended)

You can configure the connector using environment variables instead of storing values in the JCR. The following table lists the supported properties and their corresponding environment variables:

Property	Environment variable
livewords.api.url	LIVEWORDS_API_URL
livewords.api.user	LIVEWORDS_API_USER
livewords.api.key	LIVEWORDS_API_KEY
livewords.feed.name	LIVEWORDS_FEED_NAME
livewords.send.translation.endpoint	LIVEWORDS_SEND_TRANSLATION_ENDPOINT
livewords.target.language.parametername	LIVEWORDS_TARGET_LANGUAGE_PARAMETERNAME
livewords.certification.check	LIVEWORDS_CERTIFICATION_CHECK

If environment variables are not set, the connector falls back to system properties, and then to JCR values.

JCR Configuration

All configuration properties are set on the translationsaddon:connector node:

String property	Default value	Description
livewords.api.url		Base API URL for LiveWords where documents are posted.
livewords.api.user		LiveWords API username for authorization.
livewords.api.key		LiveWords API key for authorization.
livewords.feed.name		Feed name as configured in the LiveWords environment.
livewords.send.translation.endpoint	items	Endpoint name as configured in the LiveWords environment.
livewords.target.language.parametername	target-language	Parameter name for specifying target languages.
livewords.certification.check	true	Use a secure connection. Keep this set to true; the API requires SSL.

The connector constructs the full URL for posting documents using the URL, feed, endpoint, and parameter name values. For example:
https://pigwhale.api.eu-1.livewords.com/myfeed/items?target-language=en,de

Webhook for Callback

When a translation is complete in LiveWords, the system posts the translated document to a callback URL configured as a "Target" in LiveWords. To handle this callback, install a REST resource in your site module. For installation instructions, see Translations Add-on Installation. The REST resource processes the POST request and creates a translation event for a backend service to consume.

Selecting a Callback URL

Expose a site URL that LiveWords can reach. You can use a subpath of an existing domain (for example, http://www.example.com/rest/livewords/) or a new subdomain (for example, https://callback.example.com/livewords/). The REST resource requires the URL to end with /livewords/.

Ensure that the chosen URL routes to your site web application in your web server (such as Apache httpd or nginx).

HST Hosts Configuration

Configure HST to map the callback URL (excluding the /livewords/ suffix) to the plain REST pipeline in a mount. For more information, see Plain JAX-RS Services documentation.

For an existing domain such as www.example.com, create the following node structure under the relevant host group (for example, /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]
copy

If you use a new subdomain, map its hst:root mount to the JaxrsRestPlainPipeline.

Authorization

The REST resource verifies the authenticity of the callback by checking the signature in the authorization headers. The signature uses the HMAC algorithm and the configured API key.

For details, refer to LiveWords webhook documentation.

Response Codes

The webhook returns the following HTTP response codes:

• 417 SC_EXPECTATION_FAILED: No API key is configured in the repository.
• 401 SC_UNAUTHORIZED: Header-based signature validation failed.
• 406 SC_NOT_ACCEPTABLE: The request is not to /livewords/{language}.
• 406 SC_NOT_ACCEPTABLE: The request does not contain data.
• 500 SC_INTERNAL_SERVER_ERROR: Internal event bus is not found.
• 200 OK: Request processed successfully.

In com.bloomreach.cms.translations.connector.livewords.rest.TranslationResource, all non-200 responses are logged at ERROR level. A 200 response is logged at INFO level.

Using ngrok for Local Development

For local development or demonstrations, you can use ngrok to tunnel requests from LiveWords to your local instance.

1. Download ngrok from ngrok.com, install it, and run ngrok http 8080 to tunnel to your local site. ngrok will provide a URL such as http://d36e92a5.ngrok.io that forwards requests to localhost.
2. Configure this URL in your HST host configuration, for example: /hst:hst/hst:hosts/ngrok/io/ngrok/d36e92a5/hst:root/rest, where the rest mount is mapped to the JaxrsRestPlainPipeline.
3. Set the full ngrok.io URL as the "Target" in the LiveWords environment for the relevant language, for example: http://d36e92a5.ngrok.io/site/rest/livewords/.