Lime Engage

Lime Engage is an add-on for Lime CRM that lets customers create internal competitions to help them to try improve certain activities, behaviours and results.

For example, a sales team may run a competition to try and increase the number of booked meetings, or cold calls. A support team may try to close down as many tickets as possible in a certain amount of time.

Watching this could be valuable just to get a sense of the flow before you start.

https://youtu.be/aDJj7ZZe7G0

The arbiter integration connects Lime CRM and Engage. When things are created or updated in Lime CRM, arbiter let’s you control if those changes should trigger a logging of points in Engage competitions.

To see organisations who have Lime CRM integrations and linked to Engage, go to https://backoffice.lime-engage.com/halo_backoffice/lime_crm_integrations

BEFORE STARTING. TO SAVE YOURSELF TIME, PLEASE CHECK:

===== That the customer is running at least Lime CRM version 12.49.0.390 or later and that they are running at least version 0.7 of the lime-event-handler package (run `pip list` in limefu to check).

1. Lime CRM version 12.49.0.390 or later
2. Download the latest version of the plugin on https://github.com/Lundalogik/engage-integration-crm-arbiter/releases . Then transfer and unzip it on the relevant customer server. We recommend putting the unzipped engage directory in this directory:

   C:/Program Files (x86) / Lundalogik/Lime CRM 

   Remember to always download the latest version of the plugin and not keep one stored on your local machine.

3. Make sure you allow the CRM Desktop client to write to Engage from the Desktop client. Once in their Environment, open this file:

   programdata/lundalogik/lime pro server/webserver/configs/config.yaml/ini

   . To clarify, most customers have an .ini file but a small number of customers may have a .yml file.

4. If 'use_ldc_for_writes' is set to True, set it to False and then go to Windows Services and restart the Lime CRM Web Server. If there is nothing in this file about 'use_ldc_for_writes' - add the following block of code to your config.ini file

[ldc]
use_ldc_for_writes = False

• Onboarding of new customer, feature requests and questions in general: James Pember (james.pember@lime.tech), Product Manager
• Technical support: Behrouz Talebi (behrouz.talebi@lime.tech), Dev Lead

Preparing:

1. If the customer has not used Engage before, go to https://app.lime-engage.com/register to create an Engage organisation for them. This includes creating the first power user, which can be used in the next step.
2. Pick a user in Engage that is a power user. We will need to generate an API key for that user that we are going to use when connecting CRM and Engage.
3. Once in the Backoffice, open the organisation and make sure the “Lime CRM Integration” checkbox is checked. If you cannot get into Backoffice, talk to James.
4. Go into the Engage Backoffice (https://backoffice.lime-engage.com/halo_backoffice) and find that user, press “Switch to user”.
5. Go to https://app.lime-engage.com/settings/token and press “Regenerate API Token”. Copy the API token for the next step.

Installing:

1. If you have done these steps on a staging or development env. for a customer, please uninstall it there and dont run two instances of the same plugin on the same customer. If you do that, it will be very hard to debug in case there are errors.
2. Make sure you downloaded the plugin as mentioned above in “Lime CRM and Engage pre-requisites”.
3. Then install the addon via Limefu (open the shell with “run as administrator”) - On premise

$ pip install -e <local path to plugin>
$ limeplug install <local path to plugin>

1. Open upp the “Services” application and find the services “Web Server” and “Event Handler” and restart those. That way the new plugin is loaded.

Configuring:

1. Input Engage API key in Lime Admin, under Miscellaneous → Lime Engage → API configuration (required)
2. Create the config within Lime Admin containing one of more activity mappers (explained below)
3. You are now ready to create a competition within the Engage “Create Competition” UI. Make sure when creating Activities that you use the same name as you created in the config (engage_activity_name).
4. Important: Do not use your own API token when configuring Engage from Lime Admin - you MUST use a token connected to the Customer/Power Uesr for the customer. No short Cuts here :)

