To add one or more files to an existing Codyt project.
Depending on the project configuration, the operation will get translation workflows ready and going: Save files to project, mark online, pre-translate and word count, create and assign jobsReturns workflow information and status for a document and target language.
Note: Each target languages has its own workflow, independent from each other.
URL
| Code Block |
|---|
(PUTGET) /api/projects/{pid}/workflows/new/{did}/status/{trg} |
PARAMETERS
The URL parameters are:
pid | The project’s project ID. | int, Mandatory |
The request BODY contains a JSON object with these properties:
...
files
...
An array with one or more records, each describing a file to be uploaded. The records include the token referencing an uploaded a file. Example:
| Code Block |
|---|
[
{
"token": "77ca3562-ff01f5882dd1",
"name": "myfolder/myfile.docx"
}
] |
See detailed description further down.
...
object[], Mandatory
...
src
...
The source language code. This must be a valid project language.
...
string, Mandatory
...
trgs
...
The languages to translate to. These must be valid project languages. Example:
| Code Block |
|---|
"trgs": [ "es-ES", "fr-FR" ] |
...
string[], Mandatory
...
deadline
...
Optional deadline for completion of work. Deadlines are assigned to the jobs that are created with the workflow. Example:
| Code Block |
|---|
"deadline": "2024-04-03T06:00:00Z" |
...
datetime?, Optional
...
workflow
...
Optional, selects "Default" if not specified. Fine-tune how workflows are created:
Default : Create jobs according to the project’s Workflow & Suppliers configuration. Recommended value.
None : Do not create any jobs.
...
string, Optional
...
allowUpdates
...
Optional. Default is true.
true: You are allowed to replace existing files with new versions. In such cases, the file is replaced, a new set of jobs will be created and the new jobs will be assigned to the same workers as before.
false: Any attempt to replace an existing file will return an error.
...
bool?, Optional
...
jobsCfs
...
Optional custom fields to assign to all jobs created for a file’s workflow. See Custom Field Collection Record for details. Note: You reference a CF by either its “id” or its “name”.
Example:
| Code Block |
|---|
"fields": [
{ "title": "Activity", "value": "Fulltime" },
{ "id": 4, "value": "A-221" }
] |
...
object[], Optional
...
callbackurl
callback
...
Specify a URL which will be called upon success or failure of operation. This makes polling for operation status unnecessary. See Callbacks (with asynchronous operations)
...
Optional
The files array contains one record per file. Properties are:
...
token
...
Use API media/upload to upload a file. It returns the token to be included here. Note: The upload of your file or files must be done prior to calling the present method.
...
string, Mandatory
...
name
...
The file name, with or without folders. The file will be stored with this name & folders in the project. Some valid filenames:
| Code Block |
|---|
my-file.docx
marketing/section1/presentation.ppt
marketing\\section1\\presentation.ppt
strings.product.json |
Note: When using “\” make sure to escape with “\\”. This is not necessary when using the forward “/” as folder separator.
...
string, Mandatory
...
Optional parameters
...
formatId
...
Optional document format configuration to be used for extracting content from the file. See Document formats to enumerate all existing file formats.
Normally, you do not need to override the defaults: By default, the system selects the filter from the project’s File Filter configuration.
...
int?, Optional
...
disableMt
...
Optional, default is false. If you explicitly want to prevent machine translation when preparing the file, set this property to true. Machine translation is enabled or disabled in the project’s word count profile.
...
bool, Optional
...
reference
...
Optional sender ID for the document. For example, this can hold an identifier you assign to the document outside of Wordbee.
...
string?, Optional
...
comments
...
Optional comments added to the document and shown in the translation editor.
...
string?, Optional
RESULTS
This method is an asynchronous operation: Your request is queued and executes as soon as possible.
| Info |
|---|
Asynchronous operations - How to: |
The JSON results, obtained with polling or with a callback, includes the operation status as well as any results specific to the API method. Below an example for successful termination:
...
did | The document ID | int, Mandatory |
trg | The target language code | string, Mandatory |
RESULTS
The JSON result includes the workflow details. Example:
| Code Block |
|---|
{
"trmbranch": {
"requestid": 13432,
"isbatch": false,
"fr",
"status": "Finished"4,
"statusTextstatusTitle": "Finished!"
}Work delivered",
"customstatusDate": {
"files": [
{
"name": "file-003.htm",
"2024-04-03T06:32:37.683Z",
"formatopenJobs": {
"formatId": 7952,
0,
"formatNamesteps": "Default",
2,
"formatDomainfile": "HTML"
},
{
"exists": false,
"success": true,
"error": null,
"did": 288981,
"segments": 87
}
],
"request": {
...
}
}
} |
Check the status of trm/status. In case of success it should say “Finished”.
The node custom/files lists each submitted file with these properties:
name: The name of the document in the project, including any folders.
format: The document format configuration used to extract content from the file. It shows the document format ID (see settings/documentformats/configs/list) , the format configuration name and the type of document (HTML, JSON, XML…).
exists: Indicates if the file did already exist and was replaced with this new version. If you disallowed file version updates (see
allowUpdates) then the next property will indicate an error.error: Null if success. Otherwise shows the specific error why the file could not be processed. This may have many reasons. For example the file might be invalid.
did: The document ID. You will need this number for subsequent workflow operations such as to download the translation.
segments: The number of segments in the file.
The node custom/request contains your initial payload, including some extra properties.
files: The list of files you submitted
src: The source locale
trgs: List of target locales.
projectId: The project ID.
resourceId: The project memory ID.
etc.
ERROR HANDLING
Correct and complete error handling will require some efforts. There are three levels of errors:
...
Invalid payload
Immediate
...
, |
...
|
...
|
...
"date": "2024- |
...
03- |
...
27T11: |
...
08: |
...
33. |
...
7731701Z", |
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
"name": " |
...
Resolution: You likely need to fix your payload.
...
Operation failed
Delayed
If your payload is valid, your request is now queued. If the operation then fails with a fatal error, you get the async error payload. For example:
...
file-002.htm", " |
...
size": |
...
96, " |
...
encoding": " |
...
UTF-8" } } |
Resolution: Depending on the error message. You should not see such issues often. If the error details are unclear you may need to reach out to Wordbee support.
...
Operation ok but file failed
Delayed
The operation may have executed just fine but a submitted file (or several) could not be processed. The file specific error will be listed in the results, look for success and error:
| Code Block |
|---|
"custom": {
"files": [
{
"name": "file-003.htm",
"format": {
"formatId": 7952,
"formatName": "Default Gemini",
"formatDomain": "HTML"
},
"exists": false,
"success": false,
"error": "Failed to process file. No segments.",
"did": null,
"segments": null
}
] |
Resolution: Depending on the message. You likely face one of these issues:
...
The file is invalid and failed to process. Think of a badly formatted XML file. Please check your files test manually in Wordbee Translator.
...
The file name is invalid, such as too long or contains invalid characters. Please fix file naming conventions.
...
The properties are:
branch | A project target locale. The branch locale is the language of the ultimate deliverable. | string |
status | The workflow status. See Workflow Status (Enumeration)
| int, Mandatory |
statusTitle | ||
statusDate | ||
openJobs | ||
steps | ||
file |