User Comments

Introduction

This section describes the framework for generic commenting where comments can target an object in the system.

The idea is to have general User-level commenting, where data-model-wise the comments are stored under a production or account, and the comment contains a target to identify what it is actually talking about.

At the moment, this is in use for comments and change requests on DeliveryRequest and DeliveryRequestSubmission.

Model

An example of a User Comment is given below:

{
  "objectType": "UserComment",
  "funnel": "Something",
  "accountId": 9, // accountId or productionId should be set
  "productionId": 91,
  "targetObjectType": "DeliveryRequestSubmission",
  "targetIds": ["789"], // points to at least one entity
    // scope within the entity (or entities). Note that only a single subScope is
    // supported, even when multiple entities are references
    // the scope will not be query-able via API, but can be used in application
  "subscopes": [{
    // e.g. some way to target a range of words in a TSA, ...
    // diverse - depends on the targeted object
  }],
  "description": "This is my comment",
  "created": 123456789,
  "creatorId": 3
}

Full technical detail can be found here.

Field Name Description

description

The content of the comment

targetObjectType

The object type of the entity this comment is attached to.

targetIds

The ids of the entities that this comment applies to. The combination of targetIds and targetObjectType uniquely identifies an entity.

funnel

A specification of the application

subscopes

When targeting an entity, subscopes can specify further into the entity to target the comment.

mentions

In the description, users can be mentioned, for example: This is a mention @{12,Gimli}

This field should hold all users mentioned in the description to enable querying by mentionId. It is up to the api user to keep this field up-to-date.

tags

In the description, tags can be used, for example:

this is a #{tag}

This field should hold all tags used in the description. It is up to the api user to keep this field up-to-date.

parentComment

To enable threading and responses to other comments, this field can be used to attach the current comment to another comment.

resolutionStatus

This field can be used to mark comments as being open or resolved.

Targets

A User Comment can target the following entity types:

  • DeliveryRequestSubmission

  • DeliveryRequest

  • Production

  • MediaObject

  • Annotation

  • EditorialObject

  • Workflow

  • WorkflowV2

Actual use in Limecraft Flow UI is limited to targets DeliveryRequestSubmission and DeliveryRequest for now.

Subscopes

When using subscopes, it depends on the targetObjectType what is supported and allowed here.

Field Name Description

withinTargetPointer

A pointer to target a property within the target entity. See below for more information.

An example:

{
  "subscopes": [
    {
    "withinTargetPointer": "/formFieldValues/slots/values/0",
    }
  ]
}

withinTargetPointer

A subscope with withinTargetPointer simply points to a property within the target entity.

The syntax largely follows JSON Pointer, but has some extensions.

A pointer could look like this (pure JSON Pointer syntax):

/attachedAnnotations/3/annotation

/formFieldValues/slots/values/3

However, these pointers contain an array index. One issue with this is that the pointer will point to another object if elements are removed or added before position 3 in the arrays.

To make the pointers more robust, we allow addressing object via their id too:

/attachedAnnotations/:id:1234/annotation

The above example points to the first entry in attachedAnnotations with id 1234.

For form field values, the situation is slightly more complicated, as a form field value does not have an id (and is often not even an object). There, the workaround is using handles. Once handles are defined, they can be pointed to like this:

/formFieldValues/slots/values/:thehandle

API

The Api provides a generic endpoint to create, query and update User Comments.

The Api user must have the USER_COMMENT_EDIT or USER_COMMENT_EDIT_ALL to create and manipulate user comments.

Through this endpoint, most user comments can be created, although, there are some restrictions on the targetObjectType and funnel that can be used.

Reserved are:

targetObjectType funnel Reserved for

DeliveryRequestSubmission

Submit/Reject/Approve/Reopen/Archive

Comments on delivery requests submissions when changing the status of the submission.

Note that ‘Archive’ can be used both in archive / activate actions

DeliveryRequest

Archive/Lock

Note that ‘Archive’ can be used both in archive / activate actions

DeliveryRequestSubmission

PartialReject

See also Partial Reject. Points to a part of the submission using the withinTargetPointer of one or more subscopes.

Query

GET /production/{prId}/user_comment

This call queries for user comments.

Details
Description
Parameters
Path Parameters
Name Description Required Type

prId

✔

Long
Return Type

String

Content Type

  • application/json

Responses
Table 1. http response codes
Code Description Datatype

200

The request was successful.

String