Once you have installed Engage, and configured the activity mappers in Lime Admin - you are now ready to create a competition!

1. Login to the customers admin Engage account (lime-engage.com/login) . (TODO: How to solve this with Backoffice or PWState?)
2. Click create competition. Use the wizard to choose what kind of competition you want to run.
3. When you get to the Add Activity screen, make sure that you use the same name as you created in the config (

   engage_activity_name

   ). Simply paste this name into the Activity name field.

4. When creating activities, be sure to press the “Only Power Users can do this activity” checkbox, which means we will block users from being able to manually log activities and only allow points to be registered via the integration.
5. Then finish the competition creation by adding users, prizes and setting the competition dates etc.
6. Now if your configuration is configured correctly - your competition will start to suck in data from Lime CRM!

Replace the files where its currently installed with the ones you just downloaded from the latest release. You can simply remove the old folder. After that, run the following commands again (the same as when you installed it the first time):

Make sure you are in limefu and open the Shell with “Run as administrator”.

$ pip install -e <local path to plugin>
$ limeplug install <local path to plugin>

- Open upp the “Services” application and find the services “Web Server” and “Event Handler” and restart those. That way the new version is loaded.

Uninstalling an existing version:

• Remove engage-arbiter (the engage plugin) from the plugins folder (%programdata/Lime Pro/…/plugins)
• Also remove engage-arbiter from the main directory where you installed it (probably like c:/Program Files 86 /Lunda.. /Lime CRM)
• Restart event handler service
• Restart web server

Note: Some customers receive errors when trying to load Lime Admin in the web client after an uninstall (i.e. from a test environment). This is most likely always because the uninstall process hasn't been completed properly, and the web client tries to create a menu item for Lime Engage and fails. Make sure you followed all 4 steps above.

There can sometimes be issues with the Engage plugin after a CRM server upgrade. Just uninstall the plugin (above) and do a fresh install and everything will be fine. The config should still be in place as the database is not affected by the upgrade.

Demo of Engage config

See above for a quick demo of the overall workflow for configuring Engage.

• Activity mapper (mapper): a YAML structure describing how to map events in Lime CRM to activities in Engage competitions.
• Config: a collection of activity mappers

A few notes on filters:

• You can use Date strings as filters together with either the 'before' or 'after' operator. These need to be in the following format:

  "2018-09-09 00:00 +0200"

  . Note you need to include the timezeone at the end of the string i.e “+0200”.

