ondewo/survey/fhir.proto

Top

Copyright 2020 ONDEWO GmbH

Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License. (editesyntax = "proto3";

Services

FHIR

Service Methods

CreateFHIRSurvey

rpc CreateFHIRSurvey (CreateFHIRSurveyRequest) returns (Survey)
Create a Survey from FHIR format and an empty NLU Agent for it

GetFHIRSurveyAnswers

rpc GetFHIRSurveyAnswers (GetSurveyAnswersRequest) returns (SurveyFHIRAnswersResponse)
Get Survey Answers on FHIR format

GetAllFHIRSurveyAnswers

rpc GetAllFHIRSurveyAnswers (GetAllSurveyAnswersRequest) returns (SurveyFHIRAnswersResponse)
Get all Survey Answers on FHIR format

Methods with HTTP bindings

Method Name Method Pattern Body
CreateFHIRSurvey POST /fhir_survey *
GetFHIRSurveyAnswers GET /survey/{survey_id=*}/fhir_answers/{session_id=*}
GetAllFHIRSurveyAnswers GET /survey/{survey_id=*}/fhir_answers
Messages

CreateFHIRSurveyRequest

FieldTypeLabelDescription
fhir_questionnaire google.protobuf.Struct

FHIR questionnaire on a gRPC Struct format

SurveyFHIRAnswersResponse

FieldTypeLabelDescription
survey_id string

The project identifier for this survey. Equal to the parent of the corresponding Agent. Format: `projects//agent`.

fhir_questionnaire_responses google.protobuf.Struct repeated

all requested answers

ondewo/survey/survey.proto

Top

Copyright 2020 ONDEWO GmbH

Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License. (editesyntax = "proto3";

Services

Surveys

Service Methods

CreateSurvey

rpc CreateSurvey (CreateSurveyRequest) returns (Survey)
Create a Survey and an empty NLU Agent for it

GetSurvey

rpc GetSurvey (GetSurveyRequest) returns (Survey)
Retrieve a Survey message from the Database and return it

UpdateSurvey

rpc UpdateSurvey (UpdateSurveyRequest) returns (Survey)
Update an existing Survey message from the Database and return it

DeleteSurvey

rpc DeleteSurvey (DeleteSurveyRequest) returns (.google.protobuf.Empty)
Delete a survey and its associated agent (if existent)

ListSurveys

rpc ListSurveys (ListSurveysRequest) returns (ListSurveysResponse)
Returns the list of all surveys in the server

GetSurveyAnswers

rpc GetSurveyAnswers (GetSurveyAnswersRequest) returns (SurveyAnswersResponse)
Retrieve answers to survey questions collected in interactions with a survey agent for a specific session

GetAllSurveyAnswers

rpc GetAllSurveyAnswers (GetAllSurveyAnswersRequest) returns (SurveyAnswersResponse)
Retrieve all answers to survey questions collected in interactions with a survey agent in any session

CreateAgentSurvey

rpc CreateAgentSurvey (AgentSurveyRequest) returns (AgentSurveyResponse)
Populate and configures an NLU Agent from a Survey

UpdateAgentSurvey

rpc UpdateAgentSurvey (AgentSurveyRequest) returns (AgentSurveyResponse)
Update an NLU agent from a survey

DeleteAgentSurvey

rpc DeleteAgentSurvey (AgentSurveyRequest) returns (.google.protobuf.Empty)
Deletes all data of an NLU agent associated to a survey

Methods with HTTP bindings

Method Name Method Pattern Body
CreateSurvey POST /survey *
GetSurvey GET /survey/{survey_id=*}
UpdateSurvey PATCH /survey/{survey_id=*} *
DeleteSurvey DELETE /survey/{survey_id=*}
ListSurveys GET /surveys
GetSurveyAnswers GET /survey/{survey_id=*}/answers/{session_id=*}
GetAllSurveyAnswers GET /survey/{survey_id=*}/answers
CreateAgentSurvey POST /survey/{survey_id=*}/agent *
UpdateAgentSurvey PATCH /survey/{survey_id=*}/agent *
DeleteAgentSurvey DELETE /survey/{survey_id=*}/agent/delete
Messages

AgentSurveyRequest

FieldTypeLabelDescription
survey_id string

The project identifier for this survey. Equal to the parent of the corresponding Agent. Format: `projects//agent`.

AgentSurveyResponse

FieldTypeLabelDescription
parent string

The parent of an agent. Equal to the survey ID. Format: `projects//agent`.

Answer

FieldTypeLabelDescription
question_nr int64

the number of the question to which this answer belongs

session_id string

the ID of the session on which the answer was collected

answer_text string

Required; the full answer text

answer_parameter string

fixme: better names and doc-strings below Optional; contains the normalized value of the selected option (parameter) extracted

answer_parameter_original string

Optional; contains the original text of the selected option (parameter) extracted

anonymous bool

user_information Answer.UserInfo

Answer.UserInfo

FieldTypeLabelDescription
first_name string

First name of the User to be surveyed

last_name string

Last name of the User to be surveyed

phone_number string

Phone number of the User to be surveyed

session_id string

the ID of the session on which the answer was collected

user_id string

Unique identifier of the User to be surveyed

Choice

The Choice message defines one "option" for the SingleChoiceQuestion and MultipleChoiceQuestion question types

Example: Choice(synonyms=["blue", "blueish", "pale blue", "deep blue"])

FieldTypeLabelDescription
synonyms string repeated

The synonyms which are recognized as equivalent for identifying one option

follow_up_question Question

Optional; Nested question if this specific choice gets chosen. Note: the follow-up question is only available for the SingleChoiceQuestion

value string

The "canonical value" (i.e. the entity value)

CreateSurveyRequest

FieldTypeLabelDescription
survey Survey

DeleteSurveyRequest

FieldTypeLabelDescription
survey_id string

The project identifier for this survey. Equal to the parent of the corresponding Agent. Format: `projects//agent`.

GetAllSurveyAnswersRequest

FieldTypeLabelDescription
survey_id string

The project identifier for this survey. Equal to the parent of the corresponding Agent. Format: `projects//agent`.

GetSurveyAnswersRequest

FieldTypeLabelDescription
survey_id string

session_id string

ID of one specific session on which survey answers were collected (contains survey_id)

user_id string

User Identifier. Note, if the survey is anonymous there will no identifier to filter on

user_phone_number string

User phone number. Note, if the survey is anonymous there will no identifier to filter on

GetSurveyRequest

FieldTypeLabelDescription
survey_id string

The project identifier for this survey. Equal to the parent of the corresponding Agent. Format: `projects//agent`.

ListSurveysRequest

FieldTypeLabelDescription
page_token string

Optional. The next_page_token value returned from a previous list request. Example: "current_index-10--page_size-20" Start page -> 10 Page size -> 20

ListSurveysResponse

The response message for [Intents.ListIntents][google.cloud.dialogflow.v2.Intents.ListIntents].

FieldTypeLabelDescription
surveys Survey repeated

The list of surveys. There will be a maximum number of items returned based on the page_token field in the request.

next_page_token string

Token to retrieve the next page of results, or empty if there are no more results in the list.

MultipleChoiceQuestion

A question for which exactly one or more out of a predefined set of options are expected as answers

Example: MultipleChoiceQuestion(

question_text='Which colors do you like?',

choices=[

Choice(synonyms=['red', 'reddisch']),

Choice(synonyms=['blue', 'blueish']),

Choice(synonyms=['yellow']),

]

)

FieldTypeLabelDescription
question_text string

The text which introduces the question (should be pronounceable)

choices Choice repeated

List of choices which are accepted for this question Each Choice is represented by lists of synonyms. Note: needs to contain at least 2 choices

MultipleParameterQuestion

MultipleParameterQuestion defines a question which prompts the user for one or several entities of one particular type

Example: MultipleParameterQuestion(question_text='How old are your children?', parameter_type='sys.number')

FieldTypeLabelDescription
question_text string

The text which introduces the question (should be pronounceable)

parameter_type string

The display name of the entity (type) which is accepted as an answer to this question Note: the corresponding entity_type must exist (system entity type) and is not automatically created

OpenQuestion

A question to which any kind of reply can be given and recorded

fixme: not working yet

FieldTypeLabelDescription
question_text string

The text which introduces the question (should be pronounceable)

Question

FieldTypeLabelDescription
open_question OpenQuestion

single_choice_question SingleChoiceQuestion

multiple_choice_question MultipleChoiceQuestion

scale_question ScaleQuestion

convenience wrapper around a SingleChoiceQuestion

single_parameter_question SingleParameterQuestion

multiple_parameter_question MultipleParameterQuestion

ScaleQuestion

A question for which an answer on a user-defined scale is expected

FieldTypeLabelDescription
question_text string

The text which introduces the question (should be pronounceable)

min_value ScaleQuestion.ScaleValue

max_value ScaleQuestion.ScaleValue

ScaleQuestion.ScaleValue

FieldTypeLabelDescription
value int32

label string

SingleChoiceQuestion

A question for which exactly one out of a predefined set of options is expected as answer

Example: SingleChoiceQuestion(

question_text='Who is your favorite movie hero?',

choices=[

Choice(synonyms=['Bond', 'James Bond']),

Choice(synonyms=['Batman']),

Choice(synonyms=['Superman', 'Clark Kent']),

]

)

FieldTypeLabelDescription
question_text string

The text which introduces the question (should be pronounceable)

choices Choice repeated

List of choices which are accepted for this question Each Choice is represented by lists of synonyms. Note: needs to contain at least 2 choices

SingleParameterQuestion

SingleParameterQuestion defines a question which prompts the user for one entity of a particular type

Example: SingleParameterQuestion(question_text='How old are you?', parameter_type='sys.number')

FieldTypeLabelDescription
question_text string

The text which introduces the question (should be pronounceable)

parameter_type string

The display name of the entity (type) which is accepted as an answer to this question Note: the corresponding entity_type must exist (system entity type) and is not automatically created

Survey

FieldTypeLabelDescription
survey_id string

The project identifier for this survey. Equal to the parent of the corresponding Agent. Format: `projects//agent`. Read-only in the Survey message (assigned by the back-end)

display_name string

Required. The (human readable) name of this survey

language_code string

Required. The language of the agent created for the survey. This is also the only supported language of the agent. ISO 639-1 language code

questions Question repeated

Required. List of questions to be asked during the survey.

survey_info SurveyInfo

Required. Information about the entity behind the survey, the purpose of the survey, legal stuff, etc.

exclude_subflows SubFlow repeated

Optional. List of subflows excluded for this survey.

status Survey.AgentStatus

Current status of the NLU Agent respecting to the Survey

SurveyAnswersResponse

FieldTypeLabelDescription
survey_id string

The project identifier for this survey. Equal to the parent of the corresponding Agent. Format: `projects//agent`.

answers Answer repeated

all requested answers

SurveyInfo

Collect information about the entity behind the survey, the purpose of the survey, legal stuff, etc.

This is needed to generate meaningful messages and training data for some of the auto-generated intents.

FieldTypeLabelDescription
legal_entity string

Required unless SubFlow.LEGAL_ENTITY is deselected. The legal entity (company, research institute, etc.) on whose behalf the survey is performed

postal_address string

Required unless SubFlow.POSTAL_ADDRESS is deselected. The postal address to which callees can direct any requests.

email_address string

Required unless SubFlow.EMAIL_ADDRESS is deselected. The email address to which callees can direct any requests.

phone_number string

Required unless SubFlow.PHONE_NUMBER is deselected. The phone number to which callees can direct any requests.

phone_hours string

Required unless SubFlow.PHONE_HOURS is deselected. The phone hours during which callees can call (in pronounceable form).

expected_duration string

Required unless SubFlow.EXPECTED_DURATION is deselected. The expected duration of the survey (in pronounceable form)

purpose string

Required unless SubFlow.PURPOSE is deselected. An explanation regarding the purpose of the survey (in pronounceable form)

topic string

Required. A one-word explanation of the survey topic (in pronounceable form)

legal_disclaimer string

Required. A pronounceable explanation of the legal implications of participating in the survey. For example: "Your answers during this survey will be stored anonymously for the next two years and then deleted." Should be formulated such that the agent can afterwards ask for the consent of the user. Example for how the agent could continue: "Are you willing to participate in this survey?"

anonymous bool

Optional. Defaults to False. Allows the definition of a survey as anonymous or not. If the survey is not anonymous, the name of the people as well as their number will be recorded

UpdateSurveyRequest

FieldTypeLabelDescription
survey Survey

Updated survey. Note: the ID must refer to an existing survey which will be updated

update_mask google.protobuf.FieldMask

Optional. Field mask that defines which fields get updated. Default: all fields are updated. Example: - update_mask = FieldMask( [ 'survey.display_name', 'survey.questions' ] )

Enums

SubFlow

Enumeration of (some of) the subflows which are created by default

This can be used to "switch off" particular subflows when creating an agent during CreateSurvey

Subflows are defined as one of the following:

- sequences of intents A -> B_1, ..., B_n -> ... -> Z_1, ..., Z_m which are linked by context relationships

such that the first intent in the sequence can always be triggered

- single intents which can always be triggered

NameNumberDescription
SUBFLOW_UNSPECIFIED 0

Not specified. This value should be never used.

BOT 1

The subflow allowing the user to inquire whether s/he is talking to a bot

LEGAL_ENTITY 2

The subflow allowing the user to inquire about the legal entity

POSTAL_ADDRESS 3

The subflow allowing the user to inquire about the postal address

EMAIL_ADDRESS 4

The subflow allowing the user to inquire about the email address

PHONE_NUMBER 5

The subflow allowing the user to inquire about the phone number

PHONE_HOURS 6

The subflow allowing the user to inquire about the phone hours

EXPECTED_DURATION 7

The subflow allowing the user to inquire about the expected duration of the survey

PURPOSE 8

The subflow allowing the user to inquire about the purpose of the survey

Survey.AgentStatus

NameNumberDescription
TO_BE_INITIALIZED 0

UPDATED 1

UPDATING 2

OUTDATED 3

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)