Generic FTP Connector

Connector Design

The generic translation connector connects to a configurable FTP server and finds a configured location for JOBS-IN. The connector will then create an XML file on the remote server for each translationTargetId received by the plugin, for example this translation job is received by the connector with 4 translation targets:

jobItem = {
  id  =  "6779bcd3-b87c-446b-9a2a-cd9ec16a19cb",
  translationJobId  =  "e72b7240-9fa9-4aa3-8de5-eedd6f71d029",
  created  =  "01/01/2020",
  creator  =  "admin",
  documentId  =  "aeda2bcd-b21d-4ead-a2e6-c64a2ca051c8",
  sourceLocale  = "en_US",
  documentName = "The gastropoda news",
  translationTargets = [
    {
      id = '1eab46db-6113-4ba1-bb3e-1e91dc3aef5c',
      translationJobItemId = '6779bcd3-b87c-446b-9a2a-cd9ec16a19cb',
      targetLocale = "de_DE"
    },
    {
      id = '8cc9ba90-c46f-4497-8632-baa9bc56d036', 
      translationJobItemId = '6779bcd3-b87c-446b-9a2a-cd9ec16a19cb', 
      targetLocale = "en_GB"
    },
    {
      id='369d480f-15de-4176-bbe6-ab8844bbbb4a', 
      translationJobItemId='6779bcd3-b87c-446b-9a2a-cd9ec16a19cb', 
      targetLocale="fr_FR"
    },
    {
      id='3ec53020-9b77-4a94-b09e-04098683fec3', 
      translationJobItemId='6779bcd3-b87c-446b-9a2a-cd9ec16a19cb', 
      targetLocale="nl_NL"
    }
  ]
}

The connector must therefore create in the JOBS-IN folder the following:

A folder called 6779bcd3-b87c-446b-9a2a-cd9ec16a19cb, representing the job, and inside it 4 XML files called:

de_DE-1eab46db-6113-4ba1-bb3e-1e91dc3aef5c.xml,

en_GB-8cc9ba90-c46f-4497-8632-baa9bc56d036.xml,

fr_FR-369d480f-15de-4176-bbe6-ab8844bbbb4a.xml

and nl_NL-3ec53020-9b77-4a94-b09e-04098683fec3.xml

Which represent the translation requests for each target locale.

Each XML file contains the data received by the connector, for example:

<?xml version="1.0" encoding="utf-8"?>
<document type="translationsaddondemo:newsdocument" jobItemId="6779bcd3-b87c-446b-9a2a-cd9ec16a19cb"
         documentId="aeda2bcd-b21d-4ead-a2e6-c64a2ca051c8" name="the-gastropoda-news"
         path="/content/documents/translationsaddondemo/news/2019/03/the-gastropoda-news"
         translationId="2b644d39-c59d-4de3-98c3-16c908dbc7c9" translationLocale="en" title="The gastropoda news">
   <name>The gastropoda news</name>
   <mixinTypes>
       <mixinType>mix:referenceable</mixinType>
   </mixinTypes>
   <fields>
       <field name="translationsaddondemo:title" multiple="false" type="String" isPropertyField="true">
           <value>The gastropoda news</value>
       </field>
       <field name="translationsaddondemo:introduction" multiple="false" type="String" isPropertyField="true">
           <value>Lorem ipsum dolor sit amet</value>
       </field>
       <field name="translationsaddondemo:content" type="hippostd:html">
           <value>&lt;html&gt;
               &lt;body&gt;
               &lt;p&gt;Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
               tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
               quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
               consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
               dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident,
               sunt in culpa qui officia deserunt mollit anim id est laborum&lt;/p&gt;
               &lt;/body&gt;
               &lt;/html&gt;
           </value>
       </field>
   </fields>
</document>

Note that the content of the XML will be the same for all translation targets. The connector will then send an email to a configured list of email addresses via a configured SMTP server, notifying the agency that a new translation job has landed.

Once the agency receives the email, they can download the files and translate the content between the <value> tags only. It is essential that they do not break the XML document and do not change the metadata such as the locale.

Once the xml has been translated, the agency should put in the configured JOBS-OUT location a folder that represents the job (6779bcd3-b87c-446b-9a2a-cd9ec16a19cb in our example) and the completed xml files with their original names (de_DE-1eab46db-6113-4ba1-bb3e-1e91dc3aef5c.xml, en_GB-8cc9ba90-c46f-4497-8632-baa9bc56d036.xml, fr_FR-369d480f-15de-4176-bbe6-ab8844bbbb4a.xml and nl_NL-3ec53020-9b77-4a94-b09e-04098683fec3.xml in our example).

The connector then uses a polling strategy to check for files in the JOBS-OUT folder. When a completed job is found, it can determine the target locale from the filename and send a translation event to the event bus to complete the workflow (see the Tester connector for an example). If successful, it should delete the files from the remote location to prevent it being picked up again on the next polling. An email notification is sent again to tell the agency that a job has been retrieved.

When the translation agency starts a job, they must remove the xml files from the JOBS-IN folder to indicate that they have started a job. When an editor deletes a job from the translation addon dashboard, the connector will only delete the job if the file is still present in the JOBS-IN folder. An email should be sent when a job is deleted.

Summary

An out-of-the-box connector to send translation jobs to an FTP server and to retrieve completed jobs from it. The connector also sends emails to notify a target of incoming translation documents. The connector uses a polling strategy to check for completed translation jobs. This is compatible with translation agencies such as DCT.

Set up

To set up the connector, add dependency 'translations-addon-connector-ftp' as mentioned in the installation page.

Then set this property in the repository:

/hippo:configuration/hippo:modules/translation-services-daemon/hippo:moduleconfig/translationsaddon:connector-FTP/className=
    com.bloomreach.cms.translations.connector.ftp.FTPTranslationConnector

Configuration settings should match the FTP server.

The configuration at the translationsaddon:connector node:

Turn on translation results processing scheduler job

As also mentioned at the configuration page, be sure have translation results pulled into the repository, by enabling the trigger at

/hippo:configuration/hippo:modules/scheduler/hippo:moduleconfig/translationsaddon/TranslationResultsProcessor/hipposched:triggers/every-minute

Set the property hipposched:enabled to true (checked) and save the changes.

You can also change the value of hipposched:cronExpression to adjust the time interval this job runs to check translation results on remote server.

Email notification settings

The email subjects and bodies replace certain strings with information coming from the connector: