FTP Connector - Bloomreach Experience - The Headless Digital Experience Platform Built for Commerce

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:

String property Default value Description
ftp.ftpServerHost   Mandatory
ftp hostname, for example ftp.company.com
ftp.ftpUsername   Mandatory
User name to access FTP
ftp.ftpPassword   Mandatory
Password to access FTP
ftp.hostPublicKey   Mandatory
Public key of FTP server
ftp.smtpUsername   Mandatory
User name to connect to SMTP server
ftp.smtpPassword   Mandatory
Password to connect to SMTP server
ftp.emailPropNames

example: 

mail.smtp.auth,mail.smtp.starttls.enable,

mail.smtp.host,mail.smtp.port

Mandatory

Comma-separated list of property names to inject into email connection. Must be same length as emailPropValues

ftp.emailPropValues

example: 

true,true,smtp.gmail.com,587

Mandatory

Comma-separated list of property values to inject into email connection. Must be same length as emailPropValues

ftp.notificationEmailAddresses   Mandatory
comma-separated list of email recipients
ftp.notificationEmailSender   Mandatory
email address of sender
ftp.folderLocationIn IN Location on FTP server where to upload jobs
ftp.fileNameSeparator -- Separator to use in file names {locale}{separator}{targetid}.xml
ftp.folderLocationOut OUT Location on FTP server where to fetch jobs from
ftp.newRequestNotificationSubject     Subject line of email sent when new translation job is sent
ftp.newRequestNotificationBody   Body of email sent when new translation job is sent
ftp.jobRetrievedNotificationSubject   Subject line of email sent when translation is fetched
ftp.jobRetrievedNotificationBody   Body  of email sent when new translation job is fetched
ftp.jobCancelledNotificationSubject   Subject line of email sent when new translation job is cancelled
ftp.jobCancelledNotificationBody   Body of email sent when new translation job is cancelled

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:

Placeholder   Description
%%FILENAME%%   The relevant filename
%%LINK%%   Link to the relevant file on the ftp sever
%%DATE%%   The timestamp of the event
%%USER%%   The requesting user
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?