Technical¶

Extending the addon¶

Event when form response is created¶

When a new response is created in Lime CRM an event is triggered which can be subscribed to by customizations.

Event name: limepkg_survey.formresponse.new.v1

Parameter Name	Type	Description
formresponse_id	`number`	The id of the form responses lime object
payload	`dict`	The original Lime Marketing payload

Survey form context¶

It is possible to add a form context string to the registration url. This is done by appending the query parameter fc to the registration link.

You can either do this manually, by using the methods in the limepkg_survey.context module or by using the helper functions on the Survey class. It uses JWT to encrypt a JSON object and adds it to the registration url.

Example:

from limepkg_survey.classes import Survey

survey = Survey(application=self.application, id=survey_limeobject.id)
helpdesk_json = {
    'helpdesk_id': 1337
}
url_with_formcontext = survey.get_registration_url_with_formcontext(
    context_dict=helpdesk_json)

The registration url should now look like this:

'https://app.bwz.se/lime/b/v?survey=42&ucrc=7F3D7627BB&fc=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwZXJzb25faWQiOjF9Qa8vLLYRkx1U6pu9MANHwqzqRqHWVGS-g47rR4dutmg'

When opening the form via the updated link and submitting it you will now get the form context string as a property in the webhook payload (which is subscribeable using the eventhandler). Then you can simply decode the string again with the limepkg_survey.context module:

from limepkg_survey.context import (
    decode_context
)

context = decode_context('eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwZXJzb25faWQiOjF9Qa8vLLYRkx1U6pu9MANHwqzqRqHWVGS-g47rR4dutmg')

------------------------------

context == {
    'helpdesk_id': 1337
}

It's possible to change the algorithm and secret used for encoding the data, but remember to use the same values when decoding.

Table and Field Definitions Lime CRM¶

This is the standard structure that the integration expects and needs to function properly, however every table and field name can be configured in the Lime CRM admin config.

Relation(s) to one or many related types on the formresponse table can be added to set the relation between formresponse and other tables. For example if you want the form response to set it's person relation a (1:n) relation between person and formresponse must exist.

Survey¶

Field name	Required	Suggested local name(en)	Field type	Description
name	x	Name	text(256)	The name of the survey
description	x	Description	text(1024)	The description of the survey
registration_url	x	Registration URL	WWW	The url to the survey
bw_surveyid	x	admin field	number	The LM id of the survey
total_responents	x	Total respondents	number	Total number of respondents to the survey
formfield	x	Form fields	relation (1:n survey-formfield)	Relation to the form field, a survey can have many form fields
formresponse	x	Form responses	relation (1:n survey-formresponse)	Relation to the form response, a survey can have many form responses

Formfield¶

Field name	Required	Suggested local name(en)	Field type	Description
bw_formresponseid	x	admin field	number	The LM id of the form response
name	x	Name	text(1024)	The name of the form field
label	x	Label	text(1024)	The label of the form field
is_deleted	x	Deleted in Lime Marketing	yesno	Is the formfield deleted from the survey in Lime Marketing
bw_formfieldid	x	admin field	number	The LM id of the form field
field_type	x	Field type	text(32)	The type of the form field
data_type	x	Data type	option	The data type of the form field. details
survey	x	Survey	relation (1:n survey-formfield)	Relation to the survey, a survey can have many form fields
formresponse	x	Form responses	relation (1:n formfield-formresponse)	Relation to the formresponse, a form field can have many form responses

Formresponse¶

Field name	Required	Suggested local name(en)	Field type	Description
bw_formresponseid	x	admin field	number	The LM id of the form response
str_value	x	Text value	text(1024)	The text value of form response
numeric_value	x	Numeric value	decimal	The decimal value of form response (if applicable)
response_date	x	Response time	date(date and time)	The time of the form response
bw_formfieldid	x	admin field	number	The LM id of the form field
data_type	x	Data type	option	The data type of the form field. details
formfield	x	Form field	relation (n:1 formresponse-formfield)	Relation to the form field, many formresponses belongs to one form field
survey	x	Survey	relation (n:1 formresponse-survey)	Relation to the survey, many formresponses belongs to one survey
person		Person	relation (n:1 formresponse-person)	Relation to a lime type that the addons should try and set, many formresponses belongs to one person

Data type options¶

Key	Default	Suggested local name(en)
empty	Yes	Empty
email	No	Email
mobilenumber	No	Mobilenumber
nps	No	NPS
number	No	Number
text	No	Text

Class diagram¶

classDiagram
    class Survey
    Survey : +String name
    Survey : +String description
    Survey : +String registration_url
    Survey : +int bw_surveyid
    Survey : +int total_respondents
    Survey "1" --> "1..*" Formfield
    Survey "1" --> "1..*" FormResponse
    class Formfield
    Formfield : +String name
    Formfield : +String label
    Formfield : +int bw_formfieldid
    Formfield : +bool is_deleted
    Formfield : +String field_type
    Formfield : +option data_type
    Formfield "1" --> "*" FormResponse
    class FormResponse
    FormResponse : +String str_value
    FormResponse : +String numeric_value
    FormResponse : +int bw_formfieldid
    FormResponse : +int bw_formresponseid
    FormResponse : +datetime response_date
    FormResponse : +option data_type
    class Person
    Person "1" --> "1..*" FormResponse

Permissions¶

If the solution is using Object Access make sure that the API user is a member of a group with access to the data that should be available for the integration to use

Policy name	R	W	A	D	Apply to
tbl_survey	•	•	•		survey table
tbl_formfield	•	•	•		formfield table
tbl_formresponse	•	•	•	•	formresponse table
tbl_person	•				person table if relation to person exists and is used on formresponse
tbl_xyz	•				xyz table if relation to xyz exists and is used on formresponse

Updating a submitted response¶

When a recipient fills out a survey and submits it an (optional) email is sent to recipient if an email field is among the fields in the form. In that email and/or landing page a link can be inserted to edit the response. When a response is edited by either the recipient by clicking the link or by an administrator in Lime-Marketing it's reported back to Lime CRM.

Existing responses are updated with the new value and response date
New responses are added for previously unanswered questions
Multiple choice responses are updated by removing those options no longer selected and adding newly selected