Review

Review Status

review status

A clip has a review status. A user with the REVIEW_STATUS_EDIT permission can change the review status of a clip (see Permissions). The possible values are APPROVED or NOT_APPROVED by default, but can be customized via the reviewStatusConfig production setting.

See Production Settings to learn how to load production settings. This is an example of the setting with one additional NEEDS_WORK status:

{
	reviewStatusConfig: {
		possibleValues: [
			{ id: “NOT_APPROVED”, label: “Not Approved” },
			{ id: “APPROVED”, label: “Approved” },
			{ id: “NEEDS_WORK”, label: “Needs Work” },
		]
	}
}

The review status of a clip is stored as the reviewStatus field on the MediaObjectAnnotation.

One can set it to a new value using a JSON PATCH:

PATCH /api/production/:productionId/an/:moaId

[{
	op: ‘add’,
	path: ‘/reviewStatus’,
	value: ‘NEEDS_WORK’
}]

Learn more about the JSON PATCH concept here. Using PATCH instead of PUT ensures only this particular field is changed and we don’t accidentally overwrite other fields.

Changing the review status is only allowed by users who have the REVIEW_STATUS_EDIT workspace right (see Permissions).

Datamodel of a comment

Users can add comments to clips. A comment is stored as an Annotation with objectType=”ClipAnnotation” and funnel=”ReviewComment”.

Note: objectType and funnel can be seen as a way of defining sub types of an Annotation, more info here.

Details about the particular fields and structure of the ClipAnnotation can be found on this page. It explains mentions, tags, spatial position on the video frame and comment threads. Another worthwhile read is this section, explaining start / end to set the timing of the annotation. For a ReviewComment, the annotation points to a single frame, so end will be equal to start + 1.

Creating a comment

To create a comment, use the call POST /api/production/:productionId/mo/:moId/clip. See this documentation, which contains an example on how to create a ClipAnnotation with funnel ReviewComment.

The following fields are important:

  • description - the text in the comment. Note that it can contain inline tags and mentions.

  • mentionIds - an array of userIds which have been mentioned

  • tags - an array of tag strings

  • funnel - should be “ReviewComment”

  • spatial - contains the location on the video frame of the ‘dot’

  • uiLocation - contains the location on the video frame of the comment box

  • relatedToId - can contain the id of another comment on which this is a reply

  • start - the frame of the media the comment is about

  • end - will always be start + 1 for ReviewComment

Creating a comment is only allowed by users who have the REVIEW_EDIT workspace right. See Permissions.

Edit a comment

Use a JSON patch call PATCH /api/production/:productionId/an/:anId.

Learn more about the JSON PATCH concept here.

Editing a comment should only be allowed by users who have the REVIEW_EDIT or REVIEW_EDIT_ALL workspace right. In addition, users who have the REVIEW_EDIT right can only edit comments created by themselves (creatorId of the annotation matches the user id). See Permissions.

Remove a comment

Use a DELETE http call to /api/production/:productionId/an/bulk

with json body

{
  actions: [{
  	action: ‘DELETE’,
  	ids: [12345]
  }]
}

The call will remove the annotation with id 12345. Note that multiple ids can be passed at once if needed.

Removing a comment should only be allowed by users who have the REVIEW_EDIT or REVIEW_EDIT_ALL workspace right. In addition, users who have the REVIEW_EDIT right can only remove comments created by themselves (creatorId of the annotation matches the user id). In other words, if you can edit a comment, you can remove it. If you can’t edit a comment, you can’t remove it.

Listing Review Comments

review comment listing

Get comments of a clip

The same GET /api/production/:productionId/an/search endpoint as mentioned here can be used to fetch comments of a clip. The following filters will probably be used:

Filter name Description

fq=mediaObjectId:1234

Only return annotations of this particular clip

fq=funnel:ReviewComment

Only return comments

Comment threads

The Flow UI has limited support for comment threads. We support a comment, and replies on that comment, but nothing deeper than that (no replies on replies). Each comment has a relatedToId field, which has the value of the annotation it is a reply to (or empty). See here.

To visualize comments grouped by thread, one can group at the client side on the relatedToId field. If additional filtering or search features are necessary which can’t be implemented on the client, an alternative is to use the grouping feature on the threadGroupId_s_nm_d field.