The LiveWords Connector and web hook

Connector repository configuration

To set up the LiveWords connector, set this property in the repository:

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

Configuration settings are to be taken from your LiveWords.com account. Apply for one if you don't have one yet.

The connector uses the LiveWords REST API to post document to and is developed on LiveWords version 'pigwhale'.

All configuration at the translationsaddon:connector node:

The URL, feed, endpoint and parameter name values will be used to construct a full URL to post document to, resulting for example in "https://pigwhale.api.eu-1.livewords.com/myfeed/items?target-language=en,de".

The web hook for callback

When translations are done in the LiveWords system, translated documents are posted back to a URL that is set up in LiveWords as a "Target". To support this callback, a REST resource is to be installed in the site module. The REST resource takes the post request and creates a translation event that a backend service listens to.

Choose callback URL
A certain site URL has to be available for the outside world to post to. You may choose for instance a suburl of an existing domain, say http://www.example.com/rest/livewords/ or a new subdomain, say https://callback.example.com/livewords/. The REST resources matches on the ending /livewords/ so that part is mandatory.

Make sure the URL will reach the site webapp in your webservers (Apache httpd, nginx).

HST hosts configuration
The HST has to be configured to map the callback URL (without the ending /livewords/) to the plain REST pipeline in a mount. See also the Plain JAX-RS services documentation.

So for an existing www.example.com, have this node structure below the applicable host group, say at /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]

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

Authorization
To ensure the authenticity of the callback, the REST resource checks the signature, using certain authorization headers which are encoded with the HMAC algorithm together the configured API key (see above section).

It follows this documentation at LiveWords.

Response codes

The web hook returns the following HTTP response codes to the callback.

417 SC_EXPECTATION_FAILED if no key configured in the repository
401 SC_UNAUTHORIZED if header-based signature fails 
406 SC_NOT_ACCEPTABLE if the call is not /livewords/{language} 
406 SC_NOT_ACCEPTABLE if the call does not contain data 
500 SC_INTERNAL_SERVER_ERROR if internal event bus is not found
200 OK otherwise

Also, in class com.bloomreach.cms.translations.connector.livewords.rest.TranslationResource messages at ERROR level are logged for all codes except 200, which has an INFO log message.

Using ngrok tunnelling in your local enviroment

For local development or demo purposes, you can use ngrok application for secure tunnelling to localhost, to have LiveWords post documents to you local instance.

1. Download from ngrok.com, install, run it  as "ngrok http 8080" to tunnel to your locally running site. It will output a URL like http://d36e92a5.ngrok.io that is forwarded to localhost.
2. Configure this URL in your HST host, e.g. /hst:hst/hst:hosts/ngrok/io/ngrok/d36e92a5/hst:root/rest where the rest is mapped to the JaxrsRestPlainPipeline (see above)

3. Set up the full nrgok.io URL in the LIveWords environment as "Target" for a certain language:  http://d36e92a5.ngrok.io/site/rest/livewords/