Skip to main content

apps/wbflex/documents/{id}/contents/pull

Download all or selected segments from a flex document.

URL

(POST) /api/apps/wbflex/documents/{id}/contents/pull

PARAMETERS

URL parameters are:

id

Specify either a document ID (such as 1000) or a job ID (such as c300).

string, Mandatory

The body must contain a JSON object with these properties:


FILTERS


dtchange

Optional filter on last change of segments. Changes may be anything from texts in languages, meta information, comments etc.

See Date filter (Filter) for details.

The following finds texts changed the last 3 days:

CODE
"dtchange": { "hours": 48, "days": 1 }

Find changes of October (UTC):

CODE
"dtchange": { "min": "2018-10-1T00:00:00Z", "max": "2018-11-1T00:00:00Z" }

object?, Optional

keys

Optional list of segment keys to pull.

Note: You can request up to 500 keys with one pull.

Note: This filter is case insensitive.

string[]?, Optional

key

Optional filter on keys using a prefix, suffix, infix, wildcard or regex pattern. See String filter (Filter) for details.

Note: This filter is case insensitive.

CODE
"key": { "value": "frontend.", "mode": "Prefix" ]

object?, Optional

components

Optional list of component IDs to pull. See Components / Flex for more information.

Note: You can request up to 500 keys with one pull.

Note: This filter is case sensitive.

CODE
"components": [ "software.frontend", "software.sql" ]

string[]?, Optional

component

Optional filter on keys using a prefix, suffix, infix, wildcard or regex pattern. See String filter (Filter) for details.

Note: This filter is case sensitive.

object?, Optional

segments

Optional list of segment IDs to pull. Please note that you more likely would use the "keys" property to fetching specific segments.

NOTE: You can request up to 500 keys with one pull.

int[]?, Optional

bsidMin

Optional for pagination. Return only segments with a sequential ID equal or above. The sequential number starts at 1 (first segment in container).

int?, Optional

bsidMax

Optional for pagination. Return only segments with a sequential ID equal or below.

int?, Optional





VERSIONS


major

Optional. Query segments for this major version.

string?, Optional

minor

Optional. Query segments for this minor version. You must specify the major version as well.

string?, Optional





CONTENT


locales

Optional. List of locales to export. If not set or null then content in all languages is included.

string[]?, Optional

includeCustomFields

Optional, default is false. Export segment and text level custom fields with the results.

bool?, Optional

includeLabels

Optional, default is false. Export text labels with the results.

bool?, Optional

includeComments

Optional, default is false. Export segment and text level custom fields with the results.

bool?, Optional

excludeTexts

Optional. Permits to specify if a segment's translation shall be included with a segment. A segment may be split into multiple sub-segments in the Wordbee Translation Editor and each such sub-segment may have its own status (None, Ok, Problem). When pulling the segment, the system uses this filter to decide whether a specific translation shall be included or not with the segment.

The available options are:

  • IfAnyProblem : A translation is not included if ANY of the sub-segments have the "Problem" status (red color).

  • IfAllProblem: A translation is not included in the JSON if ALL the sub-segments have the "Problem" status.

  • IfNotAllOk: A translation not included unless ALL the sub-segments have the "Ok" status (green color).

  • None: No filter (same as null or dropping this property)


string?, Optional

excludeTextsProblem

Please now use the more comprehensive "excludeTexts" property instead.

Optional, default is false. If true, then an exported segment does not print any text-elements in status Problem (red color). You can also find this status in the st property on the text-element. The purpose of this property is to reduce the size of the returned JSON by excluding data that apparently has issues still in the translation team and you very likely do not want to import in the first place.

Please note that this does not filter any segments. You still get all segments but texts nodes are not included depending on status. 

bool?, Optional

copySourceToTarget

Optional, default is true. If true, then texts with empty/missing translation are returned with the source text value.

This is done under these conditions:

  • The translation is empty, and

  • The translation status is not set to OK / green (with the green status the translator can make an empty text in the translation explicit).

Set to false to disable this copy-over behavior.

bool?, Optional


CALLBACK URL / WEBHOOK


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


RESULTS

The operation may take more or less time depending on the amount of data to export. Therefore it is implemented as an asynchronous operation.

The API method returns an Asynchronous operation result:

JS
{
  "trm": {
    "requestid":32230,
    "status":"Waiting",
    "statusText":"Waiting..."
  }
}


If the operation is not completed (status = Finished), you need to poll every few seconds until completion with requestid. When finished you obtain a token to download the JSON file:

CODE
{
    "trm": {
        "requestid": 32230,
        "isbatch": false,
        "status": "Finished",
        "statusText": "Finished!"
    },
    "result": { "items": [] },
    "custom": {
        "filetoken": "1104cf62b1934e0f9ae40c43c4af1ae2",
        "segments": 4,
        "texts": 9
    }
}


Get the file: You need to use the call media/get/{token} with token is the custom/filetoken property in the previous result.


JSON FILE FORMAT

The method returns a file. It contains a JSON object with these properties:

type

Flex export descriptor. Disregard.

string

version

Flex export version. Disregard.

string

major

Major version of content. Null if no versioning used.

string?

minor

Minor version of content. Null if no versioning used.

string?

did

Flex document ID.

int

dsid

Flex document resource ID. Can be used with other API methods that require this ID.

