Edit template - Running custom scripts at the middle of a project (Midscripts)
Experts only: Don't proceed if you're not familiar with scripts, programs, services, and users in Windows. If you don't have this experience, you need to call an expert, possibly an IT specialist.
At various points of a project, you can run your own programs that manipulate documents, or do other things. This happens as part of automated actions, and not before a document is imported, or after a document is exported.
Because these programs run between import and export, they are also called midscripts.
Can't do this without templates: You can do this in projects created from project templates only.
When you use it to manipulate documents, midscripts work like this:
- Something changes in the project. For example, the translator delivers a document. You want to make a change to the document before the next user - Reviewer 1 maybe - gets it. Maybe you need to replace a term with another, or unlock segments but only if they contain a specific term. There are endless possibilities.
- memoQ exports the document in the MQXLIFF format. This is a standard bilingual XML document.
- The program runs through the document. This program must take an MQXLIFF file as input, and it must produce an MQXLIFF file. The format must not be changed - memoQ is quite sensitive to that.
- memoQ updates the document in the project from the modified MQXLIFF file.
On the other hand, you may want to check or change something in the project, and not make a change inside a document. Switch to a different translation memory, or change a deadline - the list goes on. This is also possible:
- Something changes in the project.
- memoQ doesn't export any documents, but:
- memoQ runs a program that connects to the memoQ server through the Web Service API, and makes a change to the project or related resources
Makes sense in online projects: Although you can set up local projects with midscripts, this makes sense mostly in online projects, on memoQ servers. This topic shows how you can set up a midscript in an online project.
Set up your server first: If you need to run midscripts in online projects, you must set up your server first. This is described in the What can you do? section, later in this topic.
You need to write or acquire the program: memoQ doesn't come with programs that make the necessary changes to documents or to the project. Either you need to write these, or acquire them from a programmer. Or, you can turn to memoQ Professional Services, who will write it for you for a fee.
To prepare or touch up text documents, use the built-in Find and replace tool: To learn more, see the topic about the Find and replace script.
How to get here
Open Resource console. Choose Project templates.
To set up a template for online projects: Use an online template for this. Choose your memoQ server at the top of Resource console. Click Select.
Select the project template that you want to set up with automated actions that use custom scripts. Right-click the selection, and click Edit.
In the Edit project template window, choose Automated actions. On the Project automation tab, choose an event (a trigger) in the project. On the right, click the + sign. In the Select actions you want to add to the trigger window, select Execute custom code. Click Add.
The Specify custom code details window appears.
To change an existing automated action: If the Execute custom code action is already there in the Project automation tab, select it under Actions added to the selected trigger. Click the Settings icon next to it. The Specify custom code details window appears.
What can you do?
The scripts that run in your projects are programs. On a server, not everyone is allowed to run programs. Normally, memoQ server isn't allowed to run programs - for security reasons.
Before you run scripts in an online project, you need to allow memoQ server to run them.
Must be an administrator and must be an expert: You can't follow the steps below if you're not an administrator of the memoQ server computer, and you're not completely aware of the things you're about to do.
You don't do this from memoQ - set aside the memoQ window until you finish these steps.
- Through Remote Desktop, sign in to the memoQ server computer as an administrator. (That is, you must be an administrator of the entire machine, not just the memoQ server program.)
- Open Control Panel. Choose Programs and Features. Select memoQ server. Click Change. The memoQ server deployment tool opens.
- In the memoQ server section of the Deployment program, click Advanced, and then choose Configure custom code execution. The Custom code execution window appears.
- As a rule, choose Virtual service account here. Click Next. Never use a built-in account. You may use a specific account under the This account radio button. But you must be very careful to set it up, so that it isn't used for anything else.
- The deployment tool checks if the settings are valid. You must be an administrator of the server computer, and the selected account must be able to log on as a service. If you see two green tick marks in the window, click Next. If there is at least one error, click Back, and change the settings.
- The deployment tool sets up memoQ server for running the scripts and programs. This may take a while. When you see the Settings have been saved successfully message, click Finish.
- A warning appears that you must restart memoQ server. Click OK.
- In the deployment tool, click Stop memoQ server. When the Start memoQ server link appears, click Start memoQ server.
- When the deployment tool reports that memoQ server is running again, close it.
Your programs may need files that cannot be stored in the project templates. These files can be stored in the project template - but if they are in the project template, you can't change or fix them while a project is running. In that case, you would need to create the whole project again.
Because of this, you need to place some - in fact, most - program files outside the project template.
- When you set up custom code execution, the service user will get the Log on locally system permission. It will have a Documents folder. For example, if the user is called _svc_mqsinternal, the folder will be under C:\Users\_svc_mqsinternal\Documents. Create a folder called 'Scripting' in this folder, and place your program files there.
With this setup, if you need to replace a program file - because of a bugfix, for example -, you can do it in this folder. Your existing project will use the updated program file immediately.
Before you begin, you need at least two files:
- a main program file that does the actual job in your project. It may need other files, too. You need to copy them with the main program file;
- a batch file that contains one single command: to start the main program file. This is the file that you put inside your project template.
- Copy the main program file to the server, in the Documents folder of the service user. (Example: c:\Users\_svc_mqsinternal\Documents\Scripting.) memoQ server will run the main program file under the name of the service user.
- Check the batch file, so that it points to the correct folder on the server. For example, the batch file can contain this command:
c:\Users\_svc_mqsinternal\Documents\Scripting\C_Converter.exe %1 %2 %3 %4 %5 %6 %7 %8 %9
This batch file starts the program called C_Converter.exe, and passes up to nine arguments to it. The program is supposed to be in the C:\Users\_svc_mqsinternal\Documents\Scripting folder, on the server. This is not a folder on your computer.
In fact, you can copy this command into your own batch file - just replace the name of the .exe file if you're calling a different program. And check the folder, of course.
- Return to memoQ, connect to the same server, and edit the project template. The project template should be on the same server.
Online project, online template: Never use a local project to create online projects - make sure the template is on the same server.
- Choose Automated actions. On the Project automation tab, choose the event when you want to run the program. Next to the Actions added to the selected trigger list, click the + sign. In the Select actions you want to add to the trigger window, select Execute custom code. Click Add. The Specify custom code details window appears.
If the Execute custom code action is already there: Select it under Actions added to the selected trigger. Click the Settings icon next to it. The Specify custom code details window appears.
- Under Select the files needed to run your code, click Add files. Find and open the batch file that starts the main program. Don't add the main program here.
To replace a script file or a batch file: Select the file in the Select the files needed to run your code list. Click Delete. Then add the new file by clicking Add files.
- In the Select the files needed to run your code list, select the batch file. Click Set as command.
- Set up the command next. The Command name is the same as the name of the batch file. In the Command line arguments, type the arguments that the main program needs. If you're modifying project documents, you must add {InputFilePath} and {OutputFilePath}. In this case, the program must take an MQXLIFF document for an input file, and it must produce an MQXLIFF document for an output file.
The document-related placeholders make sense only if the event that starts this program concerns a document.
The program may require other command line arguments, too.
You can use other placeholders, too, so your program can work with the identifier of the project, as well as with the source and target languages. The program would mostly use these to find or to create folders so that different files for different purposes are kept apart.
To insert a placeholder: Click Insert placeholders, and choose the placeholder from the menu.
- InputFilePath: The full path and the name of the project document. You don't need to know what this path is - it's produced automatically by memoQ.
- OutputFilePath: The full path and the name of the transformed project document that gets updated in the project. You don't need to know what this path is - it's produced automatically by memoQ.
- AssignedTo: The name of the user (translator, reviewer 1, or reviewer 2) who gets the document to work on.
- Deadline: The deadline of the current workflow step (translation, review 1, or review 2) of the document.
- FinalDeadline: The deadline of the last workflow step of the document. This is the delivery deadline.
- WorkflowStatus: The workflow step (translation, review 1, review 2) and status (Not started, In progress, Finished) of the document.
- SrcLangIso2: Two-letter code of the source language of the project.
- SrcLangIso3: Three-letter code of the source language of the project.
- TrgLangListIso2: List of two-letter codes of the target languages of the project.
- TrgLangListIso3: List of three-letter codes of the target languages of the project.
- ProjectGuid: The globally uniqiue identifier of the project. It's a long number, which is never repeated.
- DocumentGuid: The globally unique identifier of the current document.
- Choose how much you want to wait for the program to run. Because it's part of an ongoing project, it must not take forever. Set the number of seconds memoQ server must wait before it ends the program (if it doesn't end on its own accord).
- If you need to process and change documents in the program, check the Export documents as MQXLIFF for script to process check box. This saves the document or documents before the program is run.
- If you need to modify the exported document, and update the project from it: check the Update documents in project from script's output check box. After the program is run, memoQ updates the project from the modified MQXLIFF file.
Program must make minor changes only: The program must strictly keep the format of the MQXLIFF document. Plus, avoid adding or deleting contents excessively - because then memoQ may fail to update the document.
- Finally, you can test your script. Click Test run my program. The Custom code execution - test run window appears.
- If the program works on a document: Export a document in MQXLIFF. Then type or paste the document path and name in the text box, or click Browse to find the document on your computer. Click OK.
memoQ uploads the script and the sample document to the server, but not your external program. The memoQ attempts to run the script on the server.
- When the test ends, the Test result message box appears, with an exit code. If the program was run successfully, the exit code is 0. If there is an error, the code is usually -1, or a different number.
- After you finish, click OK.
memoQ automatically runs the midscript when its event happens.
For example, if memoQ needs to change the deadline of the review if the translator delivers too late, the program runs when a translator delivers a document.
To use the scripts, create a project from the project template, and carry out the workflow to the point where the script is set to run. Then check if the change you expect actually happens.
You could include your script - the entire program - in the project template. memoQ would extract them in a folder, and run them. This works well - until you discover that there is a problem with the script.
You may fix this in the project template. But when you change something in the template - replace the script, for example -, that will affect new projects only. If you have a problem in an existing project, that won't change when you replace the script in the template. If the entire program is in the template, you need to create the project again if you need to change the script.
The best practice is that you never put the main program logic in the project template. Instead, copy your program to a folder on the computer where the project will be - it's your own computer if it's a local project, and your memoQ server if it's an online project.
Then, add a simple batch file to the project template. The batch file has just one task: run the main program, and pass on the arguments (such as the file names) from the actual memoQ project. For an example, see Set up a script for an online project, earlier in this topic.
If there's a problem with the script while the project is going on, this is what you do:
- Fix the main program - or get it fixed by the developer you work with.
- Replace the program in the separate folder.
- In the project, get back to the stage where the script would run.
- Get to the event that sets off the midscript. memoQ runs the same batch file, and it calls the main program - which changed in the meantime, so the program will run differently this time.
You don't have to change the project template. What's more important, you don't have to re-create the project - simply get back to the workflow stage where the script should run.
When you finish
To save the project template, and return to Resource console: Click OK.
Possible next step: After you finish working on the template, close the Resource console, and create a project from the template.
To continue working on the project template: choose another category, and fine-tune other settings.
To return to Resource console, and not save the project template: Click Cancel.