How Comment GraphQL API works

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

Topic

Author:

Kirill Gaiduk

Changed on:

9 Dec 2024

Overview

The Comment GraphQL API enables you to Create, Update, and Query comments linked to various entities within the Fluent platform.

Prerequisites

You should have knowledge of the GraphQL API, including:
- GraphQL Operations
- GraphQL Permissions
You should have knowledge of Users, Roles, and Permissions

Authors:

Girish Padmanabha, Kirill Gaiduk

Changed on:

20 Feb 2025

Overview

The Comment GraphQL API allows customers to manage Comments across various Entities.

Multiple Comments can be added against the same Entity, with each Comment automatically capturing:

The timestamp
The User who created it (
```
`USER_VIEW`
```
Permission is required to access the User data)

This feature allows Users to record specific business actions and events, providing a comprehensive history of interactions and updates.

Key points

Add Comments to any Entity Type, enabling detailed documentation of business actions
Specific Permissions are required for Comment operations
Use the
```
`createComment`
```
and
```
`updateComment`
```
Mutations to manage Comments
Use the
```
`commentById`
```
and
```
`comments`
```
Queries to retrieve Comments

What are Comments for?

A Comment provides an additional piece of information to the Entity it is related to.

Note

The Comment Entity is independent and not tied to a specific Entity.

When creating a Comment, you can associate it with:

An Entity Type
Entity Id or Entity Reference

Making it retrievable via the

`comments`

Query.

Reminder

Multiple Comments can be added to the same Entity, each automatically capturing:

The timestamp
The User that created the Comment (
```
`USER_VIEW`
```
Permission is required to access the User data)
The Retailer Id of the associated Entity (when the
```
`fc.graphql.comment.access`
```
Setting
is set to the
```
`retailer`
```
value)

Permissions

The following Permissions are required for different operations on Comments:

```
`COMMENT_CREATE`
```
```
`COMMENT_UPDATE`
```
```
`COMMENT_VIEW`
```

Note

The Permissions to create, update, and view Comments can be managed at the Account or Retailer level.

The Comment GraphQL API Permission handling is controlled with the

`fc.graphql.comment.access`

Setting value with the following options available:

```
`account`
```
This means that cross-Retailer Comments can be read, created, or updated by any User with the appropriate Permissions. Once a User has these Permissions, they can access and manage all Comments at the Account level by default (
```
`ACCOUNT`
```
and
```
`RETAILER`
```
Permission Context works similarly).
```
`retailer`
```
Retailer-specific (
```
`RETAILER`
```
Permission Context) Permissions can be granted and validated upon executing the Comment GraphQL operations. A
```
`retailerId`
```
specified in the User Permission should match the Entity (associated with the Comment)
```
`retailerId`
```
for successful Comment Mutation / Query execution. This setup ensures comprehensive access control, allowing:
- Admins to manage data access effectively, delimiting Retailer-specific information
- Users to collaborate and maintain a unified record of interactions across various Entities within the same Retailer

```
`USER_VIEW`
```

Note

The data of the User that created a Comment is captured and stored in that Comment. That's why

`USER_VIEW`

Permission is mandatory to retrieve this User information via the API or view it on the UI. The

`USER_VIEW`

Permission for Comments can be managed at the Account level.

Features

The Comment GraphQL API enables the following functionality:

Create Comment
The
```
`createComment`
```
Mutation
allows the creation of a Comment against a known Entity.

Note

Check the following guidance to enable Comments management via the UI for Fluent Web Apps:

Update Comment
The
```
`updateComment`
```
Mutation
allows for the updating of an existing Comment object.
Get Comment by Id
The
```
`commentById`
```
Query
retrieves a Comment based on a provided Id.
Query Comments
The
```
`comments`
```
Query
retrieves Comments based on various filter criteria.

Reference Usage

Here is a collection of common scenarios for the Comment GraphQL API usage:

