Developer

Page tree

If the API changes in an incompatible manner this is listed explicitly in the "important release notes" section of each releases changelog.

Provides access to the tasks stored in translate5.

URL:

/editor/task/[ID]

Available Methods:

GET / POST / PUT / DELETE

Specialities:

Since on a POST request the import data is given, the POST must be transmitted as “multipart/form-data”.

POST creates the Task, and start the import process. Unless autoStartImport is set to 0, then the task is uploaded but the import starts on calling or a separate URL is called. See below.

By setting the userState to the value “edit” the task is registered as to be edited by the current user.

Setting it back to the userState “open” means that the the task is open again for all users.

forced DELETE: if the ACL right "taskForceDelete" (resource "backend") is set to a role, users of that role can use the "force" switch to delete tasks locked by other users.
This makes sense in some environments where translate5 task administration is done via API only. A DELETE call would then look like: DELETE /editor/task/123?force=1

Advanced filtering

In addition to the default filtering possibilities by task model fields, there is additional option for advanced "workflow" filtering. For example you can filter for all tasks where user "X" is assigned

as reviewer. The additional filter parameter should look like this:

filter: [{"operator":"in","value":["{4484fa0b-4c94-4294-8d30-7dd697760d2b}"],"property":"userName"},{"operator":"in","value":["reviewer"],"property":"workflowUserRole"}]

This will filter for all tasks where the user with guid {4484fa0b-4c94-4294-8d30-7dd697760d2b} is assigned as reviewer.

The other available fields for the advanced workflow filters:

  • userName:  filters for assigned user in the workflow by user guid
  • userState: filters for assigned workflow state (role)
  • assignmentDate: filter for user job assignment date
  • finishedDate: filter for user job finish date
  • deadlineDate: filter for job deadline date

Special Task Import URLs

URL to start the import of the uploaded task:

/editor/task/[ID]/import →   [ID] is the id of the task, the taskGuid is currently not supported

Reimport a before exported task from an excel file:

editor/task/[ID]/excelreimport

Special Task Export URLs

URL to get the edited task data in a ZIP container:

/editor/task/export/id/[ID]

The export ZIP may contain the translated content directly, or for legacy reasons in a folder named as the taskGuid of the task.

This can be controlled by setting runtimeOptions.editor.export.taskguiddirectory or explicitly on each export call by setting a GET parameter "taskguiddirectory" with 0 or 1.
example: /editor/task/export/id/[ID]?taskguiddirectory=0 to explicitly remove the guid, or 1 to have it in the folder.

As above, but with diff tags:

/editor/task/export/id/[ID]/diff/1

Export the translated file only from the ZIP container:/editor/task/export/id/[ID]?format=filetranslation

MQM Statistic Export:

/editor/qmstatistics/index/taskGuid/[GUID]?type=[TYPE]

Export Task as Excel:/editor/task/[ID]/excelexport/
Export of editing history of a task

/editor/task/export/id/[ID]?format=excelhistory

Exports task editing history (always the lattes version of a segment) for each workflow step. More info about it: TRANSLATE-2869 - Getting issue details... STATUS

Where [ID] is the value of the mysql-id field, [GUID] the mysql-taskGuid and [TYPE] a valid field type of the task (field type refers to the column the MQM has been used on in the editor).

Other Special Task URLs

URL to trigger specific workflow actions to that task via API.

POST /editor/task/[ID]/workflow →   [ID] is the id of the task, the taskGuid is currently not supported

Parameter: "trigger" which contains a string, for example: "notifyAllUsersAboutTaskAssociation"

The workflow action must be configured in the LEK_workflow_action table.

See also Workflow Actions and examples.

Show task import progress:

editor/task/importprogress?taskGuid=[GUID]

