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	Description
`id`	uuid	A unique string for every object
`organization_id`	uuid	The unique UUID for your company
`created_by_user`	uuid	The unique UUID for the user that created the workflow
`updated_by_user`	uuid	The unique UUID for the user that last updated the workflow
`name`	string	The name of this workflow
`description`	string	The description of this workflow
`modified_at`	timestamp	Timestamp of workflow last modified time
`created_at`	timestamp	Timestamp of workflow creation date

Get a single workflow¶

Endpoint:

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

Response¶

The response will be a object like:

Attribute	Type	Description
`id`	uuid	A unique string for every object
`organization_id`	uuid	The unique UUID for your company
`created_by_user`	uuid	The unique UUID for the user that created the workflow
`updated_by_user`	uuid	The unique UUID for the user that last updated the workflow
`name`	string	The name of this workflow
`description`	string	The description of this workflow
`modified_at`	timestamp	Timestamp of workflow last modified time
`created_at`	timestamp	Timestamp of workflow creation date

Create a new workflow¶

Endpoint:

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

Payload:

{
    "name": "Test Objective",
    "description": "Testing creation for new objective",
}

Update a workflow¶

Notice

Sub-items can be patched independently in subsequent requests.

Endpoint:

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

Payload:

{
    "name": "<altered_objective>",
    "description": "<altered_description>",
}

Remove a workflow¶

Notice

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

Endpoint:

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:

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:

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

Payload:

{
    "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:

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

Payload:

{
    "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:

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

Test a business target¶

Endpoint:

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:

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:

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:

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

{
    "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:

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

Payload:

{
    "name": "<altered_name>",
    "target": "<altered_target_uuid>",
    "channel_id": "<altered_channel_uuid>"
}

Remove a Bar notification setting¶

Endpoint:

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:

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:

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

Using token

{
    "target": "<target_uuid>",
    "token": "<string>",
    "channel": "<string>",
    "user": "<string>",
}

Using webhooks

{
    "target": "<target_uuid>",
    "incoming_webhook_url": "<string>",
}

Update a Slack notification setting¶

Notice

Sub-items can be patched independently in subsequent requests.

Endpoint:

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

Using token

{
    "token": "<altered_string>",
    "channel": "<altered_string>",
    "user": "<altered_string>",
}

Using webhooks

{
    "incoming_webhook_url": "<altered_string>",
}

Remove a Slack notification setting¶

Endpoint:

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:

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:

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

{
    "target": "<target_uuid>",
    "email": "<string>",
    "is_bundleable": "<bool>",
}

Update an email notification setting¶

Notice

Sub-items can be patched independently in subsequent requests.

Endpoint:

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

{
    "email": "<altered_string>",
    "is_bundleable": "<altered flag>",
}

Remove an email notification setting¶

Endpoint:

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