Entity storage - Custom objects

Freshworks customers have real-world data modelling requirements, all of which cannot be met by a product’s native objects. The products offer custom fields to extend the existing native objects. At times, customers need entities that are related to native objects but do not exist within the product. Custom objects help meet this requirement. Through the use of an app, custom objects, and their relationships to native objects (associations) customers can create and use entities that act as part of the product itself, to meet specific functional requirements.

Apps that consume the default native objects or custom fields that the Freshworks products offer, can use the developer platform’s data storage feature. For a long time, the developer platform supported only key-value storage. This poses certain limitations in terms of key size, value field size, reverse look-ups, and capabilities to query, aggregate, report, and relate data. As part of the custom objects functionality, the developer platform offers entity storage in addition to the existing key-value storage. Entity storage helps provide capabilities such as reporting and aggregation of stored data, look up, retrieval, and usage of relational information, querying on stored data, and so on.

To leverage the entity storage - custom objects feature, when you build an app, ensure to use FDK 7.3.x or a later version.

Note:Custom objects created through an app (as specified in this section) cannot be accessed by another app.

To create and use custom objects,

1. Define entities.
2. As part of the app code, use the custom objects interface to create entity records.
3. As part of the app code, define the necessary actions or operations on the entity records.

Sample use case - KYC record creation and updation for all contacts in the Freshsales Classic system. On initialization, the app leverages the custom objects feature to create KYC records for contacts in the Freshsales Classic system, if such a record does not exist for a contact. On record creation the KYC status is Pending. The app is deployed as a full page app and also as a Contact Details page app. The app displays all KYC records in the Pending status. Also, through entity-storage retrievals, the app provides a provision to view the KYC documents. Based on the submitted approval documents, an agent can approve or reject the KYC document. The app updates the entity-storage records and displays the updated status on the app interface.

In Freshworks products, business data is modelled as objects. The objects are created out of specific object types. An entity is an object type. Entity definition is the schema definition of the object type. Schema definition includes the definition of all the object.attributes. Contacts, Deals, Sales Accounts, Tasks and so on are some default native objects. tasks.description, tasks.status and tasks.due_date are some of the attributes of the task entity.

You can use the custom objects feature to define new entities (object types). An object belonging to an entity (object type) is a record. Entity records (objects) of the defined object types can be created and an app can process these records to provide meaningful results.

To define and use entities:

1. Define the custom object schema - Entity definition specification. The schema includes all object.attribute definitions.
2. Initiate entity storage.
3. Obtain a reference to the entity to facilitate schema and record operations.

Note: After an app is published, you can update or modify the entity definition and submit a new version of the app.

1. From the app’s root directory, navigate to the config folder and create an entities.json file.
2. In the entities.json file, use the syntax shown on the right pane to configure all custom objects that the app uses, as JSON objects.

The developer platform’s data storage feature offers a client.db or $db interface to store and retrieve data. For custom objects, the interface is enhanced beyond its lightweight key-value storage capabilities to support entity storage. This facilitates custom object schema creation and deletion and CRUD operations on the records. Currently, the entity storage is accessible through a versioned interface that specifies that the app uses the v1 version of the entity storage feature.

To initiate entity storage and start using the custom objects interface, use the following constructor:

const entity = client.db.entity({ version: "v1" });

const $entity = $db.entity({ version: "v1" });

Response
The constructor returns a versioned wrapper interface that can be used for custom objects operations.

To obtain a reference to the entity, use one of the following interface calls:

const <entReference> = entity.get("<entity-name>");

const <entReference> = $entity.get("<entity-name>");

Response
A successful call returns a class that represents the entity and contains the static methods that can be used to perform operations on the entity records.

{
  schema: async function() {},
  create: async function() {},
  get: async function() {},
  getAll: async function() {},
  update: async function() {},
  delete: async function() {}
}

The fdk validate and fdk pack commands validate the entities.json file, to ensure that the Entity Definition Specifications are appropriate. You can test entities creation and record operations before submitting the app.

App installation implicitly creates the entities specified in entities.json.

To verify the entity creation and view the schema of the created entity, use one of the following interface calls:

Note:<entReference> is a reference to the actual entity.

<entReference>.schema();

$entity.get("<entity-name>").schema();

Response
A successful call returns the entity object created based on entities.json specification, along with the following meta-data:

• id: Unique numeric identifier of the entity, auto-generated by the developer platform when the entity is created and stored.
• name: <entity-name> as specified in entities.json.
• prefix: Prefix associated with the entity and used in internal interface calls to uniquely identify entities, auto-generated by the developer platform when the entity is created.

For information on the fields array, see Attributes of <entity-name>.field object.

App uninstallation clean slates data and implicitly deletes the entities definition.

After an app is published to the marketplace, you can modify the entity definition specification, test the changes, and resubmit a new version of the app.

In entities.json,

• You can add new entities.
• You can delete existing entities. All records associated with the deleted entity are deleted.
• If you modify the <entity-name> of an existing entity, the entity with the previous <entity-name> is deleted and a new entity is created. All records associated with the previous <entity-name> are deleted.

In entities.json > <entity-name>.fields,

• You can add a new field object.
• You can delete an existing field object.
• If you modify the fields.name value, the attribute with the previous name is deleted and a new attribute is created.
• For an existing field, you cannot modify the fields.type value.
• For an existing field, you cannot modify the fields.filterable value.
• For an existing field, you can modify the fields.required value. If the fields.required value is modified to be true, for all existing entity records with no values for the field that is marked as required, the field value is stored as null.
• For an attribute of the type enum, you cannot modify the fields.choices array.
• For an attribute of the type section, you can add or delete new fields.

