API - Sandbox - Counts and cost

This method calculates word counts and cost for all content that was sent to the sandbox (including .beebox instructions).

This method is asynchronous and the steps are:

Request counts/cost
Obtain operation id
Loop:
1. Check status of operation
2. Wait a few seconds until counts/cost complete.
Done.

URL

(PUT) /api/files/operations/sandbox/count?token=&getcost=true

Please note that this is an HTTP PUT and not a GET action. The binary data of the file must be included in the message body.

Please note that multi-part attachments are not supported.

PARAMETERS

Parameters are:

token

The session token obtained when connecting.

getcost

“true”: Get word counts and cost

“false”: Get word count only without cost

RESULTS

This method returns a JSON object with property “opid” and which identifies the asynchronous operation:

CODE

{ 
	"opid": "78hdh7878"
}

You now need to poll the Beebox until the count/cost details are available. This may take from a few seconds to a few minutes depending on text volume.

Repeatedly call the following method in a loop and wait a few seconds in between calls:

AWAIT FINAL RESULTS

(GET) /api/async/operation/status?token=&opid=

Parameters are:

token

The session token obtained when connecting.

opid

The asynchronous operation id.

RESULTS

The method returns a JSON object with these properties. There may be more properties but we only list the relevant ones:

running	Boolean. If true then the operation is still running. Continue to poll until this property is false.
failed	Upon termination this boolean indicates if the operation failed.
cancelled	Upon termination this Boolean indicates if the operation had been canceled by the Beebox administrator. Currently not implemented.
workprogress	A user friendly text with the current operation work progress.
results	The result of the operation. See table below for details. This json object is set when the operation completed with success only: "running" is false and neither "failed" or "canceled" are true.
log	Provides an incremental log of all operations the system is carrying out. Mainly for the eyes of developers. Useful for debugging.
failedmessage	End user friendly message if "failed" is true.
opid	The ID of the current asynchronous operation.

Upon successful completion of the operation ("running" = false, "canceled" = false and "failed" = false), the "results" property contains the following json object:

errors	A json array with user friendly error messages if problems were found in one or more files. For example: A file is corrupt and could not be processed. The cost could not be calculated. The Beebox is not configured for human translation and is not linked to a translation vendor.
reception	Json object with statistical information on Sandbox files. Total number of segments and words, Total files per file type, Total files added per each calendar day, etc. You do not need this information.
failedFiles	A json array with any files that could not be processed because the file is corrupt. If this list is not empty, you need to show this to the end user. All counts contained in other properties exclude counts of failed files. The array contains one record per failed file: "folder": Disregard. Always empty. "file": File relative path "locale": The source language code "errors": Json array with error messages
languages	A json array with details for each target language. Whereas the "reception" property focuses on the source text counts, this property provides full information per target language on: Amount of contents that could be pre-translated Amount of contents that still needs to be translated Contents to be translated but which is already in translation at the vendor - no need to send again Cost of contents that still needs to be translated Each array element is a Json object. The details are described in the table below.

Each item of the "languages" property is a json object, see description below.

locale	Target language code
localeName	Language name
jobsummary	Can be disregarded for connector development. Details described in the online API documentation.
jobcontents	Can be disregarded for connector development. Details described in the online API documentation.
cost	Set only if cost calculation was requested. Null if cost calculation was requested but could not be obtained from the vendor (e.g. if no human translation vendor is linked to the Beebox project). This json object has these properties: “costed”: Boolean indicating if cost calculation was requested and the cost could be calculated. This requires that the TMS is configured (process, etc.), the vendor could be contacted, etc. “problems”: Json array of error messages. If cost could not be calculated you will find user friendly error descriptions here “currency”: Currency of quotation as 3-letter ISO code “decimalPlaces”: Positions after decimal point for rounding purposes “vatRate”: Applicable VAT rate. Numeric value. “vatRateText”: VAT rate ready to render, such as “20,00%” “totalExVat”: Total amount excluding VAT “totalVat”: Total monetary amount of VAT “totalIncVat”: Total amount including VAT “applicableMinimumAmount”: If there is a minimum amount defined by the vendor, then this is the corresponding value. "applicableGroupMinimumAmounts": An additional applicable minimum amount for the specific job language couple. The smaller one of these two minima will apply. “documents”: Json array of documents. Usually you will see here a single document. However, a vendor can decide to split a job into multiple pieces. Each piece would then show up here as an individual record. "name": Name assigned by the vendor to the document. You can disregard this. “segments”, “words”, “chars”: Word counts for this document “costExVAT”: Amount ex Vat "costDetails": A json array with cost details lines. There may be lines for different work items (translation, revision, etc.), different discounts that apply, minimum amounts that apply, etc. Similar to the details lines of an invoice. The sum of all lines is the cost grand total for the document. Each line has these properties: "amount": Sub total ex Vat "description": Details line text

REMARKS

The method returns a vast amount of information and you likely do not need all of it.

You may want to start here:

First make sure that you wait for the operation to complete: "running" = false
While you wait for completion in a loop, you may want to display work progress contained in "workprogress". In between calls, pause for a few seconds.
Check if the operation terminated successfully: Verify "canceled" = false and "failed" = false. If the operation failed, show "failedmessage" to the user.
Look for "errors". If there is anything in there, something went wrong: A file is invalid, A file does not contain any contents, Cost could not be calculated, etc. Generally, the volumetric or cost details may be compromised in such cases. Also then look for "failedfiles" to see if any file is corrupt. If a file is corrupt you need to inform the user because cost information does not cover such files and the grand totals thus may not be reliable.
Show total contents volume: "reception.total.segments", "reception.total.words" and "reception.total.files".
Loop through all "languages" array elements. You will find at least one element per target language. Per item "languages[{index}]", display:
- The total segments and words that require translation: languages[index].segmentsBatch, languages[index].wordsBatch
- Get total cost for language: languages[index].cost.totalExVat, totalIncVat, totalVat as total excluding vat, total including vat and vat amount.
- Make sure data is costed and no errors occurred: languages[index].costed (boolean) and languages[index].errors. You may request cost details but these can only be obtained if the vendor provides such information. The "errors" property will tell if vendor did not enable costing.
- Sum all individual cost amounts to obtain a grand total