403

The user needs PRODUCTION_VIEW rights.

ForbiddenError

404

The production was not found.

NotFoundError

Example

/api/production/:id/user_comment?fq=targetObjectType:DeliveryRequestSubmission&fq=targetIds:789

Search

GET /production/{prId}/user_comment/search

This call searches for user comments using the solr index.

Details
Description
Parameters
Path Parameters
Name Description Required Type

prId

✔

Long
Return Type

UserCommentSolrDocumentList

Field Name Required Type Description Format

elapsedTime

✘

Long

int64

facetDates

✘

List of FacetField

facetFields

✘

List of IFacetField

facetPivot

✘

Map of object

facetQuery

✘

Map of integer

int32

facetRanges

✘

List of object

fieldStatsInfo

✘

Map of IFieldStatsInfo

groupResponse

✘

GroupResponse

highlighting

✘

Map of map

items

✘

List of Component

mediaObjectProperties

✘

Map of map

numFound

✘

Long

int64

responseHeader

✘

Map of object

results

✘

List of SolrDocument

start

✘

Long

int64

termsResponse

✘

TermsResponse
Content Type

  • application/json

Responses
Table 2. http response codes
Code Description Datatype

200

The request was successful.

UserCommentSolrDocumentList

403

The user needs PRODUCTION_VIEW rights.

ForbiddenError

404

The production was not found.

NotFoundError

Example

/api/production/:id/user_comment/search?fq=targetObjectType:DeliveryRequestSubmission&fq=targetIds:789

Create

POST /production/{prId}/user_comment

This call creates user comments.

Details
Description
Parameters
Path Parameters
Name Description Required Type

prId

✔

Long
Body Parameters
Name Description Required Type

UserCommentRequest

✘

List of UserCommentRequest

UserCommentRequest

Field Name Required Type Description Format

accountId

✘

Long

int64

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

creatorId

✘

Long

The id of the user who created this resource

int64

deleted

✘

Date

date-time

description

✘

String

funnel

✘

String

id

✔

Long

The id of this resource

int64

lastUpdated

✘

Date

The time when this resource was last updated

date-time

mentionIds

✘

Set of long

int64

mentions

✘

Set of User

modifiedBy

✔

String

The request or process responsible for the last update of this resource

objectType

✘

String

The data model type or class name of this resource

parentCommentId

✘

Long

int64

productionId

✘

Long

int64

resolutionStatus

✔

String

Is the submission active, or is it archived?

Enum: Open, In Progress, Resolved, Rejected,

subscopes

✘

List of UserCommentSubscope

tags

✘

List of string

targetIds

✘

Set of string

targetObjectType

✘

String

version

✔

Long

The version of this resource, used for Optimistic Locking

int64
Return Type

String

Content Type

  • application/json

Responses
Table 3. http response codes
Code Description Datatype

200

The request was successful.

String

403

The user needs USER_COMMENT_EDIT or USER_COMMENT_EDIT_ALL rights.

ForbiddenError

404

The production was not found.

NotFoundError

Some endpoints allow for creating user comments as well, and those are tied to the restricted targets as described earlier.

Update

The regular CRUD API calls are available:

PUT /production/{prId}/user_comment/{id}

This call updates a user comment.

Details
Description
Parameters
Path Parameters
Name Description Required Type

prId

✔

Long

id

✔

Long
Body Parameters
Name Description Required Type

UserCommentRequest

✘

UserCommentRequest

UserCommentRequest

Field Name Required Type Description Format

accountId

✘

Long

int64

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

creatorId

✘

Long

The id of the user who created this resource

int64

deleted

✘

Date

date-time

description

✘

String

funnel

✘

String

id

✔

Long

The id of this resource

int64

lastUpdated

✘

Date

The time when this resource was last updated

date-time

mentionIds

✘

Set of long

int64

mentions

✘

Set of User

modifiedBy

✔

String

The request or process responsible for the last update of this resource

objectType

✘

String

The data model type or class name of this resource

parentCommentId

✘

Long

int64

productionId

✘

Long

int64

resolutionStatus

✔

String

Is the submission active, or is it archived?

Enum: Open, In Progress, Resolved, Rejected,

subscopes

✘

List of UserCommentSubscope

tags

✘

List of string

targetIds

✘

Set of string

targetObjectType

✘

String

version

✔

Long

The version of this resource, used for Optimistic Locking

int64
Return Type

UserComment

