Skip to content

Configuration

Review the Terminology before proceeding

The Configuration UI

limepkg-engage >= 4.0.0 comes with a UI in Lime Admin 2. There you can configure your Activity Triggers.

  • Navigate to Lime Admin 2
  • In Lime Admin 2, use the side menu to navigate to Addons > Engage. (If you cannot see Engage under Addons then Engage is not installed into your solution)
  • Under Addons > Engage you will find Activity Triggers click on it and you will see a list of all existing Activity Triggers and a button to create a new Activity Trigger
  • Click the button to add a new Activity Trigger

Activity Trigger Configuration

Missing Configuration Fields

The Configuration UI is dynamic. It will hide/show/change which fields are shown depending on what data you have already entered into the form.

  • Name: The name of the Activity Trigger. The name does not HAVE to be unique but it SHOULD be unique
  • Active: Whether or not the Activity Trigger is active. If you uncheck this checkbox the Activity Trigger will not fire until the checkbox is rechecked again
  • Limetype: The Activity Trigger listens/waits for Events from a specific Limetype. Choose the Limetype you want to listen to Events on
  • Limetype Event: Events are either Create or Update. The Activity Trigger can listen to just Create Events, just Update Events, or both Create or Update Events.
  • Coworker Email Path: When an Activity Trigger fires, it needs to know who to log the Activity for in Engage. The Coworker Email Path tells the Activity Trigger where to get the email of the user who will get points.
  • Cash Value Path: When setting up a cash Competition in Engage, a cash amount must be provided when logging an Activity. The Cash Value Path tells the Activity Trigger where to get the cash value when logging the Activity. A good example would be Deal > Value when listening to Events on the Deal Limetype. This field is optional and should only be populated if the Activity Trigger will be associated with an Activity on a cash Competition
  • Use Filters?: Whether or not the Activity Trigger uses Filters. Filters allow the Activity Trigger to only fire when an Event passes a specific criteria.
  • Filter Type: What type of filter to use. There are two options. Expression and Custom Handler. When set to Expression, you can use the UI to configure a criteria the Event must pass before the Activity Trigger will fire. When set to Custom Handler you can use a custom function written in python in your solution to perform advanced filtering. This is covered in more depth below.
  • Filters: Covered in more depth below

  • Custom Field: Custom Fields define additional data to be sent to Engage when an Activity is logged.

    • Name: The name of the custom field. MUST match the name of a Custom Field configured in Engage for the Competition otherwise no information is sent
    • Type: The type of data being sent. Either Text or True or False.
    • Property: The property whose value will be sent to Engage. Only properties that are compatible with the selected Custom Field Type will be available for selection

Activity Trigger Filters

Expression Filters

The expression filters provides you with a UI to configure the filter for your Activity Trigger. The filters UI is dynamic meaning it will add/remove/restrict what can be done depending on the data you have or have not already entered. For example, selecting a date property means you can only use Conditions that are compatible with date properties. You can also only compare date properties to other date properties. The UI will restrict and guide you to abide by these restrictions.

  • Expression filters allow you to configure a boolean expression to apply to Events in order to filter out Events that your do not want to log to Engage.

  • Expression filters are composed of comparisons. You can compare a property to another property or a static value.

    • Example Property to Static comparison: I can compare a Deal > Value >= 1000
    • Example Property to Property comparison: I can compare a Deal > Value >= Deal > Other Value

    • Comparisons can be connected using AND or OR in order to create complex boolean logic.

    • For example: I want a Deal > Value >= 1000 AND Deal > Status equals closed

    • Boolean logic can be Nested inside boolean logic to create more complex filters

    • For example: Deal > Value >= 1000 AND (Deal > Status equals closed OR Deal > Status equals signed)

Using the Has Changed Condition

The Has Changed condition allows you to specify what field needs to change during an Update event in order for the Activity Trigger to fire. Lets look at two examples

  • Activity Trigger 1: Updated Deals where value >= 1000 AND status = closed

    • This Activity Trigger will fire if these conditions are met even if value or status are not changed. This means that if, for example, you only update a deals name and the deal already had a value >= 1000 and the status was already closed, then the Activity Trigger would fire.

  • Activity Trigger 2: Updated Deals where value >= 1000 AND status = closed AND status Has Changed

    • This Activity Trigger will fire if the conditions are met, but only if the status is changed to closed. This is usually the behavior you want.

