Generic FTP Connector
Overview
The Generic FTP Connector enables integration between Bloomreach Content and a configurable FTP server for translation workflows. It exports translation jobs as XML files to a designated location on the FTP server and retrieves completed translations from another location. The connector also sends email notifications to inform translation agencies of job status changes.
Connector Design
The connector connects to a specified FTP server and monitors a configured directory for incoming translation jobs (JOBS-IN). For each translation target in a job, the connector creates an XML file on the remote server. For example, if a translation job contains four translation targets, the connector receives a payload similar to the following:
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 creates a folder named after the job ID (6779bcd3-b87c-446b-9a2a-cd9ec16a19cb) within the JOBS-IN directory. Inside this folder, it generates one XML file per translation target:
en_US-to-de_DE--1eab46db-6113-4ba1-bb3e-1e91dc3aef5c.xmlen_US-to-en_GB--8cc9ba90-c46f-4497-8632-baa9bc56d036.xmlen_US-to-fr_FR--369d480f-15de-4176-bbe6-ab8844bbbb4a.xmlen_US-to-nl_NL--3ec53020-9b77-4a94-b09e-04098683fec3.xml
Each XML file contains the job data. The content is identical for all translation targets, except for the target locale. Example XML:
<?xml version="1.0" encoding="utf-8"?> <document type="translationsaddondemo:newsdocument" jobItemId="6779bcd3-b87c-446b-9a2a-cd9ec16a19cb" jobItemCreator="admin" jobItemCreated="2025-04-23T10:44:22.930+02:00" jobItemLastModified="2025-04-23T10:44:22.930+02:00" 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><html> <body> <p>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</p> </body> </html> </value> </field> <field name="targetLocale" multiple="false" type="String" isPropertyField="true"> <value>de_DE</value> </field> </fields> </document>
After creating the files, the connector sends an email notification to a configured list of recipients through an SMTP server. This informs the translation agency that a new translation job is available.
The translation agency downloads the XML files and translates only the content within the <value> tags. The agency must not modify the XML structure or metadata, including the locale.
When the agency begins processing a job, it removes the XML files from the JOBS-IN folder to indicate the job has started. If an editor deletes a job from the translation add-on dashboard, the connector deletes the job only if the files are still present in the JOBS-IN folder. In this case, the connector sends a notification email.
After translation is complete, the agency uploads the translated XML files to the configured JOBS-OUT location, preserving the original folder and file names.
The connector polls the JOBS-OUT folder for completed jobs. When it detects completed files, it determines the target locale from the filename and sends a translation event to the local event bus to complete the workflow. After successful processing, the connector deletes the files from the remote location to avoid duplicate processing. It also sends an email notification to inform the agency that the job has been retrieved.
Summary
The Generic FTP Connector provides an out-of-the-box solution for sending translation jobs to an FTP server and retrieving completed translations. It supports email notifications for job status updates and uses a polling strategy to detect completed jobs. The connector is compatible with translation agencies such as DCT.
Setup
Add the Connector Dependency
Add the translations-addon-connector-ftp dependency as described on the installation page.
Configure the Connector Class
Set the following property in the repository to register the FTP connector:
/hippo:configuration/hippo:modules/translation-services-daemon/hippo:moduleconfig/translationsaddon:connector-FTP/className=
com.bloomreach.cms.translations.connector.ftp.FTPTranslationConnector
Ensure that the configuration matches your FTP server settings.
Environment Variables (Recommended)
You can configure the connector using environment variables instead of storing values in the JCR. The following properties are supported:
| Property | Environment variable |
|---|---|
| ftp.ftpServerHost | FTP_FTPSERVERHOST |
| ftp.ftpUsername | FTP_FTPUSERNAME |
| ftp.ftpPassword | FTP_FTPPASSWORD |
| ftp.hostPublicKey | FTP_HOSTPUBLICKEY |
| ftp.smtpUsername | FTP_SMTPUSERNAME |
| ftp.smtpPassword | FTP_SMTPPASSWORD |
If environment variables are not set, the connector falls back to system properties and then to JCR values.
JCR Configuration
Configure the connector at the translationsaddon:connector node. The following table lists available properties:
| String property | Default value | Description |
|---|---|---|
| ftp.ftpServerHost | Required. FTP hostname, e.g., ftp.company.com | |
| ftp.ftpServerPort Since 5.6.0 | 0 | Optional. FTP port for the connection. 0 (default) means not set. |
| ftp.connectTimeoutMillis Since 5.6.0 | 0 | Optional. Connection timeout in milliseconds. 0 (default) means no timeout. |
| ftp.ftpChannelType Since 5.6.0 | "sftp" | Optional. Channel type for the connection. |
| ftp.ftpUsername | Required. Username for FTP access. | |
| ftp.ftpPassword | Required. Password for FTP access. | |
| ftp.hostPublicKey | Required. Public key of the FTP server. | |
| ftp.smtpUsername | Required. Username for SMTP server. | |
| ftp.smtpPassword | Required. Password for SMTP server. | |
| ftp.emailPropNames | example: mail.smtp.auth,mail.smtp.starttls.enable,mail.smtp.host,mail.smtp.port | Required. Comma-separated email property names. Must match emailPropValues in length. |
| ftp.emailPropValues | example: true,true,smtp.gmail.com,587 | Required. Comma-separated email property values. Must match emailPropNames in length. |
| ftp.notificationEmailEnabled | true | Set to false to disable job creation email notifications. |
| ftp.notificationEmailAddresses | Required. Comma-separated list of email recipients. | |
| ftp.notificationEmailSender | Required. Sender email address. | |
| ftp.errorEmailEnabled | true | Set to false to disable error email notifications. |
| ftp.errorNotificationEmailAddresses | Required. Email address for error notifications. | |
| ftp.folderLocationIn | IN | FTP directory for uploading jobs. |
| ftp.folderLocationOut | OUT | FTP directory for retrieving completed jobs. |
| ftp.fileNameSeparator | -- | Separator for filenames: {locale}{separator}{targetid}.xml |
| ftp.newRequestNotificationSubject | Subject for new translation job email. | |
| ftp.newRequestNotificationBody | Required. Body for new translation job email. | |
| ftp.jobRetrievedNotificationSubject | Subject for translation retrieval email. | |
| ftp.jobRetrievedNotificationBody | Required. Body for translation retrieval email. | |
| ftp.jobCancelledNotificationSubject | Subject for job cancellation email. | |
| ftp.jobCancelledNotificationBody | Required. Body for job cancellation email. | |
| ftp.errorNotificationSubject | Subject for job failure email. | |
| ftp.errorNotificationBody | Required. Body for job failure email. | |
| ftp.defaultDeadlineDays | 7 | Default deadline in days (used if additional fields extension is enabled). |
Enable Translation Results Processing Scheduler
To ensure translation results are imported into the repository, enable the scheduler job as described on the configuration page:
/hippo:configuration/hippo:modules/scheduler/hippo:moduleconfig/translationsaddon/TranslationResultsProcessor/hipposched:triggers/every-minute
Set the hipposched:enabled property to true and save the changes.
You can adjust the polling interval by modifying the hipposched:cronExpression property.
Email Notification Settings
Email subjects and bodies can include placeholders that the connector replaces with job-specific information:
| Placeholder | Description |
|---|---|
| %%FILENAME%% | The relevant filename |
| %%LINK%% | Link to the relevant file on the FTP server |
| %%DATE%% | Timestamp of the event |
| %%USER%% | The requesting user |
Extension with Additional Fields
To add custom fields to the translation request dialog, specify the extension class on the configuration node:
extensions.plugin.class=com.bloomreach.cms.translations.connector.ftp.FTPExtension
The default extension class adds comments and deadline date fields, which are automatically included in the document XML. To implement custom fields, create a class based on the example in com.bloomreach.cms.translations.connector.ftp and update the property to reference your implementation.
To include custom field values in the document XML, extend com.bloomreach.cms.translations.connector.ftp.FTPTranslationConnector and override the following method:
protected void addExtraAttributes(final TranslationJob job, final TranslationJobItem jobItem)
All custom fields are treated as strings. Update the className property in your configuration to reference the overridden connector class.