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.

• James Pember (james.pember@lime.tech), PM Engage
• Bryce Sampson (bryce.sampson@lime.tech), Dev Engage

• 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

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 projectpy.toml file should look something like this:

[tool.lime.dependencies]
addon-engage = '>=1.x.x'
addon-anothercooladdon = '1.0.2'

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.

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 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 :)

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!

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 your solution-repo, what version of your solution you want (_just make it a higher version than the one you have now in your projectpy.toml file_) a desired CRM version and press BUILD.
• This will start a new job that will export your solution and publish it on github as a release asset under the “releases” tab (e.g. https://github.com/Lundalogik/<solution-name>/releases).

Task: Build and release a new solution using the Solution Exporter steps above

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.

First we need to download the exported solution from github (https://github.com/Lundalogik/<solution-name>/releases). Go to the releases page for your solution-repo, find the new version (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.

Make sure you're in the same directory as the .tar.gz file and 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>

Finally, you have to restart every installed Lime Service (Event Handler, Web Server 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!

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.

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.

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!

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.

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'

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.

- 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 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.

- 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.

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

Go back to Engage and log in as your customer.

1. 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!
2. 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.
3. When you get to the participants page, add yourself (i.e. the customer) to the competition
4. Complete the rest of the competition creation and set it to start right away so we can test now!
5. 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.

1. Build out a real config and lots of mappers based on the customer needs
2. 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
3. Good luck have fun!
4. PROFIT! 🤑