Target audience: Developers

Preconditions: JavaScript knowledge







Smart Connectors allow for quick predefined project creation, however, the functionality may be very flexible in hands of users with advanced knowledge of JavaScript. If you work with a client who regularly orders very similar translation projects, you can set up the Smart Connector for them. Such Smart Connector saves Project Manager's time. A well-prepared Smart Connector, creates a project automatically when it detects files at the specified time in the monitored directory. When the project is finished, the target file is uploaded to the directory that can be specified in the Smart Connector's settings, however, the directory needs to be provided in the Smart Connector's robot code. The client can download it from there if they are given access to that location. In this article you can find all information necessary to set up a Smart Connector for your client  in the configuration of XTRF Platform. Keep in mind that each Smart Connector requires different mapped location and each client needs to have separate Smart Connector assigned to avoid any issues.

External File Sharing Service

Your client does not need to configure anything in terms of using external file sharing service integrated with Smart Connectors. They can choose one of the following options to deliver the source files to their Project Manager:

 When the files are uploaded to the mapped folder and the Smart Connector is correctly configured, the project can be created.

Technical Configuration

In this section you can learn how different kinds of Smart Connectors can be configured. Depending on how well you can handle JavaScript, you can configure more or less advanced Smart Connectors. However, you do not need any knowledge of JavaScript to set up basic Smart Connector.

Each Smart Connector needs to be configured in XTRF Platform. You can do that using a wizard available in the Home Portal. In the picture below you can see the configuration of the Smart Connector prepared in the configuration wizard just before saving. The code snippets provided further in the article can be typed in the Connector Definition code field. To enable code field you only need to select the Robot Code radio button. Bear in mind that the Name and Client fields need to be filled before saving the Smart Connector or switching to other tabs.


Basic Smart Connector 

Basic Smart Connector can be set up in the configuration wizard, therefore you do not need to know how to use JavaScript. The configuration wizard allows for setting up only the most simple Smart Connector. This kind of Smart Connector is prepared to create projects in fixed language configuration as well as service and specialization. It means that it can be applied for the client who orders multiple projects in very similar configurations.