Field Name Required Type Description Format

accountId

✘

Long

int64

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

creatorId

✘

Long

The id of the user who created this resource

int64

deleted

✘

Date

date-time

description

✘

String

funnel

✘

String

id

✔

Long

The id of this resource

int64

lastUpdated

✘

Date

The time when this resource was last updated

date-time

mentionIds

✘

Set of long

int64

mentions

✘

Set of User

modifiedBy

✔

String

The request or process responsible for the last update of this resource

objectType

✘

String

The data model type or class name of this resource

parentCommentId

✘

Long

int64

productionId

✘

Long

int64

resolutionStatus

✔

String

Is the submission active, or is it archived?

Enum: Open, In Progress, Resolved, Rejected,

subscopes

✘

List of UserCommentSubscope

tags

✘

List of string

targetIds

✘

Set of string

targetObjectType

✘

String

version

✔

Long

The version of this resource, used for Optimistic Locking

int64
Content Type

  • application/json

Responses
Table 4. http response codes
Code Description Datatype

200

The request was successful.

UserComment

403

The user needs USER_COMMENT_EDIT or USER_COMMENT_EDIT_ALL rights.

ForbiddenError

404

The production or user comment was not found.

NotFoundError

 
PATCH /production/{prId}/user_comment/{id}

This call patches a user comment.

Details
Description
Parameters
Path Parameters
Name Description Required Type

prId

✔

Long

id

✔

Long
Body Parameters
Name Description Required Type

body

✘

Object

body

Field Name

Required

Type

Description

Format
Query Parameters
Name Description Required Type

version

✘

Long
Return Type

UserComment

Field Name Required Type Description Format

accountId

✘

Long

int64

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

creatorId

✘

Long

The id of the user who created this resource

int64

deleted

✘

Date

date-time

description

✘

String

funnel

✘

String

id

✔

Long

The id of this resource

int64

lastUpdated

✘

Date

The time when this resource was last updated

date-time

mentionIds

✘

Set of long

int64

mentions

✘

Set of User

modifiedBy

✔

String

The request or process responsible for the last update of this resource

objectType

✘

String

The data model type or class name of this resource

parentCommentId

✘

Long

int64

productionId

✘

Long

int64

resolutionStatus

✔

String

Is the submission active, or is it archived?

Enum: Open, In Progress, Resolved, Rejected,

subscopes

✘

List of UserCommentSubscope

tags

✘

List of string

targetIds

✘

Set of string

targetObjectType

✘

String

version

✔

Long

The version of this resource, used for Optimistic Locking

int64
Content Type

  • application/json

Responses
Table 5. http response codes
Code Description Datatype

200

The request was successful.

UserComment

403

The user needs USER_COMMENT_EDIT or USER_COMMENT_EDIT_ALL rights.

ForbiddenError

404

The production or user comment was not found.

NotFoundError

 
DELETE /production/{prId}/user_comment/{id}

This call removes a user comments.

Details
Description
Parameters
Path Parameters
Name Description Required Type

prId

✔

Long

id

✔

Long
Body Parameters
Name Description Required Type

body

✘

Object

body

Field Name

Required

Type

Description

Format
Return Type

UserComment

Field Name Required Type Description Format

accountId

✘

Long

int64

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

creatorId

✘

Long

The id of the user who created this resource

int64

deleted

✘

Date

date-time

description

✘

String

funnel

✘

String

id

✔

Long

The id of this resource

int64

lastUpdated

✘

Date

The time when this resource was last updated

date-time

mentionIds

✘

Set of long

int64

mentions

✘

Set of User

modifiedBy

✔

String

The request or process responsible for the last update of this resource

objectType

✘

String

The data model type or class name of this resource

parentCommentId

✘

Long

int64

productionId

✘

Long

int64

resolutionStatus

✔

String

Is the submission active, or is it archived?

Enum: Open, In Progress, Resolved, Rejected,

subscopes

✘

List of UserCommentSubscope

tags

✘

List of string

targetIds

✘

Set of string

targetObjectType

✘

String

version

✔

Long

The version of this resource, used for Optimistic Locking

int64
Content Type

  • application/json

Responses
Table 6. http response codes
Code Description Datatype

200

The request was successful.

UserComment

403

The user needs USER_COMMENT_EDIT or USER_COMMENT_EDIT_ALL rights.

ForbiddenError

404

The production or user comment was not found.

NotFoundError