Resource layout example
{
    "progress": {
        "progress": 99.58, // total import progress in percent
        "workersDone": 10, // total task workers with state done
        "workersTotal": 11, // total queued task workers
        "taskGuid":  [GUID] // taskGuid
        "workerRunning": "editor_Plugins_SegmentStatistics_WriteStatisticsWorker"
    }
}




Task Resource Layout

Name

Type

Info

id

int

GET only

taskGuid

string

GET only

entityVersion

integer

GET only, set by server

modifieddateGET only, contains the last modification timestamp of the task entity

taskNr

string


foreignIdstringoptional, is a 120 character long freetext field, not shown in the GUI. Can be used in installations where translate5 is used embedded only, to track the taskId of the management system for example.

taskName

string


descriptionstringoptional, max 500 character long textual description of the project / task
foreignNamestringoptional, is a 255 character long, see foreignId.

sourceLang

string/integer

POST accepts: integers (internal ID), rfc5646 string values, LCIDs (must be prefixed with "lcid-" for example lcid-1031 ), GET returns always the internally used language Id

targetLang

string/integer/array

POST accepts: integers (internal ID), rfc5646 string values, LCIDs (must be prefixed with "lcid-" for example lcid-1031 ), GET returns always the internally used language Id. If array of target languages is provided, for each target language, separate task (project task) will be created

relaisLang

string/integer

POST accepts: integers (internal ID), rfc5646 string values, LCIDs (must be prefixed with "lcid-" for example lcid-1031 ), GET returns always the internally used language Id

locked

date

GET only

lockingUser

string

GET only

lockingUsername

string

GET only. When requesting all tasks (GET /editor/task) this field is only delivered if a filter or limit parameter is provided.

lockedInternalSessionUniqIdstringGET only

state

string

POST: can be omitted, is set automatically to "import"
PUT: "end" to end a task, "open" to reopen an ended task.

GET: returns the current state of the task
import  → task is still importing data
error → task import produced and error and task is not usable
end → task is ended by a user
open → task is usable by users
unconfirmed → task is unconfirmed, can not be edited, must be confirmed (status open) first

workflow

string

The name of the workflow used in the task

workflowStepintegerThe workflow step nr
workflowStepNamestringThe name of the current workflow step

pmGuid

string


pmName

string


wordCount

integer


targetDeliveryDate  (deprecated)

date

The date field is deprecated. Use LEK_taskUserAssoc deadlineDate instead.

referenceFiles

boolean

GET only

terminologie

boolean

GET only

orderdate

datetime


enddatedatetimeGET only, contains the datetime when task is set to status end (calculated)

edit100PercentMatch

boolean

POST only, defines whether 100% matches found should be editable or locked

lockLocked

boolean

POST only, only for SDLXLIFF files: Segments explicitly locked in imported file are also locked in translate5
emptyTargetsbooleanGET only, flag if task has contained only empty targets on import time and is therefore a translation job, or otherwise contained some translations and is a review job
importAppVersionstringGET only, contains the translate5 version used at import time
customerIdintegerThe client for the task (= id from table LEK_customer)

enableSourceEditing

boolean

POST only

autoStartImportboolean

POST only, optional, defaults to true. set it to false to prevent an automatic start of the import - for additional configuration, preprocessing before the real import.

qmSubEnabled

boolean

GET only

qmSubFlags

auto

GET only

qmSubSeverities

auto

GET only

userState

string

As defined by the workflow.

userRole

string

GET only

userStep

string

GET only

segmentFieldsautoGET only, list with associated segment fields.
When requesting all tasks (GET /editor/task) this field is only delivered if a filter or limit parameter is provided.
userPrefsautoGET only, list with associated default user preferences.
When requesting all tasks (GET /editor/task) this field is only delivered if a filter or limit parameter is provided.

users

auto

GET only, list with associated users

taskassocsautoWith Language Resources: GET only, list with associated Language Resources.
When requesting all tasks (GET /editor/task) this field is only delivered if a filter or limit parameter is provided.

userCount

integer

GET only

fileCountinteger

