What are Comments for?

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

When creating a Comment, you can associate it with:

• An Entity Type
• Entity Id or Entity Reference

Making it retrievable via the `comments` Query.

Permissions

The following Permissions are required for different operations on Comments:

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

• `USER_VIEW`

Features

The Comment GraphQL API enables the following functionality:

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

• 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.

Inputs

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

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)

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:

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

Response

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}

Inputs

The Input fields for updating a Comment are defined with the `UpdateCommentInput`:

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

Response

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}

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

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}

Inputs

The Input arguments for retrieving a single 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

Response

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}

1{
2  "id": 123
3}

Inputs

The Input arguments for retrieving Comments:

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`

Response

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}

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