Skip to content

Workflow Reporting HTTP API

Notice

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

Overview

Warning

This section needs to be updated!

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

Warning

This section needs to be updated!

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

Workflow report

Warning

Perhaps we should add here a good explanation of what a workflow report and a sankey diagram are, and perhaps it's worth adding some pictures with explanations.

Endpoint

1
POST https://api.giosg.com/api/reporting/workflow/v1/orgs/<organization_id>/workflows/<workflow_id>/query/
Payload
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "filters":[
        {"property": "<property_1_name>", "values": [ "<property_1_value>" ]},
        {"property": "<property_2_name>", "values": [ "<property_2_value>" ]}
    ],
    "interval": {
        "start": "<start_time_ISO8601>",
        "end": "<end_time_ISO8601>"
    }
}
URL attributes
Attribute Type Required Description
organization_id String (UUID) Required ID of the organization for which the report is requested
workflow_id String (UUID) Required ID of the the workflow for which the report is requested
Payload attributes
Root level attributes
Attribute Type Required Description
filters Array of JSON objects Optional Array of filters to be applied to the workflow report (See detailed explanation in a separate section below)
interval JSON object Required Specifies the time range to the query
"filters" objects attributes
Attribute Type Required Description
property String Required Name of the property to which the filter will be applied
values Array(String / Int) Required Array of values to search in the corresponding filter property
"interval" object attributes
Attribute Type Required Description
start String Required The start timestamp of the interval for the request. Value should be timestamp in ISO8601 format. You can give timestamp with offset, for example: 2019-01-30T16:32:17.879+02:00. Start time is inclusive
end String Required The end timestamp of the interval for the request. Value should be timestamp in ISO8601 format. You can give timestamp with offset, for example: 2019-01-30T16:32:17.879-02:00. End time is exclusive
HTTP response status codes

Endpoint returns the following HTTP status codes:

  • 200 if the request was successful
  • 200 if no data matching the query was found, in this case the API will return the response as follows:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "id": "2b37c4f9-5477-4624-8e34-be7853d0b653",
    "organization_id": "7e41df75-1264-4ae0-a5ae-213636401a39",
    "name": "page navigation",
    "description": null,
    "interval": {
        "start": "2022-08-16T00:00:00+03:00",
        "end": "2022-08-16T23:59:59+03:00"
    },
    "filters": null,
    "first_step_id": null,
    "steps": [],
    "actions": [],
    "flows": []
}
  • 400 if an error occurred while validating the request parameters (for example wrong UUID format in URL)
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reporting permission
  • 404 if no workflow for given UUID is found
  • 500 if an unexpected error occurred with the query
1
2
3
4
5
6
7
!!! warning
    Perhaps we should change `if no data matching the query was found` and `if an unexpected error occurred with the query` error codes to something more appropriate

#### An example request

