Differences

This shows you the differences between two versions of the page.

--- addons:engage:crm_server_12orlower [2019-06-28 06:35]
James Pember
+++ — (current)
@@ Line 1: / Line 1: @@
-====== Lime Engage ======
-===== What is 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.
-===== Watch a demo of the basic integration ====
-Watching this could be valuable just to get a sense of the flow before you start.
-https://youtu.be/aDJj7ZZe7G0
-===== Lime CRM integration =====
-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
-===== Lime CRM and Engage pre-requisites =====
-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).
- =====
-  - Lime CRM version **12.49.0.390** or later
-  - 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: <code>C:/Program Files (x86) / Lundalogik/Lime CRM </code> **Remember to always download the latest version of the plugin and not keep one stored on your local machine.**
-  - Make sure you allow the CRM Desktop client to write to Engage from the Desktop client. Once in their Environment, open this file: <code>programdata/lundalogik/lime pro server/webserver/configs/config.yaml/ini</code>. To clarify, most customers have an .ini file but a small number of customers may have a .yml file. 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', then talk to us and we'll solve it for you. This will be automated in a future version of our Web Server. In some cases it is a simple format change in that config file that is required. Again, we'll help you here :)
-  - Make sure that the customer signs a DPA agreement unless they have been Engage customers before. Also inform the customer that during the beta phase we are running the plugin with extended logging to make debugging easier.
-===== Contact information =====
-  * **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//
-===== Getting started: creating an integration and Engage competition =====
-**Preparing:**
-  - 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.
-  - 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.
-  - 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.
-  - Go into the Engage Backoffice (https://backoffice.lime-engage.com/halo_backoffice) and find that user, press "Switch to user".
-  - Go to https://app.lime-engage.com/settings/token and press "Regenerate API Token". Copy the API token for the next step.
-**Installing:**
-  - 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.
-  - Make sure you downloaded the plugin as mentioned above in "Lime CRM and Engage pre-requisites".
-  - Then install the addon via Limefu (**open the shell with "run as administrator"**) - On premise
-<code>
-$ pip install -e <local path to plugin>
-$ limeplug install <local path to plugin>
-</code>
-  - 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:**
-  - Input Engage API key in Lime Admin, under Miscellaneous -> Lime Engage -> API configuration (required)
-  - Create the config within Lime Admin containing one of more activity mappers (explained below)
-  - 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**).
-  - __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 :)__
-===== Creating a first Engage competition =====
-Once you have installed Engage, and configured the activity mappers in Lime Admin - you are now ready to create a competition!
-  - Login to the customers admin Engage account ([[http://lime-engage.com/login|lime-engage.com/login]]) . (TODO: How to solve this with Backoffice or PWState?)
-  - Click create competition. Use the wizard to choose what kind of competition you want to run.
-  - When you get to the Add Activity screen, make sure that you use the same name as you created in the config (<code>engage_activity_name</code>). Simply paste this name into the Activity name field.
-  - 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.
-  - Then finish the competition creation by adding users, prizes and setting the competition dates etc.
-  - Now if your configuration is configured correctly - your competition will start to suck in data from Lime CRM!
-===== Upgrading an existing installation =====
-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"**.
-<code>
-$ pip install -e <local path to plugin>
-$ limeplug install <local path to plugin>
-</code>
-- Open upp the "Services" application and find the services "Web Server" and "Event Handler" and restart those. That way the new version is loaded.
-===== Removing the plugin =====
-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.
-===== Potential issues after a CRM server upgrade =====
-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.
-===== Screenshots and or video of Workflow =====
-[[https://youtu.be/aDJj7ZZe7G0|Demo of Engage config]]
-See above for a quick demo of the overall workflow for configuring Engage.
-===== Definitions =====
-  * 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
-==== Activity mapper ====
-^ Property                    ^ Values                               ^ Required    ^ Comment
-| active                      |  boolean (**True** or **False**)     | True        | If set to **False**, this activity mapper will be skipped. Can be used to keep mappers around that are not currently in use. |
-| name                        |  string                              | True        | The name of the activity mapper, e.g. ‘Won deal’. Can be used to specify what the mapper is used for, and to separate it from other mappers in the config. |
-| limetype                    |  string                              | True        | The identifier of the limetype. '''Note:''' this is not a localized name, and not the one shown in the Lime CRM interface. '''Example:''' history, deal |
-| event                       |  string (**new** or **update**)      | True        | The operation in Lime CRM that triggered a change.**new** - an object was created **update** - an object was updated. |
-| engage_activity_name        |  string                              | True        | The name of the activity in Engage that should be logged if the requirements in this mapper are met. '''Note:''' this needs to match the activity name in Engage. '''Note: 2''' If you do not want an activity to be visible in the Engage UI (i.e. it can only be logged through Lime), check the “Only Power Users can log this activity” checkbox when creating the competition. |
-| coworker_field_name         |  string                              | True        | The field in the Lime CRM instance that contains who created the event|
-| filter_boolean_operator     |  string (**and** or **or**)          | False       | Determines what logic should be applied to the list of lime_filters. '''Note:''': if this field is left out of the config, lime_filters will be applied using the and operator. '''Note: 2''': has no effect if the mapper only has one lime_filter. |
-| cash_value_field            |  string                              | False       | Determines what field under 'deal' contains the amount of the deal. '''Note:''': This field is optional. Mappers with this field set map to Engage Cash competition only; mappers without this field map to Engage Activity competitios only. |
-| lime_filters                |  object (see separate table)         | False       | If using filter_boolean_operator and (or omitting filter_boolean_operator from the mapper), all filters need to be true for the logging to proceed. If using filter_boolean_operator or, at least one filter needs to be true for the logging to proceed. |
-| engage_custom_field_mappers |  object (see separate table)         | False       | Map a Lime CRM property to a custom field in Engage. |
-==== lime_filters ====
-^ Property             ^ Values                                                       ^ Comment
-| key                  |  string  (case insensitive)                                  | the field in Lime CRM whose value we want to filter on |
-| operator             |  string  ('equals', 'contains', 'lt', 'lte', 'gt', 'gte', 'before', 'after', 'is_null', 'is_not_null')    | which operator to apply to the value. 'lt' is less than, 'lte' is less than or equal, 'gt' is greater than, and 'gte' is greater than or equal, 'before' refers to a date, 'after' refers to a date, 'is_null' refers to whether the returned value is empty/null, 'is_not_null' refers to whether the returned value is not empty/null  |
-| value                |  string  (case insensitive), bool or integer                 | what we need the value to contain or equal (numerical values must be written in the format '123456', using apostrophes). You can also create filters to check whether the returned value is_null or is_not_null (see below examples). |
-**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: <code>"2018-09-09 00:00 +0200"</code>. 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.  <code>true or false</code>
-  * 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:***
-  * <code>- {key: todo.done, operator: equals, value: true}</code>
-  * <code>- {key: company.postalcountry, operator: equals, value: "Denmark"}</code>
-  * <code>- {key: meeting.date, operator: after, value: "2018-09-09 00:00 +0200"}</code>
-  * <code>- {key: deal.amount, operator: gt, value: 50000}</code>
-  * <code>- {key: meeting.date, operator: is_null }</code>
-  * <code>- {key: meeting.date, operator: is_not_null }</code>
-==== engage_custom_field_mappers ====
-^ Property                  ^ Values                                 ^ Comment
-| engage_custom_field_name  |  string  (case sensitive)              | the name of the custom field in Engage |
-| lime_key                  |  string  (case sensitive)              | the field in Lime CRM whose value should be passed on to the custom field in Engage |
-==== Using custom fields ====
-  * 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
-===== Limitations =====
-  * 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.
-===== Examples of activity mappers =====
-<code yaml>
-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
-</code>
-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.
------
-<code yaml>
-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
-</code>
-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.
-===== Troubleshooting 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:
-  - Check that you have an active Lime Engage configuration and you have one or more activities configured correctly.
-  - Check that your logged activity in Lime CRM matches the Engage requirements for that activity which were setup by the competition creator
-  - To check the Engage activity configuration, check the Engage configuration from your Lime CRM admin page (in the web client).
-  - Make sure that the Activity name within your Engage competition matches the “engage_activity_name” attribute within your configuration (above).
-  - 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.