GET only

When requesting all tasks (GET /editor/task) this field is only delivered if a filter or limit parameter is provided.

exportRunningstringGET only

defaultSegmentLayout

boolean

GET only

When requesting all tasks (GET /editor/task) this field is only delivered if a filter or limit parameter is provided.

importUpload

HTTP Upload

POST only

usageModestring

Currently 'competitive' or 'cooperative' or 'simultaneous'.

competitive: only the first user accepting the task may work on it.
cooperative: All associated users may work on the task, but always one user at a time.
simultaneous: All associated users may work on the same task at the same time.

Note: if no value is provided on task creation, the value will be evaluated from this config runtimeOptions.import.initialTaskUsageMode

This config is overridable on client level

segmentFinishCountintegerGET only, calculated(reviewed/translated depends on the workflow step) number of segments in the current workflow
segmentCountintegerGET only, total number of segments in the current task
workflowProgressSummarystring

GET only; Workflow step progress for each workflow step. 

Response layout:

[
  {workflowStep: translation, status: finished, progress: 100},
  {workflowStep: proofreading, status: running, progress: 33},
  {workflowStep: translatorCheck, status: open, progress: 0}
]

visualReview

file

POST only, Plugin Visual Review only.

Adds a (single) file as the source for the visual review. If the import zip already contains a "visualReview" folder with review sources this file will be added to the ones provided in the zip. Filetype can be "pdf" or "html"

visualReviewHtmlarray

POST only, Plugin Visual Review only.

An URL to a website that will be taken as a source(more info about the source linking here: Visual - WYSIWYG: Upload rules for layout sources) for the visual review.The URL will be downloaded with all linked ressources. Overwrites any sources provided via "visualReview" or in the import package.

The provided URL has to be fully qualified like "https://www.translate5.net/en/translate5-open-source-translation-system/" and has to be accessible without login etc.

mappingType

string

POST only, Plugin Visual Review only.

Defines, if the visual review is mapped to the source or target of the segments. Defaults to "source". ( source | target )

taskTypestring

GET only. Possible values:

  • default - default task type
  • projectTask - task type when the task is part of project task collection
  • project - root task for all project tasks
  • instanttranslate-pre-translate - task type for translated files via instant-translate, is introduced via instant-translate plugin.

See below section task types for details.

projectIdinteger

GET only, project id of the task. For taskType default,project and instanttranslate-pre-translate this will have the same value as the id. For tasks with taskType projectTask, this will have the value of the root task(task with taskType project) of the project task collection

importProgressintegerGET only (the task must be in state import or matchanalysis), Current import(or running matchanalysis worker) total progress. 

Import push callback

To prevent excessive polling of the task state while import a HTTP callback can be configured. This is needed since task imports may need up to hours, depending on task size and used features (like term tagging).

To configure the callback search in the configuration for "runtimeOptions.import.callbackUrl" and set the value to your URL:

  • If a URL is set, this URL is called with HTTP POST after task import, where the task itself is contained as JSON (only the meta data, not the uploaded files).
  • The callback is also called in case of import errors, so your callback handler must evaluate the tasks state field given in json. A state of "open" (or in other words not "error") means a successful import of that task.
  • If the callback is not returning a HTTP 200 status, translate5 will add a warning into the application log on each call of the callback.
