Create Comment

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

Essential knowledge

Author:

Kirill Gaiduk

Changed on:

9 Dec 2024

Overview

The

`createComment`

Mutation allows the creation of a Comment against a known Entity.

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

GraphQL Reference documentation

The GraphQL Reference should be treated as the source of truth for documentation.

Inputs

The Input fields for creating a Comment are defined with the

`createCommentInput`

Field	Type	Description	Notes
`entityType`	String!	Type of the Entity	For example: `ORDER` `FULFILMENT` `ORDER_ITEM` `PRODUCT_CATALOGUE` Max character limit: 255
`entityId`	ID	Id of the Entity	While the type of this field is ID, it currently only supports Integer values
`entityRef`	String	Reference of the Entity	Max character limit: 255
`text`	String!	Comment text	Max character limit: 200

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)

Warning

An exception is thrown when the corresponding Database Entity Class is not found.

In this case, you should fix your Create Comment Payload to specify the correct Entity Type.

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

Warning

The exception is thrown when the Entity is not found for a given

`entityId`

`entityRef`

(or there were multiple returns, e.g., the

`entityId`

was empty and the

`entityRef`

was not unique).

In this case, you should fix your Create Comment Payload to specify the correct Entity Id or Reference.

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`
```

Note

A Comment could be created with an empty

`retailerId`

The "Retailer-specific Comment Permission Check" is not applied to Comments with empty

`retailerId`

(e.g., Comments for cross-Retailer Entities or legacy ones).

As such, those Comments remain available for update and query operations.

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.

Warning

Otherwise, the exception is thrown.

Therefore, you should:

Fix your Create Comment Payload (e.g., reconsider the Entity to create Comment to)
Ask your Admin for the required Permission(s) provisioning

Reminder

The "Retailer-specific Comment Permission Check" is not applied when:

The
```
`fc.graphql.comment.access`
```
Setting
is set with the
```
`account`
```
value
The associated Entity
```
`retailerId`
```
could not be found

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 Entity	For example: `ORDER` `FULFILMENT` `ORDER_ITEM` `PRODUCT_CATALOGUE`
`entityId`	ID	Id of the Entity
`entityRef`	String	Reference of the Entity
`text`	String!	Comment text
`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

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}

Language: graphqlschema

Name: Sample createComment Mutation

Description:

Creating a Comment.

API Endpoint:

`POST: {{fluentApiHost}}/graphql`

1{
2    "input": {
3        "entityType": "ORDER",
4        "entityId": "123",
5        "text": "Sample Comment for the Order"
6    }
7}

Language: graphqlschema

Name: Sample GraphQL Variables for the createComment Mutation

Description:

Creating a Comment for the Order with a specified Id.

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}

Language: graphqlschema

Name: createComment Mutation Response Example

Description:

Creating a Comment for the Order with a specified Id.

Create Comment

Overview

Key points

Inputs

Validation

1. Determine the
`retailerId`
of the Entity (associated with the Comment)

Entity Type Validation

Entity Id or Reference Validation

Entity Retailer Id Validation

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

Response

Sample Payload

Kirill Gaiduk

Building Blocks

By Type

Helpful Resources

Quick Links