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:

  1. Request counts/cost
  2. Obtain operation id
  3. Loop:
    1. Check status of operation
    2. Wait a few seconds until counts/cost complete.
  4. 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:

{ 
	"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

 

 

Copyright Wordbee - Buzzin' Outside the Box since 2008