Skip to content

Getting started with Conversational Reporting

Overview

It's recommended that you first read Conversational Reporting concepts.

This tutorial provides you with a quick walkthrough of the creation process for a Conversational Reporting report.

Prerequisites

A guide on how to create an API token can be found here

Once you have obtained your API token(s), define the Authorization HTTP header for all your API requests:

1
Authorization: Token <api_key>

You should replace the <api_key> with your API token

Remember that the api token is connected to the user that created the token, which means that if the user is deleted the api token will also be invalidated. You can create an extra user and create the token with this user, remember to name the user so that it doesn’t get deleted by mistake e.g “Reporting api-user do not delete”

Setting up Conversational Reporting

For having more control over the numbers being reported and means for notifications, one can set up conversational reporting step by step:

Sending events for usage in Conversational Reporting

Now our goal was to send data regarding our leads. So let's think about a situation in which we have a new sale and we want to report that. Lets fill the Generic Event template to be sent to the Generic Event endpoint.

Which metrics can I send?

The idea behind Generic Reporting is that it can accept various types of data. Despite the flexibility we strongly suggest that you don't send any identifiable data for example but not limited to phone numbers, people names or IDs. The sent events cannot be removed or modified in the system.

Caution

The sent events cannot be removed or modified.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
    "events": [
        {
            "event_version": 1,
            "timestamp": "2021-07-22T12:00:12.179Z", // Timestamp when the sale was done
            "organization_id": "<your_organization_uuid>", // Your organization id
            "vendor": "com.company.system", // Origin of the event
            "category": "lead", // Type of the event
            "action": "",
            "label": "",
            "properties": [],
            "value": 1, // Lead amount
            "visitor_id": "<unique visitor ID>"
        }
    ]
}

In this example case there were some fields ("action", "label", etc.) that were not useful in this case and hence we could leave them empty.

This payload example can now be sent to the Generic Reporting API like this: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
import requests

GIOSG_SERVICE_BASE_URL = "https://api.giosg.com"
token = "<your_giosg_account_token>"
organization_id = "<your_organization_uuid>"

event = {
    "events": [
        {
            "event_version": 1,
            "timestamp": "2021-07-22T12:00:12.179Z",
            "organization_id": organization_id,
            "vendor": "com.company.system",
            "category": "lead",
            "action": "",
            "label": "",
            "properties": [],
            "value": 1,
            "visitor_id": "<unique visitor ID>"
        }
    ]
}


def send_lead_to_generic_reporting(event):
    response = requests.post(
        "{}/events/v2/store/internal".format(GIOSG_SERVICE_BASE_URL),
        headers={'Authorization': 'Token ' + token},
    json=event)
    response.raise_for_status()
    return response.json()

send_lead_to_generic_reporting(event)

when this is successfully run, you can use these events further like shown below.

Setting up a workflow

A workflow is a list of tasks that achieve a specific business outcome.

We want this to be reported on using the giosg systems, therefore we can programmatically create this workflow:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import requests

GIOSG_SERVICE_BASE_URL = "https://api.giosg.com"
token = "<giosg account token>"
organization_id = "<uuid>"

json = {
    "name": "Website Lead to Deal",
    "description": "Leads"
}

def create_workflow():
    response = requests.post(
        "{}/api/objectives/v1/orgs/{}/workflows".format(GIOSG_SERVICE_BASE_URL, organization_id),
        headers={'Authorization': 'Token ' + token},
        json=json)
    response.raise_for_status()
    return response.json()

Setting up notifications

To report the conversational reporting targets we will need to dictate where we send these messages to. Conversational reporting currently offers three methods for reporting: giosg, Slack and E-Mail. When creating these notification settings you will need to save the Unique Universal Identifiers (IDs) to assign these notifications to the business report/target.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import requests

GIOSG_SERVICE_BASE_URL = "https://api.giosg.com"
token = "<giosg account token>"
organization_id = "<uuid>"

json = {
    "name": "Reporting Channel",
    "channel_id": "<channel_uuid>"
}

def create_notification_for_target():
    response = requests.post(
        "{}/api/objectives/v1/orgs/{}/notifications/bar".format(GIOSG_SERVICE_BASE_URL, organization_id),
        headers={'Authorization': 'Token ' + token},
        json=json)
    response.raise_for_status()
    return response.json()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import requests

GIOSG_SERVICE_BASE_URL = "https://api.giosg.com"
token = "<giosg account token>"
organization_id = "<uuid>"

json = {
    "name": "Reporting Channel",
    "token": "<string>",
    "channel": "<string>",
    "user": "<string>",
}

def create_notification_for_target():
    response = requests.post(
        "{}/api/objectives/v1/orgs/{}/notifications/slack".format(GIOSG_SERVICE_BASE_URL, organization_id),
        headers={'Authorization': 'Token ' + token},
        json=json)
    response.raise_for_status()
    return response.json()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import requests

