Setup & configuration

Here's how to use the Engage integration with Sitoo.

Requirements

An active Engage CXP and Omni license
An active Sitoo license

Configuration in Engage

Here is what your Engage team needs to do:

In the client's tenant, create an API-key user for the Sitoo integration.
Send the API key and the tenant's base URL for API access to Sitoo.
If the client has stores in the US, enable the feature toggle “SkipReceiptTotalGrossPriceValidation“ since the US uses a sales tax applied to the totalGrossPrice and not to each line item.
If the store is not in a country using the defined group currency, then the currency needs to be retrieved using an exchange rate. This needs to be set up in Engage using a fixed exchange rate.

Configuration in Sitoo

The API docs for Sitoo can be found here.

An Engage integration is configured in Sitoo using YAML. Using this, you can choose which attributes to use for searching and which to use for for creating, editing and displaying in the POS.

The YAML-configuration is located in Sitoo under Settings / General / POS Settings / Advanced Settings.

This will open up the window where you enter your YAML, which will look something like this:

crm:
  channels:
    -
      id: voyado
      title: Private
      client_settings:
        lookup_type: personal_id
        search_types:
          - mobile
          - email
          - personal_id
          - member_number
        fields_add:
          email: editable
          name: editable
          personal_id: editable
          mobile: editable
          invoice_address: editable
          accepts_email: editable
          accepts_sms: editable
          accepts_mail: editable
          consents: editable
        fields_edit:
          email: editable
          name: editable
          personal_id: editable
          mobile: editable
          invoice_address: editable
          accepts_email: editable
          accepts_sms: readonly
          accepts_mail: readonly
          consents: readonly
      handler:
        voyado:
          api_url: 'https://example.voyado.com/api/'
          api_key: 2b5f1234-12c4-4e20-a3d0-0749a51862aa
          locale: en-GB
          currency_code: EUR
          voucher_passwords_default:
            - pricelist_member_2021
            - spring_member
          voucher_passwords_from_labels:
            -
              label_name: Staff
              voucher_passwords:
                - staffdiscount
          sections:
            -
              title: 'Customer info'
              fields:
                -
                  title: 'Regular store'
                  attribute: currentStore.name
                -
                  title: 'Stamps left'
                  attribute: pointCards
                -
                  title: 'Customer number'
                  attribute: memberNumber
                -
                  title: 'Reward points'
                  attribute: bonusPoints
                -
                  title: Tier-level
                  attribute: bonusBasedLevel
                -
                  title: 'Points left for upgrade'
                  attribute: bonusBasedLevelLeftForUpgrade
                -
                  title: Age
                  attribute: age
                -
                  title: ZIP
                  attribute: zipCode
                  display_true: JA
                -
                  title: 'Personal ID'
                  attribute: socialSecurityNumber
                -
                  title: C/O
                  attribute: careOf
                  display_false: Ingen
                -
                  title: 'Finns ej'
                  attribute: nullAttr
                -
                  title: 'Secrecy marked'
                  attribute: secrecyMarked
                  display_false: 'Sekretess åberopad'
                -
                  title: Consents
                  attribute: consents
            -
              title: Triggerbee
              fields:
                -
                  title: 'Goals acquired'
                  attribute: tbGoals
                -
                  title: 'Interest 1'
                  attribute: tbProfln1
                -
                  title: 'Interest 2'
                  attribute: tbProfln2
                -
                  title: 'Interest 3'
                  attribute: tbProfln3
web_apps: null

Here's how to configure each section in the YAML.

Connection and country settings

Under handler in the YAML is where you set base URL, API key and the country settings:

  handler:
    voyado:
      api_url: 'https://example.voyado.com/api/'
      api_key: 2b5f1234-12c4-4e20-a3d0-0749a51862aa
      locale: en-GB
      currency_code: EUR

Attributes used to search for contacts

Under search_types and client_settings you'll define the attributes used to search for a contact in Engage:

  client_settings:
    search_types:
      - mobile
      - email
      - personal_id
      - member_number

Contact lookup (Dun & Bradstreet)

Here you can configure the personal attribute used to enrich your contact's profiles through a vendor like Dun & Bradstreet. Under "client_settings" you can define lookup_type as either "personal_id" (for their personal identity number) or "mobile" (for their mobile number):

  client_settings:
    lookup_type: personal_id

Attributes to use when creating contacts

In the client_settings section under fields_add is where you add the fields from Engage that will be accessible in Sitoo when adding a contact. These can either be "editable" or "readonly".