```string
    POST https://api.giosg.com/api/reporting/workflow/v1/orgs/e40bcb66-8c63-4aa7-8d81-68d8e8cef907/workflows/d3f3323f-9787-4abd-850d-9b9b3a5cc6f9/query/
An Example Payload
1
2
3
4
5
6
{
    "interval": {
        "start": "2022-08-16T00:00:00+03:00",
        "end": "2022-08-17T00:00:00+03:00"
    }
}

An example response

  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
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
{
    "id": "2b37c4f9-5477-4624-8e34-be7853d0b653",
    "organization_id": "5c2a0cb9-3b51-41dd-98c6-04d17db492a6",
    "name": "page navigation",
    "description": null,
    "interval": {
        "start": "2022-08-16T00:00:00+03:00",
        "end": "2022-08-16T23:59:59+03:00"
    },
    "filters": null,
    "first_step_id": "2238ca8a-505c-11ed-a4b1-5719f5e76650",
    "steps": [
        {
            "id": "2238ca8a-505c-11ed-a4b1-5719f5e76650",
            "name": "source",
            "value": null,
            "description": null,
            "next_step_id": "2238ca8f-505c-11ed-a4b1-5719f5e76650"
        },
        {
            "id": "2238ca8f-505c-11ed-a4b1-5719f5e76650",
            "name": "1st pageview",
            "value": "253",
            "description": null,
            "next_step_id": "2419c822-505c-11ed-a4b1-5719f5e76650"
        },
        {
            "id": "2419c822-505c-11ed-a4b1-5719f5e76650",
            "name": "2nd pageview",
            "value": "77",
            "description": null,
            "next_step_id": null
        }
    ],
    "actions": [
        {
            "id": "2238ca8b-505c-11ed-a4b1-5719f5e76650",
            "step_id": "2238ca8a-505c-11ed-a4b1-5719f5e76650",
            "name": "direct",
            "description": null,
            "rooms": [],
            "value": "96",
            "unique_visitor_count": "48"
        },
        {
            "id": "2238ca8c-505c-11ed-a4b1-5719f5e76650",
            "step_id": "2238ca8a-505c-11ed-a4b1-5719f5e76650",
            "name": "search | Google",
            "description": "www.google.com",
            "rooms": [],
            "value": "28",
            "unique_visitor_count": "14"
        },
        {
            "id": "2238ca8d-505c-11ed-a4b1-5719f5e76650",
            "step_id": "2238ca8a-505c-11ed-a4b1-5719f5e76650",
            "name": "website",
            "description": "somesite.com",
            "rooms": [],
            "value": "4",
            "unique_visitor_count": "3"
        },
        {
            "id": "2238ca8e-505c-11ed-a4b1-5719f5e76650",
            "step_id": "2238ca8a-505c-11ed-a4b1-5719f5e76650",
            "name": "other",
            "description": null,
            "rooms": [],
            "value": "129",
            "unique_visitor_count": "100"
        },
        {
            "id": "232c6b68-505c-11ed-a4b1-5719f5e76650",
            "step_id": "2238ca8f-505c-11ed-a4b1-5719f5e76650",
            "name": "Home | Example",
            "description": "https://www.example.com/",
            "rooms": [
                "e7209df8-59df-4340-94cb-7d1287d8d37b",
                "a7d439b4-c9b6-431d-b516-9f2ef54e73dc",
                "5d6e1547-cba3-411e-9c9f-4af3d17f31be"
            ],
            "value": "205",
            "unique_visitor_count": "50"
        },
        {
            "id": "232c6b6c-505c-11ed-a4b1-5719f5e76650",
            "step_id": "2238ca8f-505c-11ed-a4b1-5719f5e76650",
            "name": "Events | Example",
            "description": "https://www.example.com/events",
            "rooms": [
                "e7209df8-59df-4340-94cb-7d1287d8d37b",
                "a7d439b4-c9b6-431d-b516-9f2ef54e73dc",
                "5d6e1547-cba3-411e-9c9f-4af3d17f31be"
            ],
            "value": "43",
            "unique_visitor_count": "16"
        },
        {
            "id": "232c6b70-505c-11ed-a4b1-5719f5e76650",
            "step_id": "2238ca8f-505c-11ed-a4b1-5719f5e76650",
            "name": "Videos | Example",
            "description": "https://subdomain.example.com/videos",
            "rooms": [
                "e7209df8-59df-4340-94cb-7d1287d8d37b",
                "a7d439b4-c9b6-431d-b516-9f2ef54e73dc",
                "5d6e1547-cba3-411e-9c9f-4af3d17f31be"
            ],
            "value": "5",
            "unique_visitor_count": "2"
        },
        {
            "id": "2419c823-505c-11ed-a4b1-5719f5e76650",
            "step_id": "2419c822-505c-11ed-a4b1-5719f5e76650",
            "name": "Log in | Example",
            "description": "https://example.com/login",
            "rooms": [
                "e7209df8-59df-4340-94cb-7d1287d8d37b",
                "a7d439b4-c9b6-431d-b516-9f2ef54e73dc",
                "5d6e1547-cba3-411e-9c9f-4af3d17f31be"
            ],
            "value": "67",
            "unique_visitor_count": "13"
        },
        {
            "id": "256a3f68-505c-11ed-a4b1-5719f5e76650",
            "step_id": "2419c822-505c-11ed-a4b1-5719f5e76650",
            "name": "Join | Example",
            "description": "https://subdomain.example.com",
            "rooms": [
                "e7209df8-59df-4340-94cb-7d1287d8d37b",
                "a7d439b4-c9b6-431d-b516-9f2ef54e73dc",
                "5d6e1547-cba3-411e-9c9f-4af3d17f31be"
            ],
            "value": "6",
            "unique_visitor_count": "2"
        },
        {
            "id": "256a3f6b-505c-11ed-a4b1-5719f5e76650",
            "step_id": "2419c822-505c-11ed-a4b1-5719f5e76650",
            "name": "Contacts | Example",
            "description": "https://www.example.com/contacts",
            "rooms": [
                "e7209df8-59df-4340-94cb-7d1287d8d37b",
                "a7d439b4-c9b6-431d-b516-9f2ef54e73dc",
                "5d6e1547-cba3-411e-9c9f-4af3d17f31be"
            ],
            "value": "4",
            "unique_visitor_count": "3"
        }
    ],
    "flows": [
        {
            "id": "232c6b69-505c-11ed-a4b1-5719f5e76650",
            "value": "81",
            "source_action_id": "2238ca8b-505c-11ed-a4b1-5719f5e76650",
            "target_action_id": "232c6b68-505c-11ed-a4b1-5719f5e76650"
        },
        {
            "id": "232c6b6a-505c-11ed-a4b1-5719f5e76650",
            "value": "17",
            "source_action_id": "2238ca8c-505c-11ed-a4b1-5719f5e76650",
            "target_action_id": "232c6b68-505c-11ed-a4b1-5719f5e76650"
        },
        {
            "id": "232c6b6b-505c-11ed-a4b1-5719f5e76650",
            "value": "107",
            "source_action_id": "2238ca8e-505c-11ed-a4b1-5719f5e76650",
            "target_action_id": "232c6b68-505c-11ed-a4b1-5719f5e76650"
        },
        {
            "id": "232c6b6d-505c-11ed-a4b1-5719f5e76650",
            "value": "10",
            "source_action_id": "2238ca8b-505c-11ed-a4b1-5719f5e76650",
            "target_action_id": "232c6b6c-505c-11ed-a4b1-5719f5e76650"
        },
        {
            "id": "232c6b6e-505c-11ed-a4b1-5719f5e76650",
            "value": "11",
            "source_action_id": "2238ca8c-505c-11ed-a4b1-5719f5e76650",
            "target_action_id": "232c6b6c-505c-11ed-a4b1-5719f5e76650"
        },
        {
            "id": "232c6b6f-505c-11ed-a4b1-5719f5e76650",
            "value": "22",
            "source_action_id": "2238ca8e-505c-11ed-a4b1-5719f5e76650",
            "target_action_id": "232c6b6c-505c-11ed-a4b1-5719f5e76650"
        },
        {
            "id": "232c6b71-505c-11ed-a4b1-5719f5e76650",
            "value": "5",
            "source_action_id": "2238ca8b-505c-11ed-a4b1-5719f5e76650",
            "target_action_id": "232c6b70-505c-11ed-a4b1-5719f5e76650"
        },
        {
            "id": "232c6b72-505c-11ed-a4b1-5719f5e76650",
            "value": "4",
            "source_action_id": "2238ca8d-505c-11ed-a4b1-5719f5e76650",
            "target_action_id": "232c6b70-505c-11ed-a4b1-5719f5e76650"
        },
        {
            "id": "2419c824-505c-11ed-a4b1-5719f5e76650",
            "value": "47",
            "source_action_id": "232c6b68-505c-11ed-a4b1-5719f5e76650",
            "target_action_id": "2419c823-505c-11ed-a4b1-5719f5e76650"
        },
        {
            "id": "2419c825-505c-11ed-a4b1-5719f5e76650",
            "value": "20",
            "source_action_id": "232c6b6c-505c-11ed-a4b1-5719f5e76650",
            "target_action_id": "2419c823-505c-11ed-a4b1-5719f5e76650"
        },
        {
            "id": "256a3f69-505c-11ed-a4b1-5719f5e76650",
            "value": "4",
            "source_action_id": "232c6b68-505c-11ed-a4b1-5719f5e76650",
            "target_action_id": "256a3f68-505c-11ed-a4b1-5719f5e76650"
        },
        {
            "id": "256a3f6a-505c-11ed-a4b1-5719f5e76650",
            "value": "2",
            "source_action_id": "232c6b6c-505c-11ed-a4b1-5719f5e76650",
            "target_action_id": "256a3f68-505c-11ed-a4b1-5719f5e76650"
        },
        {
            "id": "268671fa-505c-11ed-a4b1-5719f5e76650",
            "value": "4",
            "source_action_id": "232c6b68-505c-11ed-a4b1-5719f5e76650",
            "target_action_id": "256a3f6b-505c-11ed-a4b1-5719f5e76650"
        }
    ]
}
Response attributes
Root level attributes
Attribute Type Description
id String (UUID) ID of the the workflow for which the report was generated
organization_id String (UUID) ID of the organization for which the report was generated
name String Workflow name
description String (or null) Workflow description
interval JSON object The time interval that was used for the report
filters Array of JSON objects (or null) List of filters that were used for the report
first_step_id String (UUID) ID of the first step in the report
steps Array of JSON objects Array of steps in the report
actions Array of JSON objects Array of actions in the report
flows Array of JSON objects Array of flows in the report
"interval" object attributes
Attribute Type Description
start String The start timestamp of the interval for the report. Start time is inclusive
end String The end timestamp of the interval for the report. End time is exclusive
"filters" objects attributes
Attribute Type Description
property String Name of the property to which the filter was applied
values Array(String or Int) Array of values by which the corresponding filter property was searched
"steps" objects attributes
Attribute Type Description
id String (UUID) Unique ID of the step. This value is not stored anywhere in the database and changes with each subsequent request
name String The name of the step
value String (or null) This is the sum of the values of all the corresponding steps. This attribute can be null, for example, for the source step
description String (or null) Step description. This attribute is reserved for future use and is currently always null
next_step_id String (UUID) (or null) The ID of the next step. This attribute is null for the last step of the report
"actions" objects attributes
Attribute Type Description
id String (UUID) Unique ID of the action. This value is not stored anywhere in the database and changes with each subsequent request
step_id String (UUID) ID of the corresponding step
name String The name of the action. For example, for the "Page navigation" workflow report this is the title of the viewed page
description String (or null) More detailed information about the action. For example, for the "Page navigation" workflow report this is the URL of the viewed page
rooms Array (String) Array of room IDs that were seen in the events related to the action
value String This is the number of events corresponding to the action. For example, for the "Page navigation" workflow report this is the number of page views
unique_visitor_count String This is number of unique visitors that undertake the actions, this counts the visitors based on their unique ID
"flows" objects attributes
Attribute Type Description
id String (UUID) Unique ID of the flow. This value is not stored anywhere in the database and changes with each subsequent request
value String This is a number of events corresponding to the flow from the action with the source_action_id to the action with the target_action_id
source_action_id String (UUID) ID of the source action
target_action_id String (UUID) ID of the target action