The LiveWords Connector and web hook - BloomReach Experience - Open Source CMS

This article covers a Hippo CMS version 11. There's an updated version available that covers our most recent release.

12-10-2017

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:

String property Default value Description
livewords.api.url   LiveWords base API URL where documents are posted to.
livewords.api.user   Your LiveWords API username, on behalf of authorization.
livewords.api.key   Your LiveWords API key, on behalf of authorization.
livewords.feed.name   The name of the feed as set up up in the LiveWords environment . 
livewords.send.translation.endpoint items The name of the end point as set up in the LiveWords environment. 
livewords.target.language.parametername target-language The name of the parameter used to define to language(s) a document is supposed to be translated to.
livewords.certification.check true

Use a secure connection. Leave at true because the API is SSL-only.

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/

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?