fields_add:
      email: editable
      name: editable
      personal_id: editable
      mobile: editable
      invoice_address: editable
      accepts_email: editable
      accepts_sms: editable
      accepts_mail: editable
      consents: editable

Note

If consents is "editable" then all consents will be visible in the POS when adding a contact.

Attributes available when editing contacts

These are the attributes available in the POS when updating an already existing contact. These are added to the client_settings section under fields_edit. The attributes that you want to be editable are listed as "editable". If they are not to be editable, make them "readonly".

    fields_edit:
      email: editable
      name: editable
      personal_id: editable
      mobile: editable
      invoice_address: editable
      accepts_email: editable
      accepts_sms: readonly
      accepts_mail: readonly
      consents: readonly

Custom attributes

Under sections you can choose which custom attributes to display in the POS. You can add different subject lines and then the attributes connected to that subject line.

Here, attribute is the field name in Engage and title is the text displayed in POS.

      sections:
        -
          title: 'Customer info'
          fields:
            -
              title: 'Regular store'
              attribute: currentStore.name
            -
              title: 'Customer number'
              attribute: memberNumber
            -
              title: 'Reward points'
              attribute: bonusPoints
            -
              title: Tier-level
              attribute: bonusBasedLevel
            -
              title: 'Points left for upgrade'
              attribute: bonusBasedLevelLeftForUpgrade
            -
              title: Age
              attribute: age
            -
              title: ZIP
              attribute: zipCode
              display_true: JA
            -
              title: 'Personal ID'
              attribute: socialSecurityNumber
            -
              title: C/O
              attribute: careOf
              display_false: Ingen
            -
              title: 'Finns ej'
              attribute: nullAttr
            -
              title: 'Secrecy marked'
              attribute: secrecyMarked
              display_false: 'Sekretess åberopad'

The display_false and display_true values contain the texts displayed if the field has data (display_true) or if it doesn't (display_false).

Important

Engage standard attributes are always editable in Sitoo, and the fields listed as editable in fields_edit are in addition to these. Engage custom attributes (meaning those that are not standard attributes) can be viewed in Sitoo but not edited.

Default discounts and vouchers

These are general member discounts which are applied in Sitoo when a contact is identified. The discounts and vouchers are created in Sitoo and do not have to be connected to a promotion in Engage.

      voucher_passwords_default:
        - pricelist_member_2021
        - spring_member

Discounts and vouchers connected to labels

These are discounts automatically applied when a contact with a certain label is identified. The voucher is created in Sitoo and in the configuration you can define which discount or voucher is triggered by which label.

      voucher_passwords_from_labels:
        -
          label_name: Staff
          voucher_passwords:
            - staffdiscount

Returning an item purchased with a voucher

If such an item is returned, the voucher used to buy it will not be automatically reactivated. This needs to be manually done in Engage.

Engage API endpoints used by Sitoo

Sitoo needs to access several Engage API endpoints to allow this integration to work.

Retrieving a contact

Endpoint	Description
GET v2/contactoverview	Get a contact's full data.
GET v1/contacts/{contactId}/labels	Get all labels connected to a contact.

Caution

The endpoint used to get a contact's labels uses V1 of the API.

Creating / updating a contact

Endpoint	Description
POST v2/contacts	Creating a contact.
POST v2/contacts/{contactId}	Updating a specific contact

Go here to read more about the v2/contacts API.

Fetching consents

Endpoint	Description
GET v2/consents	For an overview of all consents in Engage.
GET v2/contactoverview	To get the consents which are set to true for a specific contact.

Retrieving personal data from Dun & Bradstreet

Endpoint	Description
GET v2/personlookup/getpersonlookup	Get a contact's enhanced data using either their personal identity number or mobile phone number.

You'll see an example of the response on your Swagger page.

Retrieving transactions connected to a contact

Endpoint	Description
GET v2/contacts/{contactId}/transactions	Get a number of transactions for a contact (results are paged).

Creating a transaction

Endpoint	Match key
POST v2/receipts	contactId

To add a transaction to Engage, this endpoint is used.

Redeeming a promotion

Endpoint
POST v2/contacts/{contactId}/posoffers/{promotionId}/redeem

Redeeming a reward voucher

Endpoint
POST /api/v2/contacts/{contactId}/bonuschecks/{rewardVoucherId}/redeem

Note that "bonusCheck" is an older name for reward voucher in Engage.

In this section: