Skip to content

Conversational Reporting HTTP API

Notice

This API is a draft and might change in the near future.

Warning

Conversational Reporting can only be used with Generic Reporting at this moment. This will change in the near future.

Overview

With Conversational Reporting, you can set an arbitrary workflow with a target that can be monitored through the Giosg System. This system will send out a notification to the setup user when the target has been reached at a time of their convenience.

Workflow

The workflow is an objective that the user wants to track within the Giosg Systems. One workflow can contain multiple Targets which are smaller parts of the objective. For example objective can be 'Double the yearly revenue' and it's Targets could be 'Increase the monthly sales by 30%' and 'Halve the monthly customer churn'

List all workflows

Endpoint:

1
GET https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows
Response

The response will be a list with objects like:

Attribute Type Required Description
id uuid Required A unique string for every object
organization_id uuid Required The unique UUID for your company
created_by_user uuid Required The unique UUID for the user that created the workflow
updated_by_user uuid Required The unique UUID for the user that last updated the workflow
name string Required The name of this workflow
description string Required The description of this workflow

Create a new workflow

Endpoint:

1
POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows

Payload:

1
2
3
4
{
    "name": "Test Objective",
    "description": "Testing creation for new objective",
}

Update a workflow

Notice

Sub-items can be patched independently in subsequent requests.

Endpoint:

1
PATCH https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>

Payload:

1
2
3
4
{
    "name": "<altered_objective>",
    "description": "<altered_description>",
}

Remove a workflow

Notice

Removing a workflow will remove all underlying business targets and notification settings.

Endpoint:

1
DELETE https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>

Business Target

For each Workflow a user can set multiple targets, these targets are being tracked by the Conversational Reporting.

List all business targets

Endpoint:

1
GET https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets
Response

The response will be a list with objects like:

Attribute Type Description
id uuid A unique UUID for every object
organization_id uuid The unique UUID for your company
workflow uuid The unique UUID for the workflow this target is attached to
name string The name of the target the user wants to know about
reporting_threshold float The threshold which the target should pass
reporting_query JSON The query to gather events to check against
reporting_field string The name of the field which holds the value to check against in the druid query
reporting_period string The period("P1D", "P1W", "P1M") in ISO 8601 duration format which this reporting should be tracked
notification_period string The period("P1D", "P1W", "P1M") in ISO 8601 duration format which snapshots should be sent
reporting_datasource string The datasource("GENERIC_REPORTING", "CHAT_SESSIONS", "VISITOR_SESSIONS") to which the request should be sent
reporting_bound string Checks whether the druid value is < per UPPER bound, or >= per LOWER bound
are_notifications_active boolean A flag to set notifications on or off.
target_active_from date/time (Optional) Timestamp when target will be activated in ISO-8601 format, eg. 2021-04-01T10:10:57.242Z
target_active_until date/time (Optional) Timestamp when target will be activated in ISO-8601 format, eg. 2021-04-01T10:10:57.242Z

Create a new business target

Warning

The reporting query can only support metrics coming from Generic Reporting.

Endpoint:

1
POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets

Payload:

 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
{
    "name": "Amount of workflows created in one day",
    "reporting_bound": "LOWER",
    "reporting_threshold": 10,
    "reporting_query": {
        "granularity": "all",
        "group_by": [
            "organization_id"
        ],
        "vendor": "com.giosg.bolivar",
        "aggregations": [
            "count"
        ],
        "filters": {
            "type": "and",
            "fields": [
                {
                    "type": "selector",
                    "dimension": "label",
                    "value": "workflow"
                }
            ]
        }
    },
    "reporting_field": "count",
    "reporting_period": "P1D",
    "target_active_from": "<datetime>",
    "target_active_until": "<datetime>"
}

Update a business target

Notice

Sub-items can be patched independently in subsequent requests.

Endpoint:

1
PATCH https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>

Payload:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "name": "<altered_name>",
    "reporting_bound": "<altered_bound>",
    "reporting_threshold": "<altered_threshold>",
    "reporting_query": "<altered_query>",
    "reporting_field": "<altered_field>",
    "reporting_period": "<altered_period>",
    "target_active_from": "<altered_datetime>",
    "target_active_until": "<altered_datetime>"
}

Remove a business target

Notice

Removing a business target will remove all underlying notification settings.

Endpoint:

1
DELETE https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>

Test a business target

Endpoint:

1
GET https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>/test
Response
Attribute Type Description
workflow string The name of the workflow which the target is attached to.
target string The name of the target.
selected_period string The period("P1D", "P1W", "P1M") in ISO 8601 for the duration format which notifications should be sent.
timespan_requested string The timespan based on selected_period, the value will be based on this timespan.
value float The current value for the aggregation of events reported for this target