int

cfsConfig

If includeCustomFields is true: List of all custom fields with their "id" and their title "t".

object[]?

lblsConfig

If includeLabels is true: List of all custom fields with their "id" and their title "t".

object[]?

segments

Array of segments. See below.

object[]


Each element in segments has these properties:

key

Segment key

string

component

The component ID if it was assigned to the segment with a push.

string?

branch

Optional branch. Use if you save strings for multiple branches (similar to a version control system). The combination of key and branch is unique in a container.

string?

format

The content format such as "plain" or "html_1".

string

dt

The last date of change of any property of the segment (texts, status, ...)

datetime

bsid

Sequential number assigned for display in the translation editor. This number may change with push requests.

int

cfs

Segment level custom fields (null if there are none). Each array element has properties id (custom field ID) and v (custom field value)

object[]?

texts

A dictionary of texts. The key is the locale and the value a text object, see below.

CODE
"texts": { "en": {...}, "fr": {...} }


object[]

chmin

Minimum character length for translations. Only included in JSON if a minimum is set.

int?

chmax

Maximum character length for translations. Only included in JSON if a maximum is set.

int?


Each element in texts has these properties:

v

The text.

string

st

The status in Wordbee Translator. 0 = Neutral (gray color), 1 = OK (green color), 2 = Problem (red color).

IMPORTANT: This is an important information. We strongly recommend to not update your systems with any texts that are in red status. Red status means that the translation team either did not yet work on the text or they found an issue. You should only consider texts in 0 or 1 status, depending on how the translation team is organized. Some teams may instruct translators to explicitly set translation status to "green" in which case you may only want to read those.

int

bk

The bookmark in Wordbee Translator. 0 = none, 1 = blue, 2 = red

int

ed

Last editor. See Last Editor (Enumeration)

int

dt

Date of modification of text.

datetime

cfs

Custom fields (null if there are none). Each array element has properties id (custom field ID) and v (custom field value)

object[]?

lbls

Labels (null if there are none). Each array element has properties id (label ID) and v (selected label value)

object[]?

cms

Comments attached to text. An array of objects with these properties:

  • v: Comment text

  • dt: Date of comment

  • uid: User ID who created comment. Find users with these method: persons/list

  • cat: A numeric category of the comment

object[]?

vc

DEPRECATED - See the "copySourceToTarget" which gives you control if empty translations are replaced or not by the source text.

Used with target languages only. Indicates if the v content is a copy of the original text:

If true then v contains the source text value because

  • the translation is empty (no text filled in from the editor)  and

  • the translation status "st" is other than 1 (OK).

In all other cases the property vc is not output.

CODE
{
   "v": "<p>Hello world</p>",
   "vc": true,
   "st": 2,
   "bk": 0,
   "ed": 0,
   "dt": "2019-10-03T15:11:02.4421331Z"
}



EXAMPLES

Basic results without custom fields, labels and comments:

CODE
{
	"type": "Wordbee Flex File Export",
	"version": "1.0",
	"dsid": 3833,
	"did": 9371,
	"major": null,
	"minor": null,
	"segments": [{
		"key": "1001",
		"dt": "2019-05-22T07:03:50.3871180Z",
		"format": "plain",
		"bsid": 2,
		"texts": {
			"en": {
				"v": "Hello world",
				"st": 0,
				"bk": 0,
				"ed": 0,
				"dt": "2019-05-20T21:43:37.562205Z"
			},
			"de": {
				"v": "Guten Tag",
				"st": 0,
				"bk": 0,
				"ed": 0,
				"dt": "2019-05-20T21:43:37.562205Z"
			}
		}
	},
	{
		"key": "1000",
		"dt": "2019-05-22T07:03:50.3871180Z",
		"format": "plain",
		"bsid": 1,
		"texts": {
			"en": {
				"v": "<p>Hello dear world</p>",
				"st": 0,
				"bk": 0,
				"ed": 0,
				"dt": "2019-05-20T21:43:37.5542057Z"
			},
			"de": {
				"v": "",
				"st": 2,
				"bk": 0,
				"ed": 0,
				"dt": "2019-05-16T12:23:37.8150027Z"
			}
		}
	}]
}


Basic results with custom fields, labels and comments:

CODE
"segments": [{
		"key": "1000",
		"dt": "2019-05-22T07:03:50.3871180Z",
		"format": "plain",
		"bsid": 1,
		"cfs": [{
			"id": 5,
			"v": "kklklklkl"
		}],
		"texts": {
			"en": {
				"v": "Hello world",
				"st": 0,
				"bk": 0,
				"ed": 0,
				"dt": "2019-05-20T21:43:37.562205Z",
				"cfs": [{
					"id": 1,
					"v": "My custom value"
				}],
				"lbls": [{
					"id": 4043,
					"v": 20
				}]
			},
			"de": {
				"v": "",
				"st": 0,
				"bk": 0,
				"ed": 0,
				"dt": "2019-05-20T21:43:37.562205Z",
				"cfs": [],
				"lbls": [],
				"cms": [],
				"cms": [{
					"v": "I have a problem with this translation. Please help.",
					"cat": 0,
					"dt": "2019-05-20T21:42:51.8853791Z",
					"uid": 278
				}]
			}
		}
	},
    ...






JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.