Order Entity:
- Customer service representatives can add Comments regarding customer interactions or actions taken on an Order
- Comments can document the business status updates or any issues related to the Order processing
Fulfillment Entity:
- Store Users can add Comments when fulfilling Orders, noting any special instructions or issues encountered during the fulfillment process
Credit Memo Entity:
- Financial teams can document reasons for issuing Credit Memos and any follow-up actions required
Return Order Entity:
- Comments can be added detailing the reasons for Returns and the steps taken to process them
Location Entity:
- Store managers can add Comments about:
  - Inventory status
  - Store operations
  - Or any Location-specific updates

This flexibility allows the capture of essential information at various stages of business processes, ensuring that all relevant data is saved and can be retrieved when needed.

Overview

The

`createComment`

Mutation allows the creation of a Comment against a known Entity.

Prerequisites

Specific Permissions are required for creating Comments:

```
`COMMENT_CREATE`
```
```
`COMMENT_VIEW`
```

Key points

Use the
```
`createComment`
```
Mutation to create a Comment against a known Entity
Manage the Comment Permissions at the Account or Retailer level
Apply the "Retailer-specific Comment Permission Check" validation logic with the
```
`fc.graphql.comment.access`
```
Setting (
```
`retailer`
```
value)
Created Comments inherit the
```
`retailerId`
```
of the associated Entity

GraphQL Reference documentation

The GraphQL Reference should be treated as the source of truth for documentation.

Inputs

The Input fields for creating a Comment are defined with the

`createCommentInput`

Field	Type	Description	Notes
`entityType`	String!	Type of the Entity	For example: `ORDER` `FULFILMENT` `ORDER_ITEM` `PRODUCT_CATALOGUE` Max character limit: 255
`entityId`	ID	Id of the Entity	While the type of this field is ID, it currently only supports Integer values
`entityRef`	String	Reference of the Entity	Max character limit: 255
`text`	String!	Comment text	Max character limit: 200

Validation

Comment Permissions could be managed at the Account or Retailer level, which is controlled via the

`fc.graphql.comment.access`

Setting.

The

`retailer`

Setting value enables the Retailer-specific access management, so the validation logic is applied to verify that your User has the correct rights to execute the

`createComment`

Mutation - "Retailer-specific Comment Permission Check":

1. Determine the

`retailerId`

of the Entity (associated with the Comment)

Entity Type Validation

The given
```
`entityType`
```
(Input) is compared with the existing Types (from the GraphQL Schema):
- Case is ignored (e.g.,
```
`ORDER`
```
  matches
```
`Order`
```
  )
- Underscore is ignored (e.g.,
```
`CREDIT_MEMO`
```
  matches
```
`CreditMemo`
```
  )
- Known exception:
```
`FULFILMENT_OPTIONS`
```
  will be recognized as
```
`FulfilmentOption`
```
  Type
The corresponding Database Entity Class is determined for the found GraphQL Type (e.g.,
```
`ORDER`
```
Type corresponds to the
```
`CustomerOrderEntity`
```
Class)

Warning

An exception is thrown when the corresponding Database Entity Class is not found.

In this case, you should fix your Create Comment Payload to specify the correct Entity Type.

Entity Id or Reference Validation

The Create Comment Payload could contain:
- ```
`entityId`
```
  only
- ```
`entityRef`
```
  only
- Both
```
`entityId`
```
  and
```
`entityRef`
```
```
`entityId`
```
is always considered first (to define the corresponding Entity for Comment creation)
```
`entityRef`
```
is considered when
```
`entityId`
```
was not provided

Warning

The exception is thrown when the Entity is not found for a given

`entityId`

`entityRef`

(or there were multiple returns, e.g., the

`entityId`

was empty and the

`entityRef`

was not unique).

In this case, you should fix your Create Comment Payload to specify the correct Entity Id or Reference.

Entity Retailer Id Validation

The
```
`retailerId`
```
value of the Entity found with the provided
```
`entityType`
```
,
```
`entityId`
```
/
```
`entityRef`
```
is automatically retrieved:
- For Entity Types with the direct Retailer association, e.g.,
```
`retailerId`
```
  is taken from the
