See related
No related articles

Create a KObject from an external trigger

Last Update: Sep 2024 • Est. Read Time: 4 MIN
To check plan availability, see the pricing page.

In this article, we'll show how to create custom objects (KObjects) on a Customer Timeline using a trigger from an external system. This could be used to create an order object from your e-commerce platform, responses from an NPS survey, etc. We'll create an order object as an example, but the process is similar to any type of object relevant to your customer.

Who can access this feature?
User typesAdmins can access these settings pages.


In this article

Definitions

A Klass is the definition of custom objects (KObjects), capturing the name of the object (e.g. "order"), an icon to represent it, and the properties that individual objects can have (e.g. an order number).

A custom object or KObject is a single instance of a Klass. Using the order example, the Klass is Orders, while a KObject might be Order #abc123.

Hooks in Kustomer allow you to trigger workflows with data from an external system. When an order gets created in your order management system for example, you may want to send that data to Kustomer and create an order object in the customer's timeline. For a detailed overview on this, see Understanding Hooks.

Prerequisites

Before you start, there are two requirements:

  1. Define the Klass. From the Klass Settings page, make sure you've set up a custom Klass including the Workflow with custom fields configured.
  2. Create a Hook. Follow the instructions in Understanding Hooks to set up a form, web, or email hook and begin sending data into Kustomer.

Step 1. Identify the data from the hook

To see the available data, use the Workflow logger tool. Make sure your Workflow is enabled, click on “View Logs” at the bottom of the Workflow editor, and send an example request to your hook. Click on the refresh icon in the Workflow logger and if your test request was successful you will see a log appear in the list.

Click into the top log and select step 1 from the list, then copy the “output” of that step and paste it into the “Example Webhook Data” box in the right bar. If you don't see that box, click on your trigger at the top of your Workflow to make it appear. For example, if you send the following data:

{
 "orderId": "1234",
 "price": "$10.25",
 "quantity": 2,
 "email": "test@example.com"
}

You will have an output that resembles the following. Notice that the original data is nested under attributes.data and will be accessible under /#steps.1.attributes.data:

{
 "id": "a5c3694a5d1ab8ffee5b2b0e",
 "type": "transaction",
 "attributes": {
   "createdAt": "2017-12-22T05:23:02.138Z",
   "data": {
     "orderId”: “1234",
     "price": "$10.25",
     "quantity": 2,
     "email": "test@example.com"
   }
 },
 "relationships": {
   "org": {
     "data": {
       "type": "org",
       "id": "581392b55ac7a2110099d9c8"
     },
     "links": {
       "self": "/v1/org/581392b55ac7a2110099d9c8"
     }
   },
   "hook": {
     "data": {
       "type": "form_hook",
       "id": "5a345109e578360010eaa1ad"
     },
     "links": {
       "self": "/v1/hooks/form/5a345109e578360010eaa1ad"
     }
   }
 }
}

Step 2. Find a Customer using the input data

To create a KObject from this data on a customer's timeline, it's first necessary to identify the customer we will link the KObject to. We'll need some identifying information on the KObject, such as an email, phone number, or externalId.

  1. Create a new step and select the Customer: Lookup (By Email) action.
  2. Populate the email field with with /#steps.1.attributes.data.email. This can can also be selected from the dropdown when clicking into the text field.
  3. It's possible that this customer does not yet exist within the Kustomer system, so after looking up the customer, we check if any results were returned. To do so, add a Condition Step to check if the previous step's ID exists. 
  4. Add a Condition Branch to check the opposite condition: that the previous step's ID does not exist.
  5. Under the second branch, create a new step and select Customer: Create. The only relevant field is the email field, which we populate with /#steps.1.attributes.data.email from our trigger data. If the Workflow reaches this branch, it will create a customer if the record did not previously exist within Kustomer.

Step 3. Create a KObject on the Customer's timeline

Now it's time to create the KObject. Since there are two branches for getting the customer's ID (either the customer was found or created), we will need two similar but separate actions for creating the KObject.

Select a branch and add a step with the Custom Object (KObject): Create With Customer action. There are several required fields for a KObject:

  • KlassName: the name of the Klass for the object you want to create. In this example, we will type in order.
  • Customer: the ID of the customer either found or created, you should select the ID from the dropdown of the step preceding the one you created.
  • Title: the display name of the object in the timeline, such as Online Order.
  • Data: a required object field, which will need to be set in the JSON Editor for Workflows.
  • Custom: while not officially required, this field will control what is displayed by default in the UI and what is searchable. It is highly recommended to use this field. Each custom field should use the API name, which can be found on the Klass page – for example, a single line text field named Order ID should have an API name like orderIDStr. Like the data field, custom attributes will also need to be set in the JSON Editor.

To edit the fields in the Workflow JSON, follow the instructions in Calling a REST API Within a Workflow.

Step 4. Save the Workflow

Finally, save your Workflow and test it again. You will now see a new KObject created on the related customer's timeline.

Related Topics