Fluent Commerce Logo
Docs
Sign In
Essential knowledge

Author:

Kirill Gaiduk

Changed on:

20 Feb 2025

Overview

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


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

Inputs

The Input fields for creating a Comment are defined with the `createCommentInput`:

Field

Type

Description

Notes

`entityType`

String!

Type of the

For example:

  • `ORDER`
  • `FULFILMENT`
  • `ORDER_ITEM`
  • `PRODUCT_CATALOGUE`

Max character limit: 255

`entityId`

ID

Id of the

While the type of this field is ID, it currently only supports Integer values

`entityRef`

String

Reference of the

Max character limit: 255

`text`

String!

Comment text

Max character limit: 200

Validation

Comment Permissions could be managed at the 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)
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
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`

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

The User `retailerId` is defined with the User Role Context Id:

No alt provided

A Comment is created upon the mentioned (User and ) `retailerId`-s match.


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

For example:

  • `ORDER`
  • `FULFILMENT`
  • `ORDER_ITEM`
  • `PRODUCT_CATALOGUE`

`entityId`

ID

Id of the


`entityRef`

String

Reference of the


`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}
1{
2    "input": {
3        "entityType": "ORDER",
4        "entityId": "123",
5        "text": "Sample Comment for the Order"
6    }
7}
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}