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
bsidMinOptional for pagination. Return only segments with a sequential ID equal or above. The sequential number starts at 1 (first segment in container).int?, Optional
bsidMaxOptional for pagination. Return only segments with a sequential ID equal or below.int?, Optional




VERSIONS
majorOptional. Query segments for this major version.string?, Optional
minorOptional. Query segments for this minor version. You must specify the major version as well.string?, Optional




CONTENT
localesOptional. List of locales to export. If not set or null then content in all languages is included.string[]?, Optional
includeCustomFieldsOptional, default is false. Export segment and text level custom fields with the results.bool?, Optional
includeLabelsOptional, default is false. Export text labels with the results.bool?, Optional
includeCommentsOptional, 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:

typeFlex export descriptor. Disregard.string
versionFlex export version. Disregard.string
majorMajor version of content. Null if no versioning used.string?
minorMinor version of content. Null if no versioning used.string?
didFlex document ID.int
dsidFlex document resource ID. Can be used with other API methods that require this ID.int
cfsConfigIf includeCustomFields is true: List of all custom fields with their "id" and their title "t".object[]?
lblsConfigIf includeLabels is true: List of all custom fields with their "id" and their title "t".object[]?
segmentsArray of segments. See below.object[]


Each element in segments has these properties:

keySegment keystring
componentThe component ID if it was assigned to the segment with a push.
formatThe content format such as "plain" or "html_1".string
dtThe last date of change of any property of the segment (texts, status, ...)datetime
bsidSequential number assigned for display in the translation editor. This number may change with push requests.int
cfsSegment 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[]
chminMinimum character length for translations. Only included in JSON if a minimum is set.int?
chmaxMaximum character length for translations. Only included in JSON if a maximum is set.int?


Each element in texts has these properties:

vThe 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
bkThe bookmark in Wordbee Translator. 0 = none, 1 = blue, 2 = redint
edLast editor. See Last Editor (Enumeration)int
dtDate of modification of text.datetime
cfsCustom fields (null if there are none). Each array element has properties id (custom field ID) and v (custom field value)object[]?
lblsLabels (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.