```
`order.retailer`
```
  field value for Orders
- For Entity Types without the direct Retailer association, the
```
`retailerId`
```
  is attempted to be taken from a "Parent" Entity. For example, find the Fulfillment (with the provided
```
`entityType`
```
  ,
```
`entityId`
```
  /
```
`entityRef`
```
  ) --> find its "Parent" Order --> get the
```
`retailerId`
```
  from the Order
Comment
```
`retailerId`
```
field is filled in with the associated Entity Retailer value found.
Comment
```
`retailerId`
```
field remains empty when:
- The associated Entity
```
`retailerId`
```
  was not found
- The associated Entity is a cross-Retailer one (e.g., Inventory Domain Entities, like Inventory Position, Virtual Catalog, etc.)
- The
```
`fc.graphql.comment.access`
```
  Setting
  value is set to
```
`account`
```

Note

A Comment could be created with an empty

`retailerId`

The "Retailer-specific Comment Permission Check" is not applied to Comments with empty

`retailerId`

(e.g., Comments for cross-Retailer Entities or legacy ones).

As such, those Comments remain available for update and query operations.

2. Compare the querying User

`retailerId`

to the associated Entity

`retailerId`

The User

`retailerId`

is defined with the User Role Context Id:

A Comment is created upon the mentioned (User and Entity)

`retailerId`

-s match.

Warning

Otherwise, the exception is thrown.

Therefore, you should:

Fix your Create Comment Payload (e.g., reconsider the Entity to create Comment to)
Ask your Admin for the required Permission(s) provisioning

Reminder

The "Retailer-specific Comment Permission Check" is not applied when:

The
```
`fc.graphql.comment.access`
```
Setting
is set with the
```
`account`
```
value
The associated Entity
```
`retailerId`
```
could not be found

Response

The response consists of the details of the Comment:

Field	Type	Description	Notes
`id`	ID!	Id of the Comment
`entityType`	String!	Type of the Entity	For example: `ORDER` `FULFILMENT` `ORDER_ITEM` `PRODUCT_CATALOGUE`
`entityId`	ID	Id of the Entity
`entityRef`	String	Reference of the Entity
`text`	String!	Comment text	Max character limit: 200
`createdOn`	DateTime	Time of the Comment creation
`updatedOn`	DateTime	Time of the Comment last update
`user`	User	The author of the Comment	Filled in upon the Comment creation Updated upon the Comment update `USER_VIEW` Permission is required

Sample Payload

1mutation createComment ($input: CreateCommentInput) {
2    createComment (input: $input) {
3        id
4        entityType
5        entityRef
6        entityId
7        text
8        createdOn
9        updatedOn
10    }
11}

Language: graphqlschema

Name: Sample createComment Mutation

Description:

Creating a Comment.

API Endpoint:

`POST: {{fluentApiHost}}/graphql`

1{
2    "input": {
3        "entityType": "ORDER",
4        "entityId": "123",
5        "text": "Sample Comment for the Order"
6    }
7}

Language: graphqlschema

Name: Sample GraphQL Variables for the createComment Mutation

Description:

Creating a Comment for the Order with a specified Id.

1{
2    "data": {
3        "createComment": {
4            "id": "26963",
5            "entityType": "ORDER",
6            "entityRef": null,
7            "entityId": "123",
8            "text": "Sample Comment for the Order",
9            "createdOn": "2024-12-09T09:15:57.396Z",
10            "updatedOn": "2024-12-09T09:15:57.396Z"
11        }
12    }
13}

Language: graphqlschema

Name: createComment Mutation Response Example

Description:

Creating a Comment for the Order with a specified Id.

Author:

Kirill Gaiduk

Changed on:

20 Feb 2025

Overview

The

`updateComment`

Mutation allows for the updating of an existing Comment object.

Prerequisites

Specific Permissions are required for updating Comments:

```
`COMMENT_UPDATE`
```
```
`COMMENT_VIEW`
```

Key points

