def start_session(session, domain, contact, app, module, form, case_id=None, yield_responses=False,
case_for_case_submission=False):
"""
Starts a session in touchforms and saves the record in the database.
Returns a tuple containing the session object and the (text-only)
list of generated questions/responses based on the form.
Special params:
yield_responses - If True, the list of xforms responses is returned, otherwise the text prompt for each is returned
session_type - XFORMS_SESSION_SMS or XFORMS_SESSION_IVR
case_for_case_submission - True if this is a submission that a case is making to alter another related case. For example, if a parent case is filling out
an SMS survey which will update its child case, this should be True.
"""
# NOTE: this call assumes that "contact" will expose three
# properties: .raw_username, .get_id, and .get_language_code
session_data = CaseSessionDataHelper(domain, contact, case_id, app, form).get_session_data(COMMCONNECT_DEVICE_ID)
# since the API user is a superuser, force touchforms to query only
# the contact's cases by specifying it as an additional filter
if is_commcarecase(contact) and form.requires_case():
session_data["additional_filters"] = {
"case_id": case_id,
"footprint": "true" if form.uses_parent_case() else "false",
}
elif isinstance(contact, CouchUser):
session_data["additional_filters"] = {
"user_id": contact.get_id,
"footprint": "true"
}
if app and form:
session_data.update(get_cloudcare_session_data(domain, form, contact))
language = contact.get_language_code()
config = XFormsConfig(form_content=form.render_xform(),
language=language,
session_data=session_data,
auth=AUTH)
session_start_info = tfsms.start_session(config)
session.session_id = session_start_info.session_id
session.save()
responses = session_start_info.first_responses
if len(responses) > 0 and responses[0].status == 'http-error':
session.mark_completed(False)
session.save()
raise TouchformsError('Cannot connect to touchforms.')
# Prevent future update conflicts by getting the session again from the db
# since the session could have been updated separately in the first_responses call
session = SQLXFormsSession.objects.get(pk=session.pk)
if yield_responses:
return (session, responses)
else:
return (session, _responses_to_text(responses))
return False
session, responses, error_occurred, error_code = start_session_with_error_handling(
domain, contact, app, module, form, case_id, keyword, logged_subevent)
if error_occurred:
error_msg = get_message(error_code, verified_number)
clean_up_and_send_response(msg, contact, session, error_occurred, error_msg,
verified_number, send_response, logged_event, logged_subevent)
return False
session.workflow = WORKFLOW_KEYWORD
session.save()
try:
if len(responses) == 0:
raise TouchformsError('There should be at least one response.')
first_question = responses[-1]
if not is_form_complete(first_question):
if survey_keyword_action.use_named_args:
# Arguments in the sms are named
xpath_answer = parse_structured_sms_named_args(args,
survey_keyword_action, verified_number)
_handle_structured_sms(domain, args, contact_id, session.session_id,
first_question, verified_number, xpath_answer)
else:
# Arguments in the sms are not named; pass each argument to
# each question in order
_handle_structured_sms(domain, args, contact_id, session.session_id,
first_question, verified_number)