What are Comments for?

• An Entity Type
• Entity Id or Entity Reference

Permissions

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

• `USER_VIEW`

Features

• 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

• 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

Inputs

Validation

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`

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

Validation

• 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

Validation

• 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

Validation

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