Through the app and its components, multiple records (objects) of a specific entity type can be created. These records provide data that can be processed by the app. As part of processing the data, the app can programmatically perform the following operations on the records:

• Create records.
• Update a record.
• Retrieve records.
  • Retrieve the data of a specific record.
  • Retrieve all records.
  • Apply filters and retrieve specific records.
  • Delete a record.

The operations are performed through the custom objects interface, which returns promises. Successful calls return responses with requisite data and the following:

• display_id: Unique identifier of a record, auto-generated when the record is created. It is a combination of the prefix used to identify the entity and an incremental numeric value that uniquely identifies the record.
• created_at: Timestamp of when the record is created, specified in the ISO-8601 format.
• updated_at: Timestamp of when the record is last updated, specified in the ISO-8601 format.

To create a record belonging to a specific entity, use one of the following interface calls:

<entReference>.create({
<fields.name1>: <valid value for fields.name1>,
<fields.name2>: "<valid value for fields.name2>"
});

Response: A successful create operation, returns the record object created based on the input and the corresponding meta-data. record.data contains the JSON object that is stored as the record text.

To update a record belonging to a specific entity, use one of the following interface calls:

<entReference>.update("<display-id>", {
  <fields.name1>: "<valid value for fields.name1>",
  <fields.name2>: <valid value for fields.name2>
});

Response: A successful update operation, returns the record object updated based on the input and the corresponding meta-data. record.data contains the JSON object that is stored as the updated record text.

To retrieve a specific record belonging to a specific entity, use one of the following interface calls:

Note:<entReference> is a reference to the actual entity. <display-id> is the unique identifier of a record, auto-generated when the record is created. <display-id> is returned as part of the response to a successful create record operation.

<entReference>.get("<display-id>");

const record = await $entity.get("<entity-name>").get("<display-id>");

contact_entity.get("kycs-13");

Response: A successful retrieve by display-id operation, returns the retrieved record object and the corresponding meta-data. record.data contains the JSON object that is stored as the record text.

To retrieve all records belonging to a specific entity, use one of the following interface calls:

Note: <entReference> is a reference to the actual entity.

<entReference>.getAll();

const records = await <entReference>.getAll({});

function loadContacts() {
    contact_entity.getAll()
        .then(function (data) {
            //render details of all contacts as a list
    })
        .catch(function (error) {
            //error message
    })
}

Response: A successful retrieve all records operation, returns the retrieved records as an array of objects. The retrieved records are not paginated, retrieved in sets of 100 records, and ordered by created_time chronologically. The links attribute in the response provides a token to retrieve the next set of records.

Response attributes

function loadContacts() {
    contact_entity.getAll({
        next: {
            marker: "Lbr2zerj3WHNDsZ1NsdFj7NiigDlittVkGc7RmPjKF3"
    }})
    .then(function (data) {
        //render details of all contacts as a list
    })
    .catch(function (error) {
        //error message
    })
}

Response: The marker value, in the call, is an encoded token of a record id. A successful call retrieves the next set of records, starting from the record identified by the marker value. The marker value of the last set of records is null.

You can include queries as part of the retrieve all records call and thereby specify filter criteria for the filterable fields. On successful processing of the call only specific records that satisfy the criteria are retrieved.

To specify queries as part of the interface call, use the following format:

<entReference>.getAll({
  query: {
    <filterable field-name>: "<filter criteria value>"
  }
});

const record = await <entReference>.getAll({
  query: {
    <filterable field-name>: "<filter criteria value>"
  }
});

To use the and or or operations to construct a query with multiple query parameters, use the following samples:

const record = contact_entity.getAll({
  query: {
    $or:[{
       status: "Pending"
    },
    {
       status: "Rejected"
     }
   ]}
   }).then(function(data){
    // access to filtered contacts
  }).catch(function(data){
   // Handle errors
})

Response: A successful retrieve all records operation with filters, returns the records that meet the filter criteria as an array of objects.

Response attributes

To delete a specific record belonging to a specific entity, use one of the following interface calls:

Note: <entReference> is reference to the actual entity. <display-id> is the unique identifier of a record, auto-generated when the record is created. <display-id> is returned as part of the response to a successful create record operation.

<entReference>.delete("<display-id>");

Response: A successful delete operation returns an empty object.

If a call fails, the custom objects interface returns an error response with the following attributes.

Note:To test your app, use the latest version of the Chrome browser

1. To test the configured custom objects, from the command prompt navigate to the app project folder and run the following command:

   fdk run

   The command validates the entities.json file and displays the validation errors, if any. Fix the validation errors and run the command. The command creates a .sqlite file and the entities that are defined in entity.json. .sqlite mimics the platform’s entity storage, in the local setting.

   Note:If the entity definition specification in entities.json is modified, for the modification to reflect in the local .sqlite file, you will have to rerun the fdk run command. A prompt to resync is displayed and a resync deletes all existing entities, associated data, and records and creates a clean instance.

2. Log in to your Freshsales Classic account.

   If the app is successfully created, it is rendered in the app location specified in manifest.json.

3. To the Freshsales Classic account URL, append ?dev=true.
   Example URL: https://subdomain.freshsales.io/leads/1?dev=true

4. To test the custom objects interface calls, from the app, simulate record operations. If the calls fail, appropriate error responses are displayed.