To summarize: Has Changed should be used when configuring filters on Update events. They prevent false positive logging by requiring the Activity Trigger to log only when a specific field we care about is updated.

Things to know when comparing

  • Has Changed

    • Has Changed is only used when listening to a Limetype Event of Update. When configuring a Create Activity Trigger you should not use Has Changed.
    • When a LimeObject is created all the data is new and is treated as though it has changed. What this means is that when using Has Changed with a Create or Update Limetype Event, the comparison is always True during a Create Event

  • String Comparison

    • String comparison is always case insensitive
    • Preceding and trailing white space are removed before comparison

  • Before/After

    • Before and After are only used when comparing dates

  • Has Many

    • Expression Filters cannot be used to filter on a has many relationship. For example, if a deal has many products and you want to filter on "Deals with at least on product of type A", you cannot do that. If you need to filter on a has many relationship you should use a custom filter handler

  • Contains

    • When comparing a property of a relation using Contains or Does Not Contain, you need to be aware of how filtering is handled when that property does not exist. For example, if you are listening to Events on Deals and your filter is 'Deal > Company > Name' Contains 'Lime', if the company relation does not exist on the Deal then this filter will return False. The opposite is true for Does Not Contain. To avoid confusion you can check for the existense of a relation and handle that explicitly in your filters so you are sure you are getting the desired behavior. For example you can write a filter such as 'Deal > Company' Is Null or 'Deal > Company > Name' Contains 'Lime'. In this case if the company relation does not exist the filter will return True.

Custom Filter Handlers

Because there is a limit to what can be done with Expression Filters, and because we want Lime to be super configurable, custom filter handlers can be configured in your solution so that advanced filtering can be performed.

  • Create a function in your solution. In this example we will create the function in <solution-name>/__init__.py. Use this template:
    def rename_me_handler(application, event_identifier, body):
        """Filters on something

        Args:
            application: The LimeApplication instance associated with the Event
            event_identifier: A string identifying the type of event. Example: 'core.limeobject.deal.new.v1'
            body: A dictionary containing details of the event.

        Returns:
            True if the event passes the filters, False otherwise
        """
        if some_condition:
            return True
        return False
  • Name the function something descriptive
  • Your custom handler MUST return either True or False
  • Register this function in your solutions pyproject.toml file. Put a new section just above tool.poetry.dependencies with the same indentation as the tool.poetry.dependencies section:
    [tool.poetry.plugins.'lime_engage_filters']
    rename_me_handler = "<my_solution_name>:rename_me_handler"

Different Handler Function Locations

You may need to change your path depending on where your handler function is located. For example, if your function is in a file called handlers.py in the root of your project, you will need to change your pyproject.toml to have an entry like this: rename_me_handler = "<my_solution_name>.handlers:rename_me_handler"

When to use Custom Filter Handlers

  • When you need to filter on a has_many relationship. For example, if a deal has many products and you want to filter on deals where they have a product of a specific type, that cannot be expressed using the expression filters because it filters on a deals has_many relationship. Instead you can write a custom filter handler to accomplish this.
  • If filtering is dependent on dynamic information that is not part of a LimeType or LimeObject.

Testing your Activity Trigger

  • Go back to Engage and log in as your customer user.
  • Click on the profile image in the top right and click Manage Organization. On the left side menu navigate to Lime CRM Integration.
  • Verify that your Activity Triggers show up in this list
  • Create a competition by clicking Create Competition in the navbar. Go through the create competition process until you reach the point where you add activities
  • Click Add Activity. In the Add Activity dialog you will see two tabs. One saying Standard Activity and one saying Lime CRM Activity. Select Lime CRM Activity
  • Select the Activity Trigger you want to use to trigger/log this Activity. You should select the Activity Trigger you want to test. Complete the rest of the Add Activity form.
  • When you reach the participants page, add yourself (i.e. the customer) to the competition
  • Complete the rest of the create competition process and set it to start right away so we can test now

  • Go back to Lime CRM and perform an Action that will trigger an Event the Activity Trigger is listening to.

    • MAKE SURE that the value at Coworker Email Path is populated with email matching the user you have in Engage. You should get points/score in Engage straight away if you've configured everything correctly.
Back to top