Comment GraphQL API - How it works

Essential knowledge

Author:

Girish Padmanabha

Changed on:

25 June 2024

Overview

The Comment GraphQL API enables you to create, update, and query comments linked to various entities within the Fluent platform. 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. Multiple comments can be added to the same entity, each automatically capturing the timestamp and user that created the comment. This feature can record specific business actions and events, providing a comprehensive history of interactions and updates.

Key points

Create and Update Comments: Use the
```
`createComment`
```
and
```
`updateComment`
```
mutations to manage comments.
Query Comments: Use the
```
`comments`
```
query to retrieve comments based on various filter criteria.
Get Comment by Id: Use the
```
`commentById`
```
query to retrieve a comment based on the provided id.
Automatic Metadata: Each comment automatically records the timestamp and user, providing a detailed history.
Flexibility: Comments can be added to any entity type, allowing for detailed documentation of business actions.
Permissions: Specific permissions (
```
`COMMENT_CREATE`
```
,
```
`COMMENT_UPDATE`
```
,
```
`COMMENT_VIEW`
```
) are required for creating, updating, and viewing comments.
Account-Level Permissions: Comments and permissions are managed at the account level, allowing cross-retailer comments to be accessible to users with the appropriate permissions.

Create Comment

The

`createComment`

mutation allows the creation of a comment against a known entity.

Input:

`createCommentInput`

Field	Type	Description
entityType	String!	Type of the entity. For example, ORDER, FULFILMENT, ORDERITEM, PRODUCTCATALOGUE, etc.
entityId	ID	ID of the entity. Note: While the type of this field is ID, it currently only supports Integer values.
entityRef	String	Reference of the entity.
text	String!	Comment text. Max character limit: 200.

Update Comment

The

`updateComment`

mutation allows the updating of an existing comment object.

Input:

`UpdateCommentInput`

Field	Type	Description
id	ID!	ID of the comment object.
entityRef	String	Reference of the entity.
text	String!	Comment text. Max character limit: 200.

Query Comments

The

`comments`

query retrieves comments based on various filter criteria.

Arguments

Argument	Type	Description
entityType	[String!]	Type of the entity. For example, ORDER, FULFILMENT, ORDERITEM, PRODUCTCATALOGUE, etc.
entityId	[ID]	ID of the entity.
entityRef	[String]	Entity reference.
text	[String!]	Comment text.
createdOn	DateRange	Date range for creation.
updatedOn	DateRange	Date range for 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.
after	String	Returns the elements in the list that come after the specified global ID.

Response

The response consists of edges and nodes representing the comments.

Node Fields

Field	Type	Description
id	ID!	ID of the comment object.
entityType	String!	Type of the entity. For example, ORDER, FULFILMENT, ORDERITEM, PRODUCTCATALOGUE, etc.
entityId	ID	ID of the entity.
entityRef	String	Entity reference.
text	String!	Comment text.
createdOn	DateTime	Time of creation.
updatedOn	DateTime	Time of last update.
user	User	The author of the comment.

Get Comment by Id

The

`commentById`

query retrieves a comment based on the provided id.

Arguments

Field	Type	Description
id	ID!	ID of the comment object.

Response

The response consists of the details of the comment.

Fields

Field	Type	Description
id	ID!	ID of the comment object.
entityType	String!	Type of the entity. For example, ORDER, FULFILMENT, ORDERITEM, PRODUCTCATALOGUE, etc.
entityId	ID	ID of the entity.
entityRef	String	Entity reference.
text	String!	Comment text.
createdOn	DateTime	Time of creation.
updatedOn	DateTime	Time of last update.
user	User	The author of the comment.

Permissions required for different operations on comments:

Create Comment:
```
`COMMENT_CREATE`
```
Update Comment:
```
`COMMENT_UPDATE`
```
View Comments:
```
`COMMENT_VIEW`
```

Important Note on Comment Permissions

The permissions to create, update and view comments sit at the account level. This means that cross-retailer comments can be read, created, and updated by any user with the appropriate permissions (

`COMMENT_CREATE`

`COMMENT_UPDATE`

`COMMENT_VIEW`

). Once a user has these permissions, they can access and manage all comments at the account level by default. This setup ensures comprehensive access control, allowing users to effectively collaborate and maintain a unified record of interactions across various entities within the same account.

The Comment GraphQL API provides flexibility for clients to manage comments across various entities. Multiple comments can be added against the same entity, with each comment automatically capturing the timestamp and the user who created it. This feature allows users to add comments as specific business actions occur against an entity.

Examples of Use Cases

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.
Fulfilment Entity:
- Store users can add comments when fulfilling orders, noting any special instructions or issues encountered during the fulfilment 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.

Comment GraphQL API - How it works

Overview

Key points

Create Comment

Input:
`createCommentInput`

Update Comment

Input:
`UpdateCommentInput`

Query Comments

Arguments

Response

Node Fields

Get Comment by Id

Arguments

Response

Fields

Examples of Use Cases

Related content

Enable Add Comment functionality

Add Comment Workflow Template Overview

Add a Comment to Order

Girish Padmanabha

Building Blocks

By Type

Helpful Resources