Differences

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

--- addons:engage:start:crm13orabove [2019-10-22 08:08]
James Pember
+++ — (current)
@@ Line 1: / Line 1: @@
-====== Installing the Engage integration for on-prem customers using Lime CRM version 13+ 🔨🥇🙏 ======
-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.
-This integration lets you define a configuration that means when certain events are triggered in Lime CRM, a user in Engage will be rewarded in Engage.
-====== Contact information 💬 ======
-  * James Pember (james.pember@lime.tech), PM Engage
-  * Bryce Sampson (bryce.sampson@lime.tech), Dev Engage
-====== Pre-Requisites ======
-  * Lime CRM Server Version 13.0.0 or above. If your customer is running a version 12.X or lower, please refer to [this documentation](https://docs.lime-crm.com/addons/engage/start).
-  * Customer needs a ''solution-customername'' repository on Github which is compatible with Lime Server 13.0.0
-====== Installing the Engage package in the customer's solution ======
-==== Step 1a - Add ''addon-engage'' as a dependency in the solution-repo ====
-First, we need to tell our customer's solution that Engage is a dependency. In other words, when we install the customer's solution it should also install Engage, and other other add-ons we want. This is a new more powerful way of keeping track of which add-ons are installed on which on-premise installations. A far better way than just ''limeplug install'' in other words :)
-**Task: Add addon-engage to the list of dependencies in the ''pyproject.toml'' file in their solution repository. A good rule of thumb is to take the latest version of the add-on and then define that you want that version or greater (<=)**
-You can always browse the latest releases of ''addon-engage'' here: https://github.com/Lundalogik/engage-integration-crm-arbiter/releases
-Your ''pyproject.toml'' file should look something like this:
-<code>
-[tool.lime.dependencies]
-addon-engage = '>=1.x.x'
-addon-anothercooladdon = '1.0.2'
-</code>
-==== Step 1b - Make sure ''lime-ci'' Github user is a collaborator on your solution-repo ====
-Open up your solution-repo on Github and click the Settings. Then click the "Collaborators & Teams" tab in the sidebar, scroll down to the Collaborators section and add the ''lime-ci'' user with both Write and Read access.
-This is needed because this is the Github user who will handle auto-releasing new solution packages for us.
-==== Step 2 - Merge this dependency change to master and trigger a new release of the solution ====
-Now we need to create a new release of your package with your updated list of dependencies, including ''addon-engage''.
-To do this, we use a clever tool called Semantic Release - which means we can use our Git commit messages to trigger a new release.
-**Task: Commit your changes to master (either direct to master or via Pull Request, both are fine) with the following commit message below**
-''fix: Added Engage dependency to solution''
-If you do not include the ''fix:'' prefix to your commit message, you will not get auto-releases so do not forget it.
-==== Step 3 - Ensure that your solution builds successfully ====
-Every time you commit code to your solution-repo, our build server on Jenkins will run your solution, try build the code, run the tests and generally make sure everything looks good.
-Before proceeding we need to ensure everything looks good with our codebase, even if just made a small change to the dependency file.
-Browse to https://jenkins.lime.tech/
-Search for your solution
-It will probably show up at a link like https://jenkins.lime.tech/job/plugins/job/solution-customername/
-**Task: Make sure the master branch is a nice big green tick!**
-{{:addons:engage:start:screenshot_2019-10-18_at_13.47.12.png?400|}}
-If your master branch builds succesfully, and you used the ''fix:'' git commit message prefix, you should see a new release in the Github ''solution-repo'' at https://github.com/lundalogik/<solution-repo>/releases.
-==== Step 4 - Export your solution ====
-To export a solution, do the following:
-  * Browse to https://jenkins.lime.tech/job/lime-crm-solution-exporter/ and login by pressing on the login button in the upper right corner.
-  * Press the Build with Parameters button in the sidebar menu.
-  * Fill in the form with
-      * In the NAME field, enter the name of your ''solution-repo'' i.e. ''solution-customername'',
-      * In the VERSION field, enter the full version number of the release you just created (find at https://github.com/lundalogik/<solution-repo>/releases). Use the ''major.minor.patch'' format i.e. ''1.0.1''. You do not need to include the ''v''.
-      * In the CRM_VERSION field, enter the version of the Lime CRM Server that the customer is running now. If you would choose a higher version, their server would be upgraded when you install the solution later.
-**Task: Build and release a new solution using the Solution Exporter steps above**
-Once you submit this form, this will start a new Jenkins job that will export a packaged version of your solution and add this package as an asset to your Github release.
-The asset has a filename like: ''exported-xxxxxx.tar.gz''.
-{{:addons:engage:start:screenshot_2019-10-22_at_10.03.22.png?400|}}
-//Note: When a solution is exported it is built for a specific version of Lime CRM, the one you just chose in the form above. That means that every time you upgrade a server, you need to export the solution again. Otherwise, you might re-install the previous version of Lime CRM when installing the solution.//
-==== Step 5 - Install the solution on the customer's server ====
-Now we need to download the exported solution package from Github (https://github.com/Lundalogik/<solution-name>/releases). Go to the releases page for your solution-repo, find the release you've created (it should of course be the latest one), and open it. Scroll down to the ''Assets'' section and you should see some files that look like ''exported-xxxxxx.tar.gz''.
-**Task: Download the ''exported-xxxxxx.tar.gz'' file and place it on the customers server**
-Now, within the customers CRM environment, open up Limefu and make sure you are running it as an Administrator.
-Then run the following command to install the new solution we've packaged up.
-''limefu solution install /path/to/<solution-{solution-name}-{suffix}.tar.gz>''
-If the ''limefu solution install'' command is timing out or not succeeding, make sure all the Lime CRM services are running.
-Once the solution is installed, you have to again restart every installed Lime CRM Service (Event Handler, Web Server, Webfront etc) such that the customisations in the solution is picked up by Lime CRM. Open the Services application and do this now.
-**Verify that ''addon-engage'' was installed**
-Go to the customers Lime Admin, open the Miscellaneous tab and make sure Lime Engage shows up in the sidebar. If so, the solution and add-on are installed! 🎉 Great job!
-====== Engage Time! 🔥 ======
-OK! So now you have installed the ''addon-engage'' package onto the customers CRM server. However, now you need setup the Engage side of things.
-==== Step 6 - Create an Engage account for the customer ====
-**Task: If the customer has not used Engage before, go to https://app.lime-engage.com/register to create an Engage organisation for them.**
-You will be asked to add a Name, Email and Password. Do not use your own information, instead __use the information of person at the customer who will be responsible for Engage__. This will make this person the "Account Owner" for Engage.
-**Task: Please save this email and password in Password State on the customers card.**
-You will now be able to login with this account and you'll land on an empty Dashboard.
-==== Step 7 - Generate an Engage API key for this account ====
-Once on the Dashboard, logged in as the customer, click on the users profile in the top-right and click ''Edit Profile'', and then ''API Key''.
-**Task: Generate a new API Key and go and save it in PasswordState. You'll need this for configuring Engage later!**
-==== Step 8 - Set this to a Lime CRM integration customer in the Engage BackOffice ====
-This is an admin portal for Engage where you can do a bunch of cool stuff.
-Make sure you are logged in as a SUPER_USER and go to The Engage Backoffice https://backoffice.lime-engage.com/halo_backoffice/organizations
-Find the account/organiztion you just created (it should be up the top), click the ''Edit'' button and make sure the "Lime CRM Integration" checkbox is checked, then save by pressing ''Update Organization'', the red button.
-==== Step 9 Configuring Engage in Lime Admin ====
-You are now ready to start building the configuration itself i.e. telling the integration **what to listen to in CRM** and **when to give someone a reward in Engage!**
-**Task: Add the Engage API key to Lime Admin. Click on Engage in the LimeAdmin->Misc->Engage, open the API Configuration tab and add the Engage API Key you saved a few steps earlier and press save.**
-Use the following format:
-''api_key: 'xxxxxx' ''
-==== Step 10 Configuring your first activity ====
-**Task: Build your first Data Configuration Mapper**
-The Engage add-on uses something we call ''Mappers'' to define **what to listen to in CRM** and **when to give someone a reward in Engage!**
-Here are two simple examples of activity mappers.
-<code>
-- 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 above accepts new history notes 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>
-- 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.
-**Some notes on configuring mappers**
-  - Always use database names in the configuration
-  - You cannot combine ''and'' & ''or'' filter operators in the same mapper
-  - Users are matched on email between Engage and CRM. This means make sure the users in Engage have the same users in Lime CRM
-Read more about how to customise the mappers here: https://docs.lime-crm.com/addons/engage/crm_server_12orlower#definitions
-**Task: Create a simple first mapper and try press Save. Try a "sales call" or something similar. When you press save, we will validate your config and tell you if something is wrong**
-==== Step 11 Testing your activity and the real-time sync ====
-Go back to Engage and log in as your customer.
-  - If you go to https://app.lime-engage.com/organization/integration when logged in as the customer, you should now see your first configured activity here. Great!
-  - Click create competition and create a competition. When you get to the "Add Activity" step, you can add your activity to the competition by clicking the blue ''Select an activity from Lime CRM'' button.
-  - When you get to the participants page, add yourself (i.e. the customer) to the competition
-  - Complete the rest of the competition creation and set it to start right away so we can test now!
-  - Go back to Lime CRM and go create the activity you want to sync. **MAKE SURE that the coworker is set to the same coworker (with email) as the user you have in Engage**. You should get points/score in Engage straight away if you've configured everything correctly.
-==== Step 12 Next steps ====
-  - Build out a real config and lots of mappers based on the customer needs
-  - Create all the users in Engage (you have to do this manually for now unfortunately). Do it here https://app.lime-engage.com/organization/members and remember to match the emails to Lime CRM
-  - Good luck have fun!
-  - PROFIT! 🤑