Creating Resources

Creating Resources

All resource-type: profiles, items and events are either created in batches using your pre-existing data, or created individually as they occur in real time. Initially you should create data in batches to ensure the training jobs have a sufficient amount of data to generate accurate models.
Next you will create each resource-type live, by setting requests to the Octy API throughout the relevant sections of your system.
 

Creating Profiles

  • Easily create profiles in batches using the CLI application.
  • A maximum of 500 profiles can be created in a batch.
  • To create single profiles, for instance, when you acquire a new customer, you simply make a request to the /v1/retention/profiles/create ↗️  endpoint.
 
At least one singular key-value pair must be provided for both the profile_data and platform_info parameters. For example: the profile_data parameter, key : "age" and value : "30" (type : integer).
Using the above example; If you create a subsequent profile with the key : "age" within the profile_data parameter the data-type must be an integer.
To change the data-type associated with an existing key within the profile_data or platform_info attributes across all profiles, you must remove all key-value pairs from each of the profile_data or platform_info attributes from all existing profiles where applicable. This is achieved by updating ALL the profiles containing the specific key-value pairs.
Please use the /v1/retention/profiles/update ↗️  endpoint to make this desired change.
 
🖥️ CLI
octy-cli upload profiles -f {path/to/profiles.csv}
 
When specifying an input file containing your profiles data, the CLI application accepts a file of type .csv (comma separated values) with the following mandatory column headers with this explicit order:
  • customer_id
  • has_charged
  • profile_data*
  • platform_info*
*nested value columns
 
The profiles .csv file may contain a maximum of 100,000 rows (profiles).
💡
Depending on the number of rows provided, it may take a while for the command to complete as the API can only process 500 profiles per request.
 
Syntax for nested columns within your customer data csv file:
notion image
 
Specifying the '>>' characters in a profile_data or platform_info column header signals to the CLI application that the values in that column should be nested within the profile_data or platform_info objects with each request.
 
Essentially the CLI converts the data provided in the customer data csv file into JSON objects that are subsequently sent directly to the /v1/retention/profiles/create ↗️ endpoint.
 
For example, the following customer csv row...
notion image
 
Would be converted by the CLI to the following profile JSON object to be processed by the API.
{ 
    "customer_id" : "customer-1234", 
    "has_charged" : true, 
    "profile_data": {
        "age": 32
    },
    "platform_info": {
        "app_version": "5.8",
    }
}
 

Profile identification & merging

In order to track and merge unauthenticated anonymous customer sessions with Octy, anonymous customer identifiers should be generated client-side. This approach of creating anonymous customer profiles is required when there are scenarios in which your customers can interact with your platform without being authenticated.
Every 48 hours the Octy profile identification module merges anonymous and authenticated-known profiles, including their respective event instances and profile attributes. Profiles are merged by matching the value of the specified authenticated_id_key set in each anonymous profile profile_data attribute. You can specify the name of the authenticated_id_key that the Octy profile identification module will use to merge profiles by updating the authenticated_id_key attribute in your account configurations /v1/configurations/account/set ↗️  or via the CLI.
 
💡
Please note that If this configuration is not set, profile identification and merging will not be conducted.
 
When merged, profiles fall into one of two categories; parent profiles or child profiles.
A parent profile is a profile that has consumed other profiles that shared the same authenticated_id_key value. A child profile is a profile that has been consumed by another profile (a parent profile) that shared the same authenticated_id_key value. Our algorithm determines which profiles will become parent profiles and which will become child profiles based on a number of factors including the age of a profile, the number of relevant attributes associated with a profile and the number of segment tags associated with a profile.
Your systems are responsible for keeping all Octy profile references up to date.
The output of a profile identification & merging job will be sent via webhook to your specified account webhook URL allowing your system to update or delete stale profiles and persisting parent profiles and other relevant information.
You can also check the merge status of any profile at any time via the /v1/profiles/metadata ↗️  endpoint.
 
Example flow:
notion image
 
For a more comprehensive example of implementing of this flow, please see the demo Shopify application here → https://github.com/Octy-ai/octy-shopify#octy-demo-flow-diagrams
 

Creating Items

  • Easily create items in batches using the CLI application.
  • A maximum of 500 items can be created in a batch.
This is the easiest and most efficient way of creating items in batches.
 
🖥️ CLI
octy-cli upload items -f {path/to/items.csv}
 
When specifying an input file containing your item data, the CLI application accepts a file of type .csv (comma separated values) with the following mandatory column headers in this explicit order:
  • item_id
  • item_category
  • item_name
  • item_description
  • item_price
The items .csv file may contain a maximum of 500 rows (items).
💡
Depending on the number of rows provided, it may take a while for the command to complete as the API can only process 500 items per request.
 

Custom and System event types

 
Custom event types
Octy allows you to define your own custom event-types. Once created, you can track event instances of this type. You cannot create duplicate event-types or create an event-type with the same name of a system event-type.
  • Custom event-types can be created using the CLI application.
  • A single CLI command creates a maximum of 1 event-type.
 