Use the
```
`updateComment`
```
Mutation to update an existing Comment
Manage the Comment Permissions at the Account or Retailer level
Apply the "Retailer-specific Comment Permission Check" validation logic with the
```
`fc.graphql.comment.access`
```
Setting (
```
`retailer`
```
value)

GraphQL Reference documentation

The GraphQL Reference should be treated as the source of truth for documentation.

Inputs

The Input fields for updating a Comment are defined with the

`UpdateCommentInput`

Field

Type

Description

Notes

`id`

ID!

Id of the Comment

`text`

String!

Comment text

Max character limit: 200

Warning

The
```
`entityRef`
```
field has been deprecated.
We do not recommend its usage as an Update Comment Input field.
A given
```
`entityRef`
```
must correspond to the Entity associated with the Comment. Otherwise, the exception is thrown.

Validation

Comment Permissions could be managed at the Account or Retailer level, which is controlled via the

`fc.graphql.comment.access`

Setting.

The

`retailer`

Setting value enables the Retailer-specific access management, so the validation logic is applied to verify that your User has the correct rights to execute the

`updateComment`

Mutation - "Retailer-specific Comment Permission Check":

A target Comment is found by its Id (input)
A Comment Entity
```
`retailerId`
```
field stores a Retailer of the associated Entity
The Comment
```
`retailerId`
```
is compared to the querying User
```
`retailerId`
```
(defined with the User Role Context Id)
The Comment is updated upon the mentioned (User and Comment)
```
`retailerId`
```
's match

Warning

Otherwise, the exception is thrown.

Therefore, you should:

Fix your Update Comment Payload (e.g., reconsider the input Comment Id)
Ask your Admin for the required Permission(s) provisioning

Reminder

The "Retailer-specific Comment Permission Check" is not applied when:

The
```
`fc.graphql.comment.access`
```
Setting
is set with the
```
`account`
```
value
The Comment has an empty
```
`retailerId`
```

Response

The response consists of the details of the Comment:

Field	Type	Description	Notes
`id`	ID!	Id of the Comment
`entityType`	String!	Type of the Entity	For example: `ORDER` `FULFILMENT` `ORDER_ITEM` `PRODUCT_CATALOGUE`
`entityId`	ID	Id of the Entity
`entityRef`	String	Reference of the Entity
`text`	String!	Comment text	Max character limit: 200
`createdOn`	DateTime	Time of the Comment creation
`updatedOn`	DateTime	Time of the Comment last update
`user`	User	The author of the Comment	Filled in upon the Comment creation Updated upon the Comment update `USER_VIEW` Permission is required

Sample Payload

1mutation updateComment ($input: UpdateCommentInput) {
2    updateComment (input: $input) {
3        id
4        entityType
5        entityRef
6        entityId
7        text
8        createdOn
9        updatedOn
10    }
11}

Language: graphqlschema

Name: Sample updateComment Mutation

Description:

Updating the Comment.

API Endpoint:

`POST: {{fluentApiHost}}/graphql`

1{
2    "input": {
3        "id": "26963",
4        "text": "Sample Comment"
5    }
6}

Language: graphqlschema

Name: Sample GraphQL Variables for the updateComment Mutation

Description:

Updating the Comment with a specified Id.

1{
2    "data": {
3        "updateComment": {
4            "id": "26963",
5            "entityType": "ORDER",
6            "entityRef": null,
7            "entityId": "123",
8            "text": "Sample Comment",
9            "createdOn": "2024-12-09T09:15:57.396Z",
10            "updatedOn": "2024-12-09T09:22:57.791Z"
11        }
12    }
13}

Language: graphqlschema

Name: updateComment Mutation Response Example

Description:

Updating the Comment with a specified Id.

Author:

Kirill Gaiduk

Changed on:

20 Feb 2025

Overview

The

`commentById`

Query retrieves a Comment based on a provided Id.

Prerequisites

```
`COMMENT_VIEW`
```
Permission is required for retrieving a Comment

Key points

