Specification
The Flow Results specification builds on the Data Package specification. Thus a Flow Results Data Package must be a Data Package and conform to the Data Package specification.
Additionally, a Flow Results data package must conform to these additional requirements:
Components
A Flow Results data package consists of one Descriptor, which contains exactly one Resource describing the interaction results.
Descriptor
The Descriptor JSON object must contain the following required metadata properties:
The following metadata properties are recommended, consistent with the Data Packages specification:
Resource
The Resource describes the interaction results. The Resource must conform to the Data Package Resource specification. Additionally:
Inline data (data in JSON format within the Descriptor) must not be used. This means that either a file path
or api_data_url
must be provided for the Resource.
The access_method
of the Resource is an optional parameter, and can be either api
or file
:
If the
access_method
isfile
, it indicates all responses are available in a static JSON file. (The default if this parameter is not provided isfile
.) When data is available via file semantics, the Resourcepath
shall be a file reference or URL for the complete response data.If the
access_method
isapi
, it indicates the resource can be queried using the API Usage specification, with support for pagination and filtering. The Resourceapi_data_url
must be provided with the Responses URL on the API server.
The schema
property of the resource must be provided inline, and must not use an external schema file or URL.
The schema
property must contain a fields
object describing the 6 columns within the Resource data. These fields are common to all Flow Results Packages, but are provided here for compatibility with software designed to dynamically read Tabular Data Resources:
Question object
The schema
property must additionally contain a questions
object describing metadata for all the Questions pertaining to Responses in this package. The object identifier (e.g.: 'ae54d3') of questions in this object connects to the Question ID found in each Response row:
The following properties are required for each question:
The following properties are optional for each question:
The schema
property may optionally contain a language
property. If provided, this must be in the form of ISO 639-3, describing the language of the labels in the questions
object. Localization of these labels is left outside the scope of the Flow Results specification.
Resource Data (found at external path)
The Resource path
file (or the api_data_url
endpoint) must provide the Response data in JSON "row array" format, as shown in the following example:
The Resource must be valid JSON according to RFC 7159. No enhancements or constraints are added beyond the JSON specification.
Each row array shall provide exactly 7 elements ("columns") describing a single Response from a Contact. In order, the columns represent:
Results Versioning
A common occurrence for users is to make minor changes to an underlying flow that has already started collecting data, and to desire for data collected under new and old versions to be reported/aggregated together. (Examples of these minor changes include adding a new question to a flow, or removing a question.) The Flow Results specification provides vendor-optional support for limited changes to flow versions. Implementations may choose to support this functionality or not.
Option 1: No version aggregation under a Package id
; each change to a flow creates a new package
id
; each change to a flow creates a new packageImplementations may choose this approach if they do not want to implement any aggregation of responses across multiple versions of a flow, and prefer to leave this aggregation as the responsibility of client software. In this approach, any changes to the schema of a flow (e.g.: adding, removing, or changing questions) would create a new Package with a new independent id
. The implementation would serve separate results for different package id
s. Client software or external services could examine the Descriptor of each Package and determine, with additional user information, how to aggregate the responses together.
Option 2: Limited changes supported under a Package id
; changes to a flow create new versions under the same id
id
; changes to a flow create new versions under the same id
Implementations that wish to provide aggregation of responses across multiple versions of a flow may serve results from multiple versions under a single package id
, according to the following constraints. Specifically, newer versions of the same package id
may add additional questions
within the schema; however, questions may not be removed, and the metadata for existing questions may not be changed. This implies that if a newer version of a flow removes a question from a previous version, the old question will continue to be listed in the schema for the new version. (This ensures that the schema of the most recent version contains a complete set of questions describing all responses in the aggregated resource data, including responses collected under older verions.) The modified
timestamp is used as a version control indicator for the Package.
In this case, the response data includes responses collected under multiple versions. API access may implement the filter parameters min-version
and max-version
to allow clients to selectively retrieve responses from specific versions. (If a client has cached a version of the schema from a Package descriptor, it is recommended to supply the Package's modified
descriptor as the max-version
when querying the API for responses, to ensure it does not receive responses from newer versions without a corresponding question
in the cached schema.)
For changes to flows that go beyond the restrictions above, new Packages with independent id
s are required; external clients are responsible for more advanced forms of aggregation across versions of flows.
Question Types
The following Question Types describe the nature of possible Responses. This section lists the required and optional parameters within the schema
metadata, and within the Response Metadata for each row:
message
Represents the receipt or consumption of an informational message.
Response Format
The Response must be a number: 0, 1, or a fractional value in between.
How much we know about the consumption of a message depends on the channel capabilities, for example:
SMS without delivery reports: All we could know is the message was sent
SMS with delivery reports: We can know if the message was delivered (but not if it was read)
Social Messaging (Facebook Messenger, WhatsApp, etc.): We can often know if the message was "read"
IVR: We know if the message was listened to, and additionally how much of the message was listened to.
Therefore, the Response value column is proposed to be a numeric column with a boolean interpretation, applicable across channel capabilities:
A value of 0 is not received
A value of 1 means received
When channels can measure partial receipt, a value between 0 and 1 indicates percentage receipt. (For example, an IVR message that the contact listened to 71% of the duration can be represented as 0.71).
Type Options (type_options)
None
Response Metadata
select_one
Represents a selection of one choice from a set of discrete choices. (This is a classic multiple-choice question.)
Response format
The Response must be a string; it must be one from the set of choices
.
Type options (type_options)
Response Metadata
select_many
Represents a selection of one or more choices from a set of discrete choices. (This is a multiple-choice question where the Contact can choose more than one option.)
Response format
The Response must be an array of strings, one for each choice selected by the Contact. Each string must be one from the set of choices
:
Type options (type_options)
Response Metadata
numeric
Represents a numeric response; a measurement of a single number.
Response format
An integer or floating-point number:
Type options (type_options)
Response Metadata
open
Represents a Response that might be in one of several formats. This Question type is useful for representing open-ended Responses to Flows that run over multiple channels (IVR, SMS, social media) and allow the Contact to submit an audio message, image, video, or text response.
Response format
Response must be in the format required for the Question type of each row (where type
is identified within the response metadata.)
Type options (type_options)
None used at theschema
level. (Refer to the type_options
within each row.)
Response Metadata
text
Represents any arbitrary text response.
Response format
A string:
Type options (type_options)
Response Metadata
image
Represents a picture submitted by the Contact.
Response format
A string with the URL where the image can be retrieved. (TODO: Do we want to support inline image data?)
Type options (type_options)
Response Metadata
video
Represents a video submitted by the Contact
Response format
A string with the URL where the video can be retrieved.
Type options (type_options)
Response Metadata
audio
Represents an audio recording submitted by the Contact
Response format
A string with the URL where the audio can be retrieved. (TODO: Do we want to support inline audio data?)
Type options (type_options)
Response Metadata
geo_point
Represents a geospatial coordinate on the surface of the earth.
Response format
Response must be either:
An array of two floating point numbers with the latitude and longitude:
[lat, long]
An array of three floating point numbers: latitude, longitude, elevation (in meters):
[lat, long, elevation]
An array of four floating point numbers: latitude, longitude, elevation, and accuracy (in meters):
[lat, long, elevation, accuracy]
Type options (type_options)
Response Metadata
datetime
Represents a timestamp with both date and time
Response format
A string containing the date and time in the RFC 3339 date-time
format with timezone extension:
Type options (type_options)
Response Metadata
date
Represents a date. We caution that dates are ambiguous without times and timezone offsets. Interpretation of the date is left to the publishing and consuming platforms. For example, this could be the date of the start of a pregnancy, in an implied local timezone.
Response format
A string containing the date in the format:
Type options (type_options)
Response Metadata
time
Represents a time. We caution that times are ambiguous without dates and timezone offsets. Interpretation of the date is left to the publishing and consuming platforms. For example, this could be the time of day a Contact would like to receive messages, in an implied local timezone..
Response format
A string containing the time in the 24h format:
Type options (type_options)
Response Metadata
Last updated