GIOSG_SERVICE_BASE_URL = "https://api.giosg.com"
token = "<giosg account token>"
organization_id = "<uuid>"

json = {
    "name": "Reporting Channel",
    "incoming_webhook_url": "<string>",
}

def create_notification_for_target():
    response = requests.post(
        "{}/api/objectives/v1/orgs/{}/notifications/slack".format(GIOSG_SERVICE_BASE_URL, organization_id),
        headers={'Authorization': 'Token ' + token},
        json=json)
    response.raise_for_status()
    return response.json()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import requests

GIOSG_SERVICE_BASE_URL = "https://api.giosg.com"
token = "<giosg account token>"
organization_id = "<uuid>"

json = {
    "email": "your-email-address@gmail.com",
    "is_bundleable": True
}

def create_notification_for_target():
    response = requests.post(
        "{}/api/objectives/v1/orgs/{}/notifications/email".format(GIOSG_SERVICE_BASE_URL, organization_id),
        headers={'Authorization': 'Token ' + token},
        json=json)
    response.raise_for_status()
    return response.json()

Setting a report

giosg Conversational Reporting has two types of reports that can be used:

  • A business report, which gives you a daily report of the metric set by you; (140 shopping carts sold yesterday)
  • A business target, this is a daily report that needs to be tracked to a certain standard. (140/5000 shopping carts sold, 1/50 unique leads gathered etc)

Below you will find an example of both of the reports that can be used.

A business report is a report that allows you to be informed of the metrics that are important to you, you can create as many as you want. For the above example "Website Lead to Deal!" we could use a business report for example: "I would like to see how many leads we get per day.". To track this, we add the following business report to our workflow:

Notice

Keep in mind that these are automatically tracked but standard not reported on, you will have to set a notification setting to report these to your users.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
import requests

GIOSG_SERVICE_BASE_URL = "https://api.giosg.com"
token = "<giosg account token>"
organization_id = "<uuid>"
workflow = "<uuid>"
notifications = ["<uuid>", ...]

query = {
    "granularity": "all",
    "group_by": [],
    "vendor": "com.company.system",
    "aggregations": [
        "count"
    ],
    "filters": {
        "type": "and",
        "fields": [
            {
                "type": "selector",
                "dimension": "category",
                "value": "lead"
            },
        ]
    }
}

json = {
    "name": "Amount of leads",
    "reporting_query": query,
    "reporting_field": "count",
    "reporting_period": "P1D", # Period giosg reports on, P1D = Daily, P1W = Weekly, P1M = Monthly,
    "notification_settings": notifications
}

def create_report_for_workflow():
    response = requests.post(
        "{}/api/objectives/v1/orgs/{}/workflows/{}/reports".format(GIOSG_SERVICE_BASE_URL, organization_id, workflow),
        headers={'Authorization': 'Token ' + token},
        json=json)
    response.raise_for_status()
    return response.json()

A business target is an underlying measurement that points to the performance of a workflow, you can create as many as you want. For the above example "Website Lead to Deal!" we could use a business target for example: "I would like to track the performance of leads and set a target.". To track this, we add the following business target to our workflow:

Notice

Keep in mind that these are automatically tracked but not reported on when the notification settings are not set, you will have to set a notification setting to report these to your users.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
import requests

GIOSG_SERVICE_BASE_URL = "https://api.giosg.com"
token = "<giosg account token>"
organization_id = "<uuid>"
workflow = "<uuid>"
notifications = ["<uuid>", ...]

query = {
    "granularity": "all",
    "group_by": [],
    "vendor": "com.company.system",
    "aggregations": [
        "count"
    ],
    "filters": {
        "type": "and",
        "fields": [
            {
                "type": "selector",
                "dimension": "category",
                "value": "lead"
            },
        ]
    }
}

json = {
    "name": "Amount of leads",
    "reporting_bound": "LOWER",
    "reporting_threshold": 50, # We want 50 leads or more.
    "reporting_query": query,
    "reporting_field": "count",
    "reporting_period": "P1D", # Period giosg reports on, P1D = Daily, P1W = Weekly, P1M = Monthly
    "notification_settings": notifications
}

def create_target_for_workflow():
    response = requests.post(
        "{}/api/objectives/v1/orgs/{}/workflows/{}/target".format(GIOSG_SERVICE_BASE_URL, organization_id, workflow),
        headers={'Authorization': 'Token ' + token},
        json=json)
    response.raise_for_status()
    return response.json()

Conclusion

When the workflow, notification setting and the business target have been successfully set, you will receive a notification at 8 AM local time to your chosen platform. This notification will consist of whether the metric has passed the chosen threshold and what this metric is, for instance 51 out of 50 shopping carts sold.

When this comes in, you have successfully set up Conversational Reporting, enjoy!

Endpoints used in this tutorial

  1. POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows
  2. POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets
  3. POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/reports
  4. POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>
  5. POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/reports/<report_id>
  6. POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/notifications/bar
  7. POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/notifications/slack
  8. POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/notifications/email