Use the
```
`commentById`
```
Query to retrieve an existing Comment
Manage the Comment Permissions at the Account or Retailer level
Apply the "Retailer-specific Comment Permission Check" validation logic with the
```
`fc.graphql.comment.access`
```
Setting (
```
`retailer`
```
value)

GraphQL Reference documentation

The GraphQL Reference should be treated as the source of truth for documentation.

Inputs

The Input arguments for retrieving a single Comment:

Argument

Type

Description

`id`

ID!

Id of the Comment

Validation

Comment Permissions could be managed at the Account or Retailer level, which is controlled via the

`fc.graphql.comment.access`

Setting.

The

`retailer`

Setting value enables the Retailer-specific access management, so the validation logic is applied to verify that your User has the correct rights to execute the

`commentById`

Query - "Retailer-specific Comment Permission Check":

A target Comment is found by its Id (input)
A Comment Entity
```
`retailerId`
```
field stores a Retailer of the associated Entity
The Comment
```
`retailerId`
```
is compared to the querying User
```
`retailerId`
```
(defined with the User Role Context Id)
The Comment is retrieved upon the mentioned (User and Comment)
```
`retailerId`
```
's match

Warning

Otherwise,

`null`

is returned.

Therefore, you should:

Fix your Get Comment Payload (e.g., reconsider the input Comment Id)
Ask your Admin for the required Permission(s) provisioning

Reminder

The "Retailer-specific Comment Permission Check" is not applied when:

The
```
`fc.graphql.comment.access`
```
Setting
is set with the
```
`account`
```
value
The Comment has an empty
```
`retailerId`
```

Response

The response consists of the details of the Comment:

Field	Type	Description	Notes
`id`	ID!	Id of the Comment
`entityType`	String!	Type of the Entity	For example: `ORDER` `FULFILMENT` `ORDER_ITEM` `PRODUCT_CATALOGUE`
`entityId`	ID	Id of the Entity
`entityRef`	String	Reference of the Entity
`text`	String!	Comment text	Max character limit: 200
`createdOn`	DateTime	Time of the Comment creation
`updatedOn`	DateTime	Time of the Comment last update
`user`	User	The author of the Comment	Filled in upon the Comment creation Updated upon the Comment update `USER_VIEW` Permission is required

Sample Payload

1query commentById ($id: ID!) {
2    commentById (id: $id) {
3        id
4        entityType
5        entityId
6        entityRef
7        text
8        createdOn
9        updatedOn
10        user {
11           username
12           id
13           ref
14           primaryEmail
15           firstName
16           lastName
17           timezone
18        }
19    }
20}

Language: graphqlschema

Name: Sample commentById Query

Description:

Getting the Comment.

API Endpoint:

`POST: {{fluentApiHost}}/graphql`

1{
2  "id": 123
3}

Language: graphqlschema

Name: Sample GraphQL Variables for the commentById Query

Description:

Getting the Comment with a specified Id.

Author:

Kirill Gaiduk

Changed on:

20 Feb 2025

Overview

The

`comments`

Query retrieves Comments based on various filter criteria.

Prerequisites

```
`COMMENT_VIEW`
```
Permission is required for retrieving Comments

Key points

Use the
```
`comments`
```
Query to retrieve existing Comments
Manage the Comment Permissions at the Account or Retailer level
Apply the "Retailer-specific Comment Permission Check" validation logic with the
```
`fc.graphql.comment.access`
```
Setting (
```
`retailer`
```
value)

GraphQL Reference documentation

The GraphQL Reference should be treated as the source of truth for documentation.

Inputs

The Input arguments for retrieving Comments:

Argument	Type	Description	Notes
`entityType`	[String!]	Type of the Entity	For example: `ORDER` `FULFILMENT` `ORDER_ITEM` `PRODUCT_CATALOGUE`
`entityId`	[ID]	Id of the Entity
`entityRef`	[String]	Reference of the Entity
`text`	[String!]	Comment text
`createdOn`	DateRange	Date range for Comments creation
`updatedOn`	DateRange	Date range for Comments last update
`first`	Int	Returns the first n elements from the list
`last`	Int	Returns the last n elements from the list
`before`	String	Returns the elements in the list that come before the specified global Id	This is a cursor (the value is used for pagination)
`after`	String	Returns the elements in the list that come after the specified global Id	This is a cursor (the value is used for pagination)