When creating custom event-types, you must supply at least one event property name that will be required as a parameter when creating event instances of this type. For example, if you created the custom event-type “login” with a required event property within the event_properties parameter called "device", all future event instances of the type “login” would HAVE TO specify the key “device” with a relative value within its event_properties parameter.
Example custom event-type “login”: (THIS CREATES A NEW EVENT TYPE CALLED “LOGIN”)
{
    "event_type" : "login",
    "event_properties" : [
        "device"
    ]
}
Example event instance with a custom event-type “login”: (THIS CREATES AN EVENT INSTANCE OF TYPE “LOGIN”)
{
    "event_type" : "login",
    "event_properties" : {
        "device" : "iPhone"
    }
}
 
🖥️ CLI
octy-cli apply --filepath {path/to/event-type-definitions.yml}
Example event-type-definitions.yml :
kind: eventTypes
eventTypeDefinitions :
    - eventType: login
      eventProperties:
        - device
        - time

    - eventType: logout
      eventProperties:
        - device

    - eventType: watched_video
      eventProperties:
        - video_id

    - eventType: showed_love
      eventProperties:
        - page_id
 
System event types
In addition to custom event-types, Octy has three predefined system event-types:
  • charged
  • churned
  • complaint
 
When event instances of system event-types are created, they trigger predetermined actions and have pre-determined event_properties that are required for training data used to train various models.
 
For example :
  • When tracking purchases, the "charged" system event-type will set the is_charged attribute to "true" for the profile that conducted the “charged” event.
  • The "churned" system event-type will set the status attribute to "churned" of the profile that conducted an event of this type.
 
System event-types should be used where appropriate, for example “charged” is a system event-type and should be used to track your customers purchases. Avoid creating custom event-types that represent the same definitions of any system event-types.
For example: if you created a custom event-type named “purchases” and used this event-type to track your customers purchases, you would be circumventing the desired actions associated with the system event-type “charged” as per above.
This circumvention would lead to inferior training datasets/models and incorrect attributes being present in your customers profiles.
 

Creating Events

💡
Note: Before creating event instances, you should first ensure that the event-type, you are creating an event instance for, already exists. If it does not exist, then you should first define it as a custom event-type.
 
  • Easily create events, of a single event-type, in batches using the CLI application.
 
When creating events in batches, you have the option to supply a backdated timestamp with the created_at parameter using the format: YYYY-MM-DD HH:MM:SS
If left blank, the created_at attribute will be set to the current date and time. Please note that events with a backdated timestamp older than one year will be redundant as they are not included in any training jobs datasets.
 
When creating events either in batches or individually, you must supply values for the event_properties defined for that event-type.
 
For example if you wanted to create an event instance of the event-type “login” (a previously defined custom event-type, with an event property “device”) you would HAVE TO specify the key “device” with a relative value, within the event references event_properties parameter as portrayed in the example JSON object below.
 
{
    "event_type" : "login",
    "event_properties" : {
        "device" : "iPhone"
    }
}
 
Referencing the above example JSON object; If you created a subsequent event of type “login” with the event property key : "device" within the event_properties parameter, the data-type of the value provided would have to be a string. The data-type of an event property for any specific event-type can not be changed once set.
 
Both the "charged" and "complaint" system event-types have required event properties that values must be provided for when creating event instances of these types.
 
Charged required event properties:
  • payment_method string (the name of a payment method)
  • item_id string (an item identifier)
 
Complaint required event properties:
  • channel string (the name of the channel that the customer made a complaint through)
 
🖥️ CLI
octy-cli upload events -f {path/to/events.csv}
When specifying an input file containing your events data, the CLI application accepts a file of type .csv (comma separated values) with the following mandatory column headers with this explicit order:
  • event_type
  • profile_id
  • created_at
  • event_properties*
*nested value column
 
Your "events" csv file may contain up to 100,000 rows, where each row represents an event object of the same event_type.
💡
Depending on the number of rows provided, it may take a while for the command to complete as the API can only process 500 events per request.
 
Syntax for nested columns within your events data csv file:
notion image
 
Specifying the '>>' characters in an event_properties column header signals to the CLI application that the values in that column should be nested within the event_properties objects with each request.
 
Essentially the CLI converts the data provided in the events data csv file into JSON objects that are subsequently sent directly to the /v1/retention/events/create/batch ↗️  endpoint.
 
For example, the following events csv row...
notion image
Would be converted by the CLI to the following event JSON object to be processed by the API.
{
    "event_type" : "login",
    "profile_id" : "profile_1234",
    "created_at": "2020:12:13 09:30:54",
    "event_properties": {
       "device": "iPhone(iOS)",
    }
}
 
💡
Note: Data-types can not be explicitly specified in a csv file. The CLI application will parse the data provided to the correct data-types for each endpoints object schema. If parsing fails, the CLI will assume the incorrect or inconsistent data-types have been provided for specific columns (You will be notified if this occurs). For Boolean values, please provide on of the following accepted boolean representations: True,TRUE, true, t,T, False, FALSE, false, f, F in the relevant column’s cells. Providing any other Boolean representation will result in the incorrect data-type being set for this column’s values
 

Next steps

Now that pre-existing data has been provided and all the points in your system have the required requests added to capture live resources, it's time to move on to creating segment definitions.
Go to the Segmentation 🔗 section of this documentation to learn more about how segmentation works.