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: "dtchange": { "hours": 48, "days": 1 } Find changes of October (UTC): "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. "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. "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:

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

{
    "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.
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. "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.~~ { "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:

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

"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
				}]
			}
		}
	},
    ...