function robot(input) {
	return {
		project: {
			sourceLanguage: utils.repository.languages.bySymbol('EN'),
			targetLanguages: [ utils.repository.languages.bySymbol('DE') ],
			specialization: utils.repository.specializations.byName('General'),
			files: input.files

The project created by the Smart Connector example will involve translation from English to German and the set workflow will be appropriate for the Translation service. The specialization is set to General.

The code snippet provided above was created using the configuration wizard. Similar codes are created every time the configuration wizard is used.


Advanced Smart Connector

The advanced Smart Connector allows you to set more parameters for the project, however, some knowledge of JavaScript is required.

The Smart Connector example provided below creates a project named User Manual Translation. The source language is German and the target languages are Polish, PL, and English, EN. The service involved in the project is set to Translation Premium , since its retrieved from the XTRF's database, the workflow applied in the project will be as specified in the Premium Translation service. The specialization of the translation is set to the system's default and the category is Automatic-Project. Current date is set as the start date for the project and the deadline is set to a week after the start date. The directory of the translated files is set to  this/is/my/relative/path on an FTP server. Notes that will be displayed in the project's Instructions tab are as follows:

The code snippet needs to be entered in the Connector Definition field in the Smart Connector configuration. In the Create Smart Connector display select the Robot Code radio button to enable the code field.

The Smart Connector in the example has fixed parameters, it means that projects created by this Smart Connector will have the same configurations. You can use it for the client who orders multiple translation projects of the same type.

function robot(input) {
	var now = new Date().getTime();
	return {
		project: {
			name: 'User Manual Translation',
			sourceLanguage: utils.repository.languages.bySymbol('DE'),
			targetLanguages: [ utils.repository.languages.bySymbol('PL'), utils.repository.languages.bySymbol('EN') ],
			service:'Translation Premium'),
			specialization: utils.repository.specializations.getDefault(),
			categories: [ utils.repository.categories.byName("Automatic-Project") ],
			notes: "Important notes", instructionsFromCustomer: "Important instructions from client",
			internalInstructions: "Important internal instructions",
			startDate: new Date(now),
			deadline: new Date(now + 7*24*60*60*1000),
			files: input.files,
			delivery: {
				url: 'ftp://localhost:21/this/is/my/relative/path'



Smart Connector with a Descriptor

Both simple and advanced Smart Connectors provided as examples above contain some fixed settings. Therefore, every time a project is created using one of those Smart Connectors, the language combinations or any other parameters specified in the code of those Smart Connectors will be applied. A Smart Connector with a descriptor can be used for multiple projects with completely different parameters, which can be specified in the descriptor file. A descriptor file with project specifications needs to be prepared and uploaded with the file that needs to be translated for every new project created in this type of Smart Connector. An appropriate Smart Connector needs to be prepared for interpreting of the descriptor file. 

The code snippet should be entered in the Connector Definition section. In the Create Smart Connector display select the Robot Code radio button to enable the code field.

The Smart Connector in the example provided below is prepared to retrieve the information from the descriptor file. Name of the project, source and target languages, service and notes will be retrieved from the descriptor.

The descriptor needs to be saved as a .json file and added together with the files that are to be the subject of the project.


function robot(input) {
	var descriptor;
	var projectFiles = [];
	var now = new Date().getTime();{
		if (file.relativeDirWithName == 'descriptor.json') {
			descriptor = file.loadAsJSON();
		} else {
	if ( ! descriptor) {
		throw 'no descriptor.json found in input files';
	return {
		project: {
			sourceLanguage: utils.repository.languages.bySymbol(descriptor.sourceLanguage),
			targetLanguages: {
				return utils.repository.languages.bySymbol(targetLanguage);
			specialization: utils.repository.specializations.getDefault(),
			notes: descriptor.notes,
			startDate: new Date(now),
			deadline: new Date(now + 7*24*60*60*1000),
			files: projectFiles


	"name": "Translation Project",
	"sourceLanguage": "DE",
	"targetLanguages": ["PL", "EN", "FR"],
	"service": "Translation Plus",
	"notes": "Important notes"


You can see an example of a descriptor file. The data provided for the Smart Connector by the descriptor are as follows:

  • name
  • source language
  • target languages
  • service

  • notes

The Smart Connector retrieves the information from the  descriptor.json  file and creates project based on that information. The new project will be named Translation Project, the source language will be German, DE, and there will be three translation tasks: into Polish, PL, English, EN, and French, FR. The project's workflow will be appropriate for the Translation Plus service uploaded to the XTRF's database and in the project's Instructions tab the information Important notes will be displayed in the Notes section.

Keep in mind that the data provided in the descriptor file need to be compatible with the data uploaded to your XTRF Patform.


Available Parameters

In the table below you can find the list of all parameters available for creating an advanced Smart Connector and the descriptor file. Parameters necessary to create the project are marked as such in their description, all the parameters that are not marked as necessary are optional and are not required to create a project.

While configuring Robot Code, the system may provide you with suggestions for possible operations. To get suggestions press CTRL and SPACE on your keyboard while typing in the code field. A list with possible operations appears.


ParameterDescription of the Parameter
name This parameter sets the name for the project created by the Smart Connector. If the parameter is not added to the Smart Connector's code, the name of the project will be empty.

This parameter specifies the source language in the project. The source language needs to be retrieved from the repository, therefore, the appropriate language needs to be uploaded to the XTRF's database. This parameter is necessary to create a project.

sourceLanguage: Repository.languages.bySymbol('EN-US')



This parameter specifies the target languages in the project. The target languages need to be retrieved from the repository, therefore, appropriate languages need to be uploaded to the XTRF's database. This parameter is necessary to create a project.

targetLanguages: [repository.languages.bySymbol('DE'), repository.languages.bySymbol('FR')]



This parameter specifies what kind of service is provided in the project. The Smart Connector applies the workflow to the project according to this parameter. The services and their corresponding workflows need to be retrieved from the repository, it means that both services and workflows need to be configured and uploaded to the XTRF's database. This parameter is necessary to create the project.

service:'premium translation')



This parameter specifies the specialization of the translation project. The specialization needs to be retrieved from the repository, therefore, the appropriate specialization needs to be uploaded to the XTRF's database.

specialization: repository.specializations.getDefault()



This parameter specifies the category of the project. The category needs to be retrieved from the repository, therefore, the appropriate categories need to be uploaded to the XTRF's database.  

categories: [repository.categories.byName("automatic-project")]


notes This parameter allows to add notes to the project. You can add the content of the note in the quotation marks in this parameter. The notes will be displayed in the project's Instructions tab in the Notes section.
instructionsFromCustomer This parameter allows to add instructions from the client. The content of the instructions can be added in the quotation marks in this parameter. The instructions will be displayed in the project's Instructions tab in the Special Instructions from Client section.
internalInstructions This parameter allows to add special internal instructions to the project. The content of the instructions can be added in the quotation marks in this parameter. The instructions will be displayed in the project's Instructions tab in the Internal Special Instructions section.

You can add the start date of the project using this parameter. If you provide a specific date, the date will be fixed for this Smart Connector. It means that every time this Smart Connector is used to create different projects, the start date will be always the same as specified in this parameter. You can also set the current date as the start date or add a period of time in milliseconds to the current date, if you wish the start date to be in future, for example 7*24*60*60*1000 for seven days.

var now = new Date() .getTime();
startDate: new Date(now + 7*24*60*60*1000)


deadline You can specify the deadline for the project. You can either provide a specific date, which will then be fixed for this Smart Connector, or you can set the current date or the start date and add a period of time in milliseconds, if you want the deadline to be somewhere in future. For example you can add 7*24*60*60*1000 milliseconds to add 7 days.
files This parameter specifies the list of the source files for the project.

The parameter specifies values of your custom fields for the project. Use key or label to identify custom field.

customFields: {
	myTextField: 'text',
	myCheckbox: true,
	mySelection: 'option1',
	myNumber: 2.56,
	myMultipleSelection: ['option1','option2'],
	myDate: new Date (2000000000)



You can specify the directory path for the translated files. The translated files will be uploaded to this directory when the project is finished.

delivery: {
	url: 'ftp://localhost:21/this/is/my/relative/path'



Available Features

Managing Files

Once a file is uploaded to the folder mapped or an e-mail with attached files is sent to the address specified in the Scan for Input Files section and the Smart Connector is started, the Smart Connector creates a project. The files are available for the vendors assigned to the project as if the project was created manually. Depending on the configuration of the Smart Connector, once the project has been started, the Smart Connector can create a folder with the project's ID number in the directory specified for the processed files and can store the input files there or remove them. If there are any problems with the uploaded file, which would prevent creating a project, the Smart Connector can create a subfolder with the exact date in the name in the directory specified for the In Case of Errors, Store Files in section or it can remove them.

You need to provide the entire paths in the directories of specific sections.

You can add output path for the target files in the Robot Code of the Smart Connector. If the project includes more than one translation task, the target files are stored in folders with a proper language symbol as a folder name.

Multiple files can be added at the same time as a .ZIP archive. The Smart Connector recognizes the . ZIP  archive, creates a subdirectory with the same name as the . ZIP archive and extracts the files in the subdirectory.

If the name of the file or .ZIP archive contains characters unsupported by Microsoft Windows operating system, such as: * , : , ? , < , > , or | , the Smart Connector replaces those characters with _

Once the project has started, additional files cannot be uploaded to the project using Smart Connector functionality.

E-mail Notifications

You can select when and to whom the e-mail notifications are sent.

The notifications can be sent when:


You can specify when the Smart Connector attempts to create a project. The project can be started:


Testing Smart Connectors Configuration

To make sure that the Smart Connector will work properly and the folder in Base Directory is mapped correctly, you can perform the following steps:

  1. Sign in to the Home Portal of XTRF Platform.
  2. Click the  icon.
  3. In the accordion configuration menu select the Integration and then select Smart Connectors.
  4. Click the Add button in the upper side of the Smart Connectors list.
  5. Prepare a Smart Connector:Upload a file to the folder specified in Input section.
    1. Provide the name  for the Smart Connector in the Name field.
    2. Select the client to whom the Smart Connector is dedicated. The system provides the suggestions as you start typing the name of your client.
    3. Select the client's Price List.
    4. In the Files Aggregation drop-down menu select the way the Smart Connector will handle the files uploaded to the mapped folder.
    5. Provide the directory of the folder or the access data for the e-mail which will be scanned for input files.
    6. Select what happens with processed files and provide directory for them if necessary.
    7. Select what happens with the files if any error occurs and provide directory if necessary.
    8. Select the Person Responsible for the Smart Connector
    9. Select the Wizard radio button in the Connector Definition field if you want to prepare a simple Smart Connector or Robot Code radio button if you want to prepare an advanced Smart Connector.
    10. Select the specifications of the project from the drop down menus if you selected Wizard radio button or provide the piece of JavaScript code if you selected Robot  Code radio button.
    11. Click the Save button.
  6. Click the Test button. Test Smart Connector pop-up window containing logs appear. If the directory in Input section is mapped correctly, the file is processed and a pop-up window informing about the potential project appears. In the pop-up window you can choose to create a project or close the pop-up window.



Documentation JIRA issue:  

Release version: 4.9, 4.13