Page Comparison

To add one or more files to an existing Codyt project.

Depending Based on the project configurationsettings, the operation will get initiates translation workflows ready and going: Save by saving files to the project, mark marking them online, conducting pre-translate translation and word count, create and creating and assign assigning jobs.

URL

Code Block
(PUTPOST) /api/projects/{pid}/workflows/new

PARAMETERS

The URL parameters are:

pid

The project’s ID.

int, Mandatory

The request BODY contains a JSON object with these properties:

files

An array with containing one or more records, each describing a file to be uploaded. The These records include the a unique token referencing an the uploaded a file. ExampleFor 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”“title” (name).

Example:

Code Block
"jobsCfs": { fields": [ { "title": "Activity", "value": "Fulltime" }, { "id": 4, "value": "A-221" } ] }

object[], Optional

maxFilesInJob

This parameter is applicable only to Standard projects, with a default value of 100. The maximum is 1000.

It is designed for scenarios involving the submission of a large number of files. The system will group the files into jobs, ensuring that no single job contains more than the specified number of files. If the total exceeds this limit, multiple jobs and workflows will be created automatically.

Note: For Codyt jobs, this parameter is not applicable, as Codyt always creates one workflow per file.

int, 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

...

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.

If you need to upload multiple files to get multiple tokens, use the multi-upload: media/upload/multi

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

attachments

Optional array of files to attach to the document. This can be screenshots, reference material or more. Up to 10 files can be attached. See details below.

You can also upload attachments at a later time using Manage attachments

object[]?, Optional

The optional attachments array contains one record per attachment. 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.

If you need to upload multiple files to get multiple tokens, use the multi-upload: media/upload/multi

string, Mandatory

name

The attachment file name, with or without folders.

string, Mandatory

locale

The language code of the attachment. Must be a source or a target language of the present request.

string, Mandatory

RESULTS

This method is an asynchronous operation: Your request is queued and will execute as soon as possible.

Info

Asynchronous operations - How to:

The API method immediately returns a JSON object that includes the ID of the operation(look for the requestId property).

The result is the updated invoice document.

...

However, the operation has not yet been executed. You will need to await the operation’s termination to obtain results.

Waiting can be done in two ways: Polling: Regularly check the operation’s status. Webhook Call: Wait for a callback using the callbackurl parameter in your request. We strongly recommend the latter approach. For more details, please refer to the documentation: Asynchronous operations

The JSON results, obtained with polling or with a callback, include the operation status as well as any results specific to the API method. Below is an example of successful termination:

Code Block

 {
    "trm": {
        "requestid": 13432,
        "isbatch": false,
        "status": "Finished",
        "statusText": "Finished!"
    },
    "custom": {
        "files": [
            {
                "name": "file-003.htm",
                "format": {
                    "formatId": 7952,
                    "formatName": "Default",
                    "formatDomain": "HTML"
                },
                "exists": false,
                "success": true,
                "error": null,
                "did": 288981,
                "segments": 87,
                "attachments": 0
            }
        ],
        "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:

did: The document ID. You will need this number for all subsequent workflow operations related to this document and its workflows (in the different target languages).
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.
segments: The number of segments in the file.
attachments: Total number of attachments that could be saved. If a token is invalid, the attachment is disregarded.

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

Effective error handling involves careful consideration and effort. Let’s break it down into three levels of errors:

Invalid payload

Immediate

If you submit an invalid payload, your API call will immediately be rejected with the error payload typical for the API. Here is an example when submitting an invalid source locale:

Code Block
{ "error": { "operation": null, "date": "2024-04-03T15:57:01.2110105Z", "title": "Invalid parameter 'src': Invalid source locale" }, "reason": "Invalid parameter 'src': Invalid source locale" }

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:

Code Block
{ "trm": { "requestid": 559, "isbatch": false, "status": "Failed", "statusText": "Operation failed!", "statusInfo": "The parameter xy was not properly supplied" } }

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 file contains 0 segments. Please do not submit empty files, Wordbee does not like them.

Versions Compared

Old Version 5

New Version Current

Key

URL

PARAMETERS

RESULTS

ERROR HANDLING