Validation

Comment Permissions could be managed at the Account or Retailer level, which is controlled via the

`fc.graphql.comment.access`

Setting.

The

`retailer`

Setting value enables the Retailer-specific access management, so the validation logic is applied to verify that your User has the correct rights to execute the

`comments`

Query - "Retailer-specific Comment Permission Check":

Comments are searched by the given Input Arguments
A Comment Entity
```
`retailerId`
```
field stores a Retailer of the associated Entity
For all the found Comments, the Comment
```
`retailerId`
```
is compared to the querying User
```
`retailerId`
```
(defined with the User Role Context Id)
The list of the retrieved Comments contains:
- The Comments for which the mentioned (User and Comment)
```
`retailerId`
```
  -s matches
- The Comments with empty
```
`retailerId`
```

Warning

All the other Comments (the User doesn't have Permissions for) are filtered out from the response.

Reminder

The "Retailer-specific Comment Permission Check" is not applied when:

The
```
`fc.graphql.comment.access`
```
Setting
is set with the
```
`account`
```
value
The Comment has an empty
```
`retailerId`
```

Response

The response consists of the details of the Comment:

Field	Type	Description	Notes
`id`	ID!	Id of the Comment
`entityType`	String!	Type of the Entity	For example: `ORDER` `FULFILMENT` `ORDER_ITEM` `PRODUCT_CATALOGUE`
`entityId`	ID	Id of the Entity
`entityRef`	String	Reference of the Entity
`text`	String!	Comment text	Max character limit: 200
`createdOn`	DateTime	Time of the Comment creation
`updatedOn`	DateTime	Time of the Comment last update
`user`	User	The author of the Comment	Filled in upon the Comment creation Updated upon the Comment update `USER_VIEW` Permission is required

Sample Payload

1query comments($createdOn: DateRange) {
2    comments(createdOn: $createdOn) {
3        edges {
4            node {
5                id
6                entityId
7                entityRef
8                entityType
9                text
10                createdOn
11                updatedOn
12            }
13            cursor
14        }
15    }
16}

Language: graphqlschema

Name: Sample comments Query

Description:

Getting the Comments created within the specified date range.

API Endpoint:

`POST: {{fluentApiHost}}/graphql`

1{
2    "createdOn": {
3        "from": "2024-11-16T00:32:28.935Z",
4        "to": "2024-11-16T23:40:28.935Z"
5    }
6}

Language: graphqlschema

Name: Sample GraphQL Variables for the comments Query

Description:

Getting the Comments created within the specified date range.

How Comment GraphQL API works

Overview

Comment GraphQL API Overview

Overview

Key points

What are Comments for?

Permissions

Features

Reference Usage

Related content

Create Comment

Update Comment

Get Comment by Id

Query Comments

Create Comment

Overview

Key points

Inputs

Validation

1. Determine the `retailerId` of the Entity (associated with the Comment)

Entity Type Validation

Entity Id or Reference Validation

Entity Retailer Id Validation

2. Compare the querying User `retailerId` to the associated Entity `retailerId`

Response

Sample Payload

Update Comment

Overview

Key points

Inputs

Validation

Response

Sample Payload

Get Comment by Id

Overview

Key points

Inputs

Validation

Response

Sample Payload

Query Comments

Overview

Key points

Inputs

Validation

Response

Sample Payload

Related content

fc.graphql.comment.access

Add Comment Workflow Template Overview

Enable Add Comment functionality

Add a Comment to Order

Kirill Gaiduk

Building Blocks

By Type

Helpful Resources

Quick Links

1. Determine the
`retailerId`
of the Entity (associated with the Comment)

2. Compare the querying User
`retailerId`
to the associated Entity
`retailerId`