Workflow source data download API

Warning

This page may be subject to changes!

This endpoint provides a way to download data on each individual event in each step of the workflow, which is aggragated to make up the data of each step of the workflow. File formats available for downloading are .xlsx (MS Excel 2007 & newer) and .csv since these are two of the most widely & commonly used ones.

To check how to simply query the step source data, check this page

Endpoint

Step source data URL

POST https://api.giosg.com/api/reporting/workflow/v1/orgs/<organization_id>/workflows/<workflow_id>/step/<step_index>/download/

URL attributes

Attribute	Type	Required	Description
organization_id	String (UUID)	Required	ID of the organization for which the data is requested
workflow_id	String (UUID)	Required	ID of the workflow for which the data is requested
step_index	Positive integer	Required	Index of the step for which the data is requested

Payload

{
    "filters":[
        {
            "property": "action", 
            "values": [ "action name" ]
        }
    ],
    "step_data": [
        {},
        {
            "actions": [
                "action name 1",
                "action name 2"
            ]
        },
        {
            "actions": [
                "action name 3"
            ]
        }
    ],
    "interval": {
        "start": "<start_time_ISO8601>",
        "end": "<end_time_ISO8601>",
    },
    "format": "xlsx"
}

Payload attributes

Attribute	Type	Required	Description
filters	Array of filters	Required	An array of filter objects used to filter the response. For example you can use action property in filters to get the data for the particular action. Follow this link for more information about filtering
interval	Interval	Required	Time interval of the query, with start and end being in ISO8601 time format
step_data	Array of objects	Optional	An array of objects that describe the step. If this attribute is omitted for the payload of web navigation and interaction workflows, the API will return all events for the current step regardless of the data shown on the chart. For voice & video, chat and user-generated workflows this attribute is ignored and events returned by the API always correspond to data on the chart
target	String	Optional	String describing if information that is fetched is related to goal or the step action. Accepts default or triggered_goal. Default value is default if omitted from payload.
format	String	Optional	The file format API returns. Can be either csv or xlsx. Anything else will not be accepted & API will return a HTTP status 400. This field can be omitted, in that case the default value will be csv
limit	Positive integer	Optional	A number of rows to return in the response. Must be greater than 0. If this attribute is ommitted, the API will return all relevant data

Payload step_data objects explanation

Each object in the step_data array represents a corresponding step. For example: step_data[0] - corresponds to source step, step_data[1] - corresponds to step 1 and so on. An empty object can be passed for the source step(step_data[0]), as source step data is not used in processing

step_data objects can contain the following attribute:

Attribute	Type	Required	Description
actions	Array of strings	Optional	An array of action identifiers. For different types of workflows this array can contain different types of identifiers. For a web navigation workflow, this array contains page_url values for actions, for interaction workflow this array contains view_uid values for actions

Response

Response for both file formats is almost the same, a Blob containing the raw data. The only difference between the formats is the value of Content-Type in response header.

• For "format"="csv" the value is "Content-Type"="text/csv"
• For "format"="xlsx" the value is "Content-Type"="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"

Successful response does not send any JSON data, just the Blob. However the response for the unsuccessful request will send JSON data and usually describe the problem with the request.

Example response for a request with wrong format field in payload looks like this:

{
  "format": [
    "Format must be 'xlsx' or 'csv'. Change the value or omit the field from payload."
  ]
}

Response HTTP status codes

Warning

This section should be fact-checked before going live!

Endpoint returns the following HTTP status codes:

• 200 if the request was successful
• 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 data was not found
• 406 if filtering with something that is not yet implemented
• 500 if an unexpected error occurred with the query

Example for correct Request / Response

Request

POST https://api.giosg.com/api/reporting/workflow/v1/orgs/<organization_id>/workflows/<workflow_id>/step/<step_index>/download/'

Payload

{
    "filters":[
        {
            "property": "action", 
            "values": [ "User dialed" ]
        }
    ],
    "step_data": [
        {},
        {
            "actions": [
                "User dialed",
                "Visitor dialed"
            ]
        }
    ],
    "interval": {
        "start": "2022-11-03T00:00:00+00:00",
        "end": "2022-11-04T00:00:00+00:00"
    },
    "format": "xlsx"
}

Response

Response will contain Blob with the raw data. It's up to the browser to initiate the download & naming of the file. Example can be found here

Example for wrong Request / Response

Request

POST https://api.giosg.com/api/reporting/workflow/v1/orgs/<organization_id>/workflows/<workflow_id>/step/<step_index>/download/'

Payload

{
    "filters":[
        {
            "property": "action", 
            "values": [ "User dialed" ]
        }
    ],
    "step_data": [
        {},
        {
            "actions": [
                "User dialed",
                "Visitor dialed"
            ]
        }
    ],
    "interval": {
        "start": "2022-11-03T00:00:00+00:00",
        "end": "2022-11-04T00:00:00+00:00"
    },
    "format": "totally-not-valid-format"
}

Response

{
  "format": [
    "Format must be 'xlsx' or 'csv'. Change the value or omit the field from payload."
  ]
}

Example how to handle file download in frontend

Below is a really simple example on how to initiate and handle the download, done in (basically vanilla JS) ES6 using fetch.

<button onclick="handleDownload()">
    Initiate download
</button>
<script>
    const handleDownload = async () => {
        fetch("https://api.giosg.com/api/reporting/workflow/v1/orgs/<organization_id>/workflows/<workflow_id>/step/<step_index>/download/", {
            "headers": {
                "authorization": "Bearer <auth-token>",
                "content-type": "application/json",
            },
            "body": {
                "filters":[
                    {
                        "property": "action", 
                        "values": [ "User dialed" ]
                    }
                ],
                "step_data": [
                    {},
                    {
                        "actions": [
                            "User dialed",
                            "Visitor dialed"
                        ]
                    }
                ],
                "interval": {
                    "start": "2023-02-01T00:00:00+02:00",
                    "end": "2023-02-12T23:59:59+02:00"
                },
                "format": "csv"
            },
            "method": "POST",
        }).then( async (res) => {
            if (res.ok) {
                const blob = await res.blob()
                const fileName = res.headers.get('content-disposition').split("filename=")[1]
                const blobUrl = window.URL.createObjectURL(blob);
                // Workaround to get filename included
                const fileLink = document.createElement("a");
                document.body.appendChild(fileLink)
                fileLink.href = blobUrl
                fileLink.download = fileName
                fileLink.target = "_blank"
                fileLink.click()
                window.URL.revokeObjectURL(blob)
            } else {
                throw new Error(res.statusText)
            }
        }).catch((err) => {
            alert(`Something went wrong with download: ${err}`)
        });
    }
</script>