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.
  • • You can also create profiles in batches with a request to the /v1/retention/profiles/create endpoint.

Note: A maximum of 100 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 batch-create -t profiles -f {path/to/profiles_file.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 50,000 rows (profiles).

Note: It will take a while for the command to complete as the API can only process 100 profiles at a time.


Syntax for nested columns within your customer data csv file:


profile_data>{key} platform_info>{key}
{value} {value}

Specifying the '>' character 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...

customer_id has_charged profile_data>age platform_info>app_version
customer-1234 true 32 5.8

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",
    }
}

Creating Items
  • • Easily create items in batches using the CLI application.
  • • You can also create items in batches with a request to the /v1/retention/items/create endpoint.
  • • A maximum of 100 items can be created in a batch.
  • • Create a single item by making a request to the /v1/retention/items/create endpoint.

This is the easiest and most efficient way of creating items in batches.


CLI

octy-cli batch-create -t items -f {path/to/items_file.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 with this explicit order:


  • item_id
  • item_category
  • item_name
  • item_description
  • item_price

The items .csv file may contain a maximum of 150 rows (items).


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.
  • • Custom event-types can also be created by making a request to the /v1/retention/events/types/create endpoint.
  • • A maximum of 100 custom event-types can be created by making a request to the /v1/retention/events/types/create endpoint.

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 "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 event-types -o set -e {event_type} -p {event_property} -p {event_property}...



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.


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 batch-create -t events -f {path/to/events_file.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.

Note: It will take a while for the command to complete as the API can only process 100 events at a time.


Syntax for nested columns within your events data csv file:


event_properties>{key}
{value}

Specifying the '>' character 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...

event_type profile_id created_at event_properties>device
login profile_1234 2020:12:13 09:30:54 iPhone(iOS)

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 cannot 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 either 'true' or 'false' in the relevant column’s cells. Providing 0/1 or True/False or T/F or 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.