Example JSON which is send as raw data to the configured callback endpoint 
{
    "id": "2636",
    "entityVersion": "47",
    "modified": "2023-11-07 14:15:01",
    "taskGuid": "{8cdb06ec-840a-46e8-ad0a-5b44ff7d6197}",
    "taskNr": "",
    "foreignId": "",
    "taskName": "Translate5 Demo Text EN - en \/ sq",
    "foreignName": "",
    "sourceLang": "5",
    "targetLang": "274",
    "relaisLang": "0",
    "locked": null,
    "lockingUser": null,
    "state": "open",
    "workflow": "default",
    "workflowStep": "1",
    "workflowStepName": "no workflow",
    "pmGuid": "{e6828cdf-2ee0-4a25-af0a-92e6f060e9eb}",
    "pmName": "Manager, Project (manager)",
    "wordCount": "92",
    "userCount": "0",
    "referenceFiles": "0",
    "terminologie": "0",
    "orderdate": "2023-10-31 00:00:00",
    "enddate": null,
    "enableSourceEditing": "0",
    "edit100PercentMatch": "0",
    "lockLocked": "1",
    "emptyTargets": "1",
    "importAppVersion": "development",
    "customerId": "1",
    "usageMode": "simultaneous",
    "segmentCount": "24",
    "segmentFinishCount": "0",
    "taskType": "projectTask",
    "projectId": "2565",
    "diffExportUsable": "0",
    "reimportable": "1",
    "description": "",
    "created": "2023-11-07 14:14:49"
}


The callback is called also in the case of an import error!

In seldom cases the import is crashing in a way no callback can be send (server reboot for example). In that case such a task is set to state error after 48 hours, which then triggers the callback finally. The 48 hours can be configured too: runtimeOptions.import.timeout

Task types

A task can be of a specific type. The types defines the visibility and how the task is threatened in the application. For example the projects are also tasks, but with taskType project.

The task type is always calculated / set in the application automatically and must not be set from outside.

Available task types:

  • default - default task type, used for legacy tasks before introducing the project features, and for projects containing only one target language, in other words where project = task.
  • projectTask - task type when the task is part of project task collection, for each target language one projectTask is created
  • project - root task for all project tasks, listed in the project overview. Is not editable directly, only the corresponding projectTasks are editable.
  • instanttranslate-pre-translate - task type for translated files via instant-translate, is introduced via instant-translate plugin. Tasks of this type are only used internally for translating an uploaded file via instanttranslation, they are not listed in ordinary translate5 task and project listing.












  • No labels

4 Comments

  1. shenghao chen

    Could you give an example for getting translated files in zip (export package) using API? I've tried to call /editor/task/export/id/[ID]/ but failed to get the package.

    Thank you

    1. Thomas Lauria

      Hi Shenghao, I added an example on the page Basic Usage Examples. I hope that helps! Try it without the trailing "/" in the URL.

  2. Stef Velzel

    For a project I am working on, I am programatically uploading tasks to a Translate5 server. Afer this, I am trying to programmatically poll each known task and determine whether the task is done, i.e. whether translation data is complete and ready to be exported and used elsewhere. I do this to automate the translation process within a CMS. However I am unsure how to do this. So far I have found 3 options within the task resource layout:

    • Check the `state` field, check if it is equal to `end`.
    • Compare the `segmentFinishCount` and `segmentCount` fields, if the former is smaller than the latter, there are still segments to be translated. However if I understand it correctly this might report a completed task even though it might still need reviewing? Plus I don't see those fields documented here, I found them as I was writing the software that connects to a Translate5 server.
    • Check if the `progress` field of each element in the `workflowProgressSummary` field is equal to 100. I believe this would ensure all steps are finished, including reviewing. However I cannot seem to trigger all workflow steps to be finished.

    My hunch is that I should simply use the `state` field. This because then the end user of the Translate5 server manually has to close a task for it to be 'completed'. Is this correct?

    1. Thomas Lauria

      Hi Stef,
      this depends on your use case. To check for the status "end" would be ok, if your PMs (and only PMs may set tasks to end by default) end the task after the work is done.

      But since you talk to the API, I assume it is no option to wait until a PM has set the task to "end".

      I think the field "workflowStepName" is the one you are looking for, since it should contain the value "workflowEnded" if the last users has finished their work.
      So in a workflow with translators only, the workflowStepName should switch to "workflowEnded" if they finish the task, and the same if you have added translated and reviewers. Here the workflow is ended if the reviewers have finished their work.