Integrating with External Systems

Info: Bloomreach provides Enterprise support for this feature to Bloomreach Experience customers. The release cycle for this feature may differ from the core product release cycle.

This feature requires an additional license. Contact your account manager or sales representative for details.

The Translations Add-on enables sending and retrieving documents between Bloomreach Content and external translation systems.

To integrate with an external system, the system must expose a suitable API. You must implement and configure a connector as a Java class.

The Translations Add-on supports the following integrations:

• ChatGPT: AI-powered translations using OpenAI’s API. See the ChatGPT connector documentation.
• GlobalLink (transperfect.com): See the GlobalLink connector documentation.
  (Connector rewritten since version 7.2.1 for brXM 16)
• LiveWords (livewords.com): See the LiveWords connector documentation.
• Star Translation Services (star-ts.com): See the Star connector documentation.
• XTM Translation Services (xtm.cloud): See the XTM connector documentation.
• FTP: Generic connector using the SFTP protocol. See the FTP connector documentation.

A Tester Connector is also available for testing and demonstration. This connector does not interact with an external system but can echo translation requests for validation.

Environment-First Configuration (Recommended)

Connector configuration prioritizes environment variables for sensitive values. You can provide any connector property as an environment variable by converting the key to uppercase and replacing . or - with _.

Example:
livewords.api.key becomes LIVEWORDS_API_KEY.

The connector resolves configuration values in the following order:

1. Environment variable
2. System property (for example, -Dlivewords.api.key=...)
3. Connector-specific fallback keys (where documented)
4. JCR configuration

If no environment variable is set, the connector uses the existing JCR configuration.

Document Format

Documents are sent to and typically retrieved from the external system in a generic XML format. The following example illustrates the structure:

<document jobItemId="aec3aa3b.." [jcr:uuid of job item node]
          jobItemCreator="admin01" [since 6.2.0, user that submitted the request]
          jobItemCreated="2022-10-13T11:00:00.000+02:00" [since 6.2.0]
          jobItemLastModified="2022-10-14T12:00:00.000+02:00" [since 6.2.0]    
          documentId="9e1c972d.." [jcr:uuid of the document handle]
          name="test1" [document handle node name)
          path="/content/documents/myproject/news/test1"
          type="mynamespace:mytester" [JCR document type]
          translationId="b06571e2.." [hippotranslation:id of the document; link between translated documents]
          translationLocale="en" [hippotranslation:locale of the document]>
    <name>Test 1 Display Name</name>
    <mixinTypes>
        <mixinType>mix:versionable</mixinType>
        <mixinType>mix:referenceable</mixinType>
    </mixinTypes>
    <fields>
        <!-- regular string field -->
        <field isPropertyField="true" multiple="false" name="[mynamespace]:mystring" type="String">
            <value>Text</value>
        </field>
        <!-- multiple string field -->
        <field isPropertyField="true" multiple="true" name="[mynamespace]:mymultiplestring" type="String">
            <value>one</value>
            <value>two</value>
            <value>three</value>
        </field>
        <!-- compound rich text editor field -->
        <field name="[mynamespace]:myhippostd_html" type="hippostd:html">
            <value>&lt;p&gt;Extended HTML Lorem ipsum&amp;nbsp;&lt;/p&gt;</value>
        </field>
        <!-- primitive HTML field -->
        <field isPropertyField="true" multiple="false" name="[mynamespace]:myhtml" type="String">
            <value>&lt;p&gt;Simple HTML Lorem ipsum&amp;nbsp;&lt;/p&gt;</value>
        </field>
        <!-- text field -->
        <field isPropertyField="true" multiple="false" name="[mynamespace]:mytext" type="String">
            <value>Text Lorem Ipsum</value>
        </field>
        <!-- date field -->
        <field isPropertyField="true" multiple="false" name="[mynamespace]:mydate" type="Date"> 
            <value>2022-10-13T17:00:00.000+02:00</value>
        </field>
        <!-- integer number field -->
        <field isPropertyField="true" multiple="false" name="[mynamespace]:mylong" type="Long">
            <value>10</value>
        </field>
        <!-- decimal number field -->
        <field isPropertyField="true" multiple="false" name="[mynamespace]:mydouble" type="Double">
            <value>100.0</value>
        </field>
        <!-- compound link field -->
        <field name="[mynamespace]:myhippo_mirror" type="hippo:mirror">
            <value>9caea793-42b1-4f3e-a8e5-d58f810ce2ef</value>
        </field>
       <!-- docbase field -->
        <field isPropertyField="true" multiple="false" name="[mynamespace]:mydocbase" type="String">
            <value>64ab4648-0c20-40d2-9f18-d7a394f0334b</value>
        </field>
        <!-- boolean field -->
        <field isPropertyField="true" multiple="false" name="[mynamespace]:myboolean" type="Boolean">
            <value>true</value>
        </field>
    </fields>
</document>
copy