• You can use booleans as the value in a filter (i.e.

  true or false

• You can also use Null Check operators to check for fields that are either empty or not empty. When using a null check operator, you can skip the “value:” part of the filter completely. See examples below.

Examples of lime_filters:*

• - {key: todo.done, operator: equals, value: true}

• - {key: company.postalcountry, operator: equals, value: "Denmark"}

• - {key: meeting.date, operator: after, value: "2018-09-09 00:00 +0200"}

• - {key: deal.amount, operator: gt, value: 50000}

• - {key: meeting.date, operator: is_null }

• - {key: meeting.date, operator: is_not_null }

• Can only use custom fields with text type (not checkbox)
• Any custom field mapping in the config that does not match a custom field in an Engage competition will simply be left out of the activity logging
• Using required custom fields is not advisable, since activity logging will not work if a required custom field is left out of the config

• A mapper that listens for new events will not trigger on update on that same object.
  • E.g. mapper has limetype ‘history’, event new, filter on ‘type’ ‘bookedmeeting’. Coworker logs ‘salescall’ and then updates the ‘type’ to ‘bookedmeeting’. Since the mapper only looks at new events, this means that the update will not trigger a logging of points in Engage.
• Workaround: adding an additional mapper that listens for update events on limetype ‘history’, filter on ‘type’ equals ‘bookedmeeting’.
  • This kind of workaround needs to be used with caution, for two reasons:
  • * If there’s a mapper for the ‘type’ ‘salescall’ as well, there will be double points logged in Engage.
  • * This will not work if you have two filters that both need to be satisfied (using filter_boolean_operator and). If the new event mapper has a lime_filter looking at two different fields (e.g. ‘note’ contains ‘CEO’ and ‘type’ equals ‘bookedmeeting’), and you create an update mapper to counteract the case described above, the update event mapper will only see that the ‘type’ field has updated and as such will not trigger a logging of points.
• Workaround: deleting the item in Lime CRM and logging it again with the correct type.
• Points can not be logged retroactively. I.e. if a coworker is not added to a competition before they log something in Lime CRM, that log will not give points.
• LimeTypes that can have multiple values can not be used in filters or custom field mappers. E.g. if ‘company‘ has multiple ‘industry‘, we can not use ‘company.industry.name‘.
• Custom fields in Engage need to be handled with care (see section 'Using custom fields' above)
• We have no way to know if a event handler has stopped running, which seems to happen from time to time after updating the add-on.

- name: Booked customer visit
  active: true
  limetype: history
  event: new
  coworker_field_name: coworker
  engage_activity_name: Booked customer visit
  filter_boolean_operator: and
  lime_filters:
    - { key: type, operator: equals, value: bookedcustomervisit }
  engage_custom_field_mappers:
    - { engage_custom_field_name: Note, lime_key: note }

This mapper accepts new history notes (i.e. not updates on existing) where the type is 'Booked customer visit'. The contents of the `note` field from Lime is passed on to the `Note` custom field in Engage.

- name: Deal won
  active: true
  limetype: deal
  event: update
  coworker_field_name: coworker
  engage_activity_name: Won deal
  cash_value_field: value
  filter_boolean_operator: and
  lime_filters:
    - { key: dealstatus, operator: equals, value: agreement }
    - { key: value, operator: gt, value: 50000 }
  engage_custom_field_mappers:
    - { engage_custom_field_name: Customer name, lime_key: company.name }
    - { engage_custom_field_name: Deal name, lime_key: name }

This mapper accepts deal, where the `dealstatus` field has been updated to 'agreement'. It also requires the value to be greater than 50,000. The value from the field specified in `cash_value_field` is sent to Engage as the amount sold for. The name of the company the deal is tied to is passed on to the `Customer name` custom field in Engage. The name of the deal is passed on to the `Deal name` custom field in Engage.

This section will help you understand and troubleshoot some of the most frequently asked support/user questions regarding the Engage add-on and integration to Lime CRM.

I can’t see my activities logged in Engage even though I’ve logged them in Lime CRM?

To see what may be going wrong, perform the following steps:

1. Check that the Lime CRM Event Handler windows service is running
2. Make sure you have the same API key for the Engage user and the Lime Admin 2 API Configuration
3. Make sure the user you are logged in as in CRM is the same user you are testing in your Engage competition
4. Check that you have an active Lime Engage configuration and you have one or more activities configured correctly.
5. Check that your logged activity in Lime CRM matches the Engage requirements for that activity which were setup by the competition creator
6. To check the Engage activity configuration, check the Engage configuration from your Lime CRM admin page (in the web client).
7. Make sure that the Activity name within your Engage competition matches the “engage_activity_name” attribute within your configuration (above).
8. Check you are a participant in an active competition (if you are not, you will not be awarded points)

I made a mistake, so I updated something in Lime CRM but Engage still hasn’t updated the activity to show the right data?

Most Engage activities are configured to sync from Lime CRM to Engage when the activity is first created and Engage does not always necessarily listen for updates to specific activities. This means if you do something in Lime CRM (i.e. book a meeting) which syncs over to Engage, and then you change that meeting activity – those changes won’t be synced over to Engage.

Can I get points retroactively for activities I logged before the competition started?

No. You cannot receive points retroactively. You will only be rewarded points for activities that are logged within the competition dates/time.