resources/files/details

Provides additional and detailed information for a file.

Information for a subsequent preview or deliverable creation.
Erroneous segments (with source/target document only)

URL

(POST) /resources/files/details

PARAMETERS

The parameters are a JSON object included in the request body:

scope	The scope object. Note that if you use a document set or global search scope, you will receive an "available" = false result. In fact these scopes do not support files.	Mandatory
did	The document id. This must be a document within the scope.	Mandatory
locale	Language of the file.	Mandatory

folder	Folder ID of the file. If not specified the call refers to the source or target document corresponding to "did" and "locale".	Optional
name	Name the file. If not specified the call refers to the source or target document corresponding to "did" and "locale".	Optional

	Applicable for source/target files only:
segmentDetails	Boolean, default is false. If true the system scans the texts of the document for errors, missing translations and last change date.	Optional

RESULTS

A JSON with these properties:

preview	An object with details about previewing the file. See next table.	object
file	An object providing general information on the file: Does it exist physically? Date and size?	object
segments	If the file is the source/target document and parameter segmentDetails is true, then this node is included. See table below.	object
hl	Information on highlighting options available when constructing a translated file (look for highlighting). See table below.	object?

Preview node

Properties are:

canPreview	Boolean. True if a web preview is possible.	bool

	Preview activation
needActivate	Boolean. If "canPreview" is false then this property indicates if previewing can be activated.	bool
canActivate	If the preview requires activation: Indicates if the user has the right to activate. If so, typically show URL to go to activation page.	bool

	Preview parameter options
previewer	The code of the previewer component. You can disregard this property.	string
domain	The file type (domain). You will pass this to the preview method.	string
encoding	A JSON object with these properties: canEdit: Boolean. True if the user shall be able to optionally select an encoding. Only true with text based file formats. Properties if canEdit is true: value: Last encoding used for this document & locale. Null if none. valueOriginal: The encoding of the original/source file. options: If "canEdit" is true you will find the list of all selectable encodings with properties "v" (code) and "t" (title).	object
baseUrl	Used with html files only. Permits to inject a base URL into the preview for proper rendering of images, css, etc. canEdit: Boolean. True if the file is a web page. Properties if canEdit is true: value: A suggested base url or null if none suggested. The list of available encodings is included in the result of resources/files/get	object

File node

Provides information on the file and whether it exists physically or not. Properties are:

canSet	Whether user can replace or delete the file. This depends on the user's access rights. Note that the source document can never be changed.	bool
name	The name of the file	string
exists	True if the file exists physically. A deliverable that was never saved to the project is an example when this boolean is false.	bool
date	Date of file. Null if file does not exist.	datetime?
size	Size of file in bytes. Null if the file does not exist.	long?
encoding	The encoding if the document is a text file (xml, json...). For example "utf-8". In some cases this information may not be available. For binary formats such as Word or InDesign, the encoding is null.	string?

Segments node

Only included if "segmentDetails" parameter was set to true. Provides information on the actual texts in the language.

For example you can compare "segments.lastchange" ad "file.date" to know if the physical file is outdated and needs to be rebuilt from the newer text changes.

total	Total segments.	int
missing	Total number of untranslated segments (in the specified locale). Note: Does not count empty segments that were set to green status.	int
error	Total number of segments in error status (in the specified locale)	int
lastchange	Most recent change of a text. Can only be null if the document has 0 segments (cannot occur normally).	datetime?

Highlighting (hl) node

Describes the colors used when highlighting is enabled when calling resources/files/new

This node is null if the document format does not support the highlighting features.

Properties are:

editors

An array of objects, each with:

v: The last editor to highlight
f: A text with the format / color used in the highlight. Can be shown to end users to clarify in what color errors will be shown.
c: A text with the hexadecimal value of the highlight color that's going to be user in the highlight.

object[]

errors

A string containing the format / color used for the highlighting. Can be shown to end users to clarify in what color errors will be shown.

string

EXAMPLE

Here we get details for a target document with

{
  "preview": {
    "canPreview": true,
    "needActivate": false,
    "canActivate": false,
    "previewer": "CodeMirror",
    "domain": "PLAINTEXT",
    "baseurl": {
      "canEdit": false,
      "value": null
    },
    "encoding": {
      "canEdit": true,
      "value": "utf-8",
      "options": [
        {
          "v": "UTF-8",
          "t": "UTF-8"
        },
        {
          "v": "UTF-16",
          "t": "UTF-16"
        }
        {
          "v": "WINDOWS-1258",
          "t": "WINDOWS-1258"
        }
      ]
    }
  },
  "file": {
    "canSet": true,
    "name": "html.txt",
    "exists": true,
    "date": "2017-02-05T22:57:24.7403048Z",
    "size": 502
  },
  "segments": {
    "total": 8,
    "lastchange": "2017-02-06T07:08:46.422Z",
    "missing": 0,
    "errors": 0
  },
  "hl": null
}

EXAMPLE HIGHLIGHTING

Some formats (Microsoft Word) include options for highlighting errors etc. in color. In that case the hl node is filled in:

{
	...


	"hl": {
		"editors": [{
			"v": 7,
			"f": "cyan"
		},
		{
			"v": 6,
			"f": "green"
		},
		{
			"v": 9,
			"f": "magenta"
		},
		{
			"v": 2,
			"f": "yellow"
		},
		{
			"v": 3,
			"f": "red"
		},
		{
			"v": 5,
			"f": "grey"
		}],
		"errors": "red"
	}


	...
}