Comment GraphQL API Overview

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Essential knowledge

Intended Audience:

Technical User

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.

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

Girish Padmanabha

Contributors:

Building Blocks

By Type

Helpful Resources

Quick Links