Technical¶
Configuration explanations¶
Here is an explanation of all the blocks that is included in the example configuration.
Using Consent type mapping¶
In version 2 of the newsletter integration we introduced support for different types of send-outs, e.g newsletters and product information.
This can be done by mapping consent types in Lime CRM to publications in Lime Marketing. Consenttype mapping is used to tell lime-newsletter which consent type to use for what publication(s).
You can for example map the Product info consent type in Lime CRM to the publications Lime CRM customer info, Lime Go customer info and Lime Easy customer info:
"consenttypemapping":{
"consenttypemappings":[
{"consenttype": 1002, # Product info
"publications":[
{"publication": 20}, # Lime CRM customer info
{"publication": 30}, # Lime Go customer info
{"publication": 40}, # Lime Easy customer info
]
}
]
}
If you don't have consent type and consent tables in your database leave the consenttypemapping empty like this:
"consenttypemapping":{
"consenttypemappings":[]
}
Import fields¶
When getting marketing activity participants you can specify which properties you want to be available in Newsletter using the importfields under the participant node in the configuration in Lime Admin.
This can later be used when replacing merge fields in your emails. For example if you want your email to say "Hello $$person.firstname$$" you can specify the person.firstname in the importfields.
Id and email are mandatory for the integration to work. The id is later used to connect a recipient to a 'person' in Lime CRM. The import fields are not validated so make sure you enter these correctly.
Fields that should be synced to Lime Marketing are formatted like this:
"person": {
"firstname": null
}
null value is there to make the importfields backwards compatible to YAML format. You can not sync relation fields by themselves, instead you must define the relation as a json object and sync a field from the related card.
"person": {
"company": {
"_id": null
}
}
All importfields must start from the participant card but can be any related properties found on the card.
Note that only one-to-one (like participantto person) or many-to-one (like person to company) relations are supported.
Example using person:
"participant": {
"name": "participant", <-- Name of the table
"properties": {
"campaign": "campaign",
"person": "person"
},
"importfields":{
"person":{
"_id": null,
"email": null,
"firstname": null,
"lastname": null,
"company":{
"name": null,
"status": null
}
}
}
}
Example using company:
"participant":{
"name": "participant", <-- Name of the table
"properties":{
"campaign": "campaign",
"person": "company"
},
"importfields":{
"company":{
"_id": null,
"name": null,
"phone": null
}
}
}
The null values are just to make the file YAML compatible, do not write anything here.
All importfields must start from the participant card but can be any related properties found on the card.
Note that only one-to-one (like participant to person) or many-to-one (like person to company) relations are supported.
Date and time properties are not supported.
The importfields are validated on the server as of version 2.7.0 and will display an error if any non-existing tables or fields are being used. Read access to any fields used are also validated.
Campaign types and campaign statuses¶
Campaigntypes and campaignstatus are used to filter which marketing activities that should be fetched in lime-newsletter. You can change which types and statuses of campaign you want to see in Newsletter under the campaign table:
"campaign":{
"name": "campaign",
"campaigntypes": [
{ "type": "email"}
],
"campaignstatuses": [
{ "status": "planned"},
{ "status": "engoing"}
],
"properties": ....
}
"campaigntypes": [],
"campaignstatuses": [],
Note that when using lime-newsletter and lime-event the same filter for the campaigns must be used.
Opt-in settings¶
You can configure the integration to automatically create new limeobjects when someone submits the opt-in form of one or more chosen publications. The feature requires that the limetype has an email field. You must also make sure that all the required fields for the limeobject are present in the fieldmappings section. The same applies for the opt-in form in Lime Marketing, all the required fields must be present and set to required in the form. The opt-in integration requires lime-newsletter 2.5.0 or later which in turn requires Lime CRM 2020.x or later.
"optinsettings": {
"enabled": true,
"create_duplicates": false,
"publications": [123, 256],
"limetypesetting": {
"name": "person",
"email_field_name": "email",
"fieldmappings": {
"email": "check email recipient property name in Lime Marketing",
"firstname": "check firstname recipient property name in Lime Marketing",
"lastname": "check lastname recipient property name in Lime Marketing"
...
...
}
}
}
In the section fieldmappings the key on the left is the name of the lime field and the value on the right is the recipient property name in Lime Marketing. The recipient property name in Lime Marketing can be found in Administration -> Email recipient properties.
As mentioned you need to make sure that all required properties on the limetype have required form fields on the opt-in form in Lime Marketing. The integration cant create the lime type if not all required fields have data. So make sure that all the required fields has its corresponding field in Lime Marketing and that they are marked as required. Open this editor by clicking on the "Subscription form" link on the publication settings page.
You can control if the feature is active with the enabled field.
create_duplicates controls if you should be able to create a new object if there is already an object with the same email address.
publications contain the ids of all publications that should be able to create new objects. Leave this empty if you want opt-ins from all publications to create objects.
limetypesetting.name is the database table name of the limetype you want to create, for example person or lead.
email_field_name should contain the database name for the email field. Note that the field must be present in the fieldmappings.
fieldmappings is a list of mapped properties between Lime properties and Marketing recipient properties. Map the lime name on the left and the corresponding Marketing name on the right.
It is not possible to map to a property on a relation field. Simple field types works. I.e. the following types: string, text, link, integer, decimal, date, phone, mobilephone.
Link clicks¶
Link click settings are used for enabling the tracking of link clicks in Lime. It requires lime-newsletter 2.6.0 or later and Lime CRM 2020.x or later.
"linkclickenabled": true
Configure the linkclick table under tables:
"linkclick": {
"name": "linkclick",
"properties": {
"person": "person",
"mailing": "mailing",
"linkname": "linkname",
"linkurl": "linkurl",
"linkvalue": "linkvalue",
"linkclicktime": "linkclicktime",
"linkcategoryid": "linkcategoryid",
"linkcategoryname": "linkcategoryname"
}
}
Set the value for person to the object you are sending your newsletter to (e.g. company or person).
See required structure for instructions on how to set up the link click card.
Mail openings¶
With the emailopeningenabled in your config you can control whether you want to track mail openings in Lime.
"emailopeningenabled": true
Configure the emailopening table under tables:
"emailopening": {
"name": "emailopening",
"properties": {
"person": "person",
"mailing": "mailing",
"emailopeningtime": "emailopeningtime"
}
}
Get Recipients¶
With the getrecipientsenabled in your config you can control whether you want to be able to fetch mailing recipients from a mailing into Lime Marketing. If the property is not included in the config the value is by default set to true. Contact the Marketing Tech team for more information.
Object content¶
Add objectcontent to the config. This is a list of lime-queries. Remember to set a unique queryname for each query.
See this example of two queries:
"objectcontent": [{
"queryname": "coworker_query",
"query": {
"limetype": "coworker",
"responseFormat": {
"object": {
"_id": {
"_alias": "coworkerid"
},
"firstname": null,
"lastname": null,
"email": null,
"office": {
"visitingaddress1": null
}
}
},
"filter": {
"op": "=",
"key": "_id",
"exp": "{0}"
}
}
},
{
"queryname": "deals_query",
"query": {
"limetype": "deal",
"responseFormat": {
"object": {
"_id": {
"_alias": "dealid"
},
"name": null,
"value": null,
"coworker":{
"_id": {
"_alias": "coworkerid"
},
"firstname": null,
"lastname": null
},
"company":{
"name": null
}
}
},
"filter": {
"op": "=",
"key": "coworker._id",
"exp": "{0}"
}
}
}]
exp value of the filter to "{0}" since this is what is inserted from the search input in Lime Marketing.
Since Vue can not handle properties stating with '_' or '$' it is recommended to create an alias for any system properties like '_id' or '_descriptive'. If you forget to do this, the illegal characters will automatically be cleaned by Lime Marketing before you insert the data.
Required structure¶
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 Newsletter admin config.
In order to get the consent flow working you must have the relations to the campaign and person tables.
If you do not want to use consents you can hide the consenttype and consent table, but they must still exist in your database.
You must also have at least one consent type created.
Mailing¶
| Field name | Required | Suggested local name(en/sv) | Field type | Description |
|---|---|---|---|---|
| subject | x | Subject/Titel | Text field | The subject from the mailing (1024 characters) |
| campaign | x | Marketing activity/Marknadsaktivitet | relation (1:n campaign-mailing) | Relation to the campaign, a campaign can have many mailings |
| statisticlink | x | Statistics link/Statistiklänk | Link field | Hidden field used to hold statistic link from Lime Marketing (1024 characters) |
| sendoutlink | x | Sendout link/Utskickslänk | Link field | Hidden field used to hold send out link from Lime Marketing, i.e the actual layout of the mail sent (1024 characters) |
| htmlstatisticlink | x | Statistics/Statistik | HTML-tab | SQL-expression: mailing.[statisticlink]. Displays the content of the statistic link |
| htmlsendoutlink | x | Sendout/Utskick | HTML-tab | SQL-expression: mailing.[sendoutlink]. Displays the content of the send out link |
| mailingid | x | Newsletter ID | Text field | The mailing id from Lime Marketing, should be hidden |
| senddate | x | Sent/Skickat | Date | The date when the mailing was sent |
| recipient | x | Mailing recipient/Utskicksmottagare | relation (1:n mailing-recipient) | Relation tab to the recipients, a mailing can have many recipients |
| linkclick | Relation(1:n mailing-linkclick) | Relation to linkclick, a mailing can have many linkclicks (Only add if using linkclick) | ||
| emailopening | Relation(1:n mailing-emailopening) | Relation to emailopening, a mailing can have many emailopenings (Only add if using emailopening) |
Recipient¶
| Field name | Required | Suggested local name(en/sv) | Field type | Description |
|---|---|---|---|---|
| person | x | Person | relation: (1:n person-recipient) | Relation to the person, a person can have many recipients |
| mailing | x | Mailing/E-postutskick | relation: (1:n mailing-recipient) | Relation to the mailing, a mailing can have many recipients |
| sendoutstatus | x | Sendout status/Utskicksstatus | Option list(sent, open, clicked, bounce, optout) | Used to set status for the mailing. must contain correct option keys |
Marketing activity(Campaign)¶
| Field name | Required | Field type | Description |
|---|---|---|---|
| name | x | Text field | Name of the marketing activity |
| type | Option list | Used to filter out the kind of campaigns to see in Newsletter | |
| campaignstatus | Option list | Used to filter out the status of campaign to see in Newsletter | |
| participant | x | Relation(1:n campaign-participant) | The participants that will get the sendout |
| mailing | x | Relation(1:n campaign-mailing) | The mailing sent in Newsletter |
| consenttype | Relation(n:1 campaign-consenttype) | Send mail to persons with a consent of this type |
Person¶
| Field name | Required | Field type | Description |
|---|---|---|---|
| x | Link field | Email to person IMPORTANT | |
| totaloptout | Checkbox | Shows if the person has done an optout in Newsletter, if set the person will not be included when importing campaign participants | |
| emailhardbounce | Checkbox | Shows if the person has a hard bounce in Newsletter | |
| recipient | x | Relation(1:n person-recipient) | Relation to recipient, a person can have many recipients |
| consent | Relation(1:n person-consent) | Relation to consent, a person can have many consents. | |
| participant | x | Relation(1:n person-participant) | Relation to participant, a person can have many participants |
| linkclick | Relation(1:n person-linkclick) | Relation to linkclick, a person can have many linkclicks (Only add if using linkclick) | |
| emailopening | Relation(1:n person-emailopening) | Relation to emailopening, a person can have many emailopenings (Only add if using emailopening) |
Participant¶
| Field name | Required | Field type | Description |
|---|---|---|---|
| person | x | Relation(1:n person-participant) | Relation to person(Can be changed to something else e.g Company) |
| campaign | x | Relation(1:n campaign-participant) | Relation to campaign |
Consenttype (Optional)¶
| Field name | Required | Field type | Description |
|---|---|---|---|
| title | x | Text field | Name of the consenttype |
| consent | x | Relation(1:n consenttype-consent) | Relation to consent |
| campaign | x | Relation(1:n consenttype-campaign) | Relation to campaign |
Consent (Optional)¶
| Field name | Required | Field type | Description |
|---|---|---|---|
| person | x | Relation(n:1 consent-person) | Relation to person |
| consenttype | x | Relation(n:1 consent-consenttype) | Relation to consenttype |
| approved | x | checkbox | Approved consent equals a Newsletter opt-in |
| source | x | Option list | Where did the consent come from |
Linkclick (Optional)¶
| Field name | Required | Suggested local name(en/sv) | Field type | Description |
|---|---|---|---|---|
| person | x | Person/Person | Relation(n:1 linkclick-person) | Relation to person (or other table connected to recipients) |
| mailing | x | Mailing/Utskick | Relation(n:1 linkclick-mailing) | Relation to mailing |
| linkname | x | Name/Namn | string | Name of the link (1024 characters) |
| linkurl | x | URL/URL | string | the URL of the link (1024 characters) |
| linkvalue | x | Value/Värde | integer | the value of the link |
| linkclicktime | x | Click time/Tid för länkklick | time | the timestamp of the link click |
| linkcategoryid | x | integer | id of the link category (Should be hidden) | |
| linkcategoryname | x | Category/Kategori | string | name of the link category (1024 characters) |
Emailopening (Optional)¶
| Field name | Required | Suggested local name(en/sv) | Field type | Description |
|---|---|---|---|---|
| person | x | Person/Person | Relation(n:1 emailopening-person) | Relation to person (or other table connected to recipients) |
| mailing | x | Mailing/Utskick | Relation(n:1 emailopening-mailing) | Relation to person (or other table connected to recipients) |
| emailopeningtime | x | Opening time/Tid för öppning | time | the timestamp of the emailopening |