resources/timeline/segment

Provides current and historical information for a specific segment:

Comments attached to segment
Change history (revisions)

URL

(POST) /resources/timeline/segment

PARAMETERS

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

scope	The scope object. The segment must be within the scope.	Mandatory
sid	The segment id.	Mandatory
knownPersons	Optional array of person/user ids for which we do not need name and company, since we already have this information. Try to provide the person ids if you already have details as this will speed up performance.	Optional
calcdiff	Specifies how text differences between succeeding revisions are calculated (see the "mk" property in the resulting Segment Change (Object). String values are: None: Do not calculate differences Forward: The latest text has no markers. Each text shows differences with the preceeding (earlier one). Backward: Each text shows differences with the next older one. The most recent text gets markers. The last one not. If not specified, the Forward algorithm is used by default.	Optional

RESULTS

A JSON with these properties:

comments	An array of all comments of the segment, sorted by descending date. It includes comments in all the scope languages to which the user has access. See Comment (Object) for details.	object[]
history	An array of all text and flag changes of the segment, sorted by descending date. These are notably changes of the texts by different workers over time. See Segment Change (Object) for details.	object[]
persons	An object containing the persons referred to by comments or revisions. Note: Excludes persons contained in parameter knownpersons. Excludes persons that the user cannot see. There is an access right to prevent a user from viewing user and company names. The object has keys where the key is the person id. "persons": { "_7": { "id": 7, "nm": "Stephan", "cid": 1, "cnm": "Tradubee" }, "_3": { "id": 3, "nm": "Thierry", "cid": 1, "cnm": "Freelancebee" } nm: Full name of person id: Id of person cnm: Company of person cid: Company id	object
locales	A list of all locales available for this segment and which are within the scope. You can use these in a comments/revisions language filter.	string[]
rights	A few access rights that are specifically useful when working with the results: canSendEmail: When a user adds/edits a comment, this boolean tells if the user can notify the comment by email or not. canAdd: Tells if the user can add a new comment in one of the locales. Note: When using the APIs to add/edit/delete comments, you may obtain a not authorized information even when the edit, canAdd or canSendEmail properties are true. The reason for this is that further detailed access rights check are done upon those advanced operations.	object

ACCESS RIGHTS

When working with the timeline of a segment, you should always read out these properties:

comments.[].edit: Tells if a comment can be edited or deleted.
rights.canAdd: Tells if a new comment can be added to the segment.
rights.canSendEmail: Tells if a newly added comment can be notified by email to people involved with this segment.

EXAMPLE

Here we get details for a target document with

{
  "comments": [
    {
      "cty": "s",
      "cmid": "s823850-122",
      "sid": 823850,
      "did": 1908,
      "txt": "The French original text is flawed. It cannot be translated!",
      "tsk": "TR",
      "dt": "2017-04-07T14:22:38.080706Z",
      "cat": 0,
      "fpd": false,
      "fro": false,
      "loc": "en",
      "uid": null,
      "edit": true
    },
    {
      "cty": "s",
      "cmid": "s823850-115",
      "sid": 823850,
      "did": 1908,
      "txt": "I corrected the translation",
      "tsk": null,
      "dt": "2017-04-07T07:44:42.6006221Z",
      "cat": 3,
      "fpd": false,
      "fro": false,
      "loc": "en",
      "uid": null,
      "edit": true
    }
  ],
  "history": [
		{
			"ty": "text",
			"current": true,
			"val": "Corrected translation",
			"tsk": null,
			"ed": 1,
			"dt": "2017-04-07T07:39:11.2253404Z",
			"uid": null,
			"loc": "en"
		},
		{
			"ty": "flags",
			"current": true,
			"tsk": null,
			"dt": "2017-02-14T09:42:50.0220044Z",
			"uid": 7,
			"loc": "en",
			"st": 1,
			"bk": 0
		}
  ],
  "rights": {
    "canSendEmail": true,
    "canAdd": true
  },
  "locales": [
    "fr",
    "en"
  ],
  "persons": {
    "_7": {
      "id": 7,
      "nm": "Bohmig Stephan",
      "cid": 1,
      "cnm": "Pons"
    },
    "_3": {
      "id": 3,
      "nm": "Hund Thierry",
      "cid": 1,
      "cnm": "Pons"
    }
  }
}