Notification

Endpoint:

1
GET https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>/notifications
Response

The response will be a list with objects like:

Attribute Type Description
bar list Shows all settings for the BAR channels set for this business target
slack list Shows all settings for the Slack channels set for this business target
email list Shows all settings for the Email notifications set for this business target

BAR

Get all bar settings

Endpoint:

1
GET https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>/notifications/bar
Response

The response will be a list with objects like:

Attribute Type Description
id uuid A unique UUID for every object
target uuid The target UUID to which this setting belongs
organization_id uuid The organization UUID for the organization owning this setting
last_notification_sent date/time When is the last notification sent to the channel in ISO-8601 format, eg. 2021-04-01T10:10:57.242Z
name string Name for the notification setting
is_notification_active boolean Flag to enable or disable these notifications
channel_id uuid The UUID for the chat within BAR to gather the Reporting Cards
Set a notification to BAR

Endpoint:

1
POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>/notifications/bar
1
2
3
4
5
{
    "name": "Reporting channel",
    "target": "<target_uuid>",
    "channel_id": "<channel_uuid>"
}
Update a BAR notification setting

Notice

Sub-items can be patched independently in subsequent requests.

Endpoint:

1
PATCH https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>/notifications/bar/<setting_id>

Payload:

1
2
3
4
5
{
    "name": "<altered_name>",
    "target": "<altered_target_uuid>",
    "channel_id": "<altered_channel_uuid>"
}
Remove a Bar notification setting

Endpoint:

1
DELETE https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>/notifications/bar/<setting_id>

Slack

Get all slack settings

Endpoint:

1
GET https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>/notifications/slack
Response

Warning

NOTE: Either (1) or (2) will be set in the response, you can not mix these when setting the object.

The response will be a list with objects like:

Attribute Type Description
id uuid A unique UUID for every object
target uuid The target UUID to which this setting belongs
organization_id uuid The organization UUID for the organization owning this setting
last_notification_sent date/time When is the last notification sent to the channel in ISO-8601 format, eg. 2021-04-01T10:10:57.242Z
name string Name for the notification setting
is_notification_active boolean Flag to enable or disable these notifications
token string (1) Slack token to authenticate to Slack with
channel string (1) Slack channel to send the notification to
user string (1) Slack user to send the notification as
icon_url string (2) The Icon url for sending to slack
incoming_webhook_url string (2) The webhook url for sending notification to slack
Set a notification to Slack

Endpoint:

1
POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>/notifications/slack
1
2
3
4
5
6
{
    "target": "<target_uuid>",
    "token": "<string>",
    "channel": "<string>",
    "user": "<string>",
}
1
2
3
4
{
    "target": "<target_uuid>",
    "incoming_webhook_url": "<string>",
}
Update a Slack notification setting

Notice

Sub-items can be patched independently in subsequent requests.

Endpoint:

1
PATCH https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>/notifications/slack/<setting_id>
1
2
3
4
5
{
    "token": "<altered_string>",
    "channel": "<altered_string>",
    "user": "<altered_string>",
}
1
2
3
{
    "incoming_webhook_url": "<altered_string>",
}
Remove a Slack notification setting

Endpoint:

1
DELETE https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>/notifications/slack/<setting_id>

Email

Get all email settings

Endpoint:

1
GET https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>/notifications/email
Response

The response will be a list with objects like:

Attribute Type Description
id uuid A unique UUID for every object
target uuid The target UUID to which this setting belongs
organization_id uuid The organization UUID for the organization owning this setting
last_notification_sent date/time When is the last notification sent to the channel in ISO-8601 format, eg. 2021-04-01T10:10:57.242Z
name string Name for the notification setting
is_notification_active boolean Flag to enable or disable these notifications
email string Gets the email registered in this setting
is_bundleable boolean Flag to enable or disable bundling of emails
Set a notification to email

Endpoint:

1
POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>/notifications/email
1
2
3
4
5
{
    "target": "<target_uuid>",
    "email": "<string>",
    "is_bundleable": "<bool>",
}
Update an email notification setting

Notice

Sub-items can be patched independently in subsequent requests.

Endpoint:

1
PATCH https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>/notifications/email/<setting_id>
1
2
3
4
{
    "email": "<altered_string>",
    "is_bundleable": "<altered flag>",
}
Remove an email notification setting

Endpoint:

1
DELETE https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/workflows/<workflow_id>/targets/<target_id>/notifications/email/<setting_id>