Installation Instructions¶

Preparations¶

Check that the requirements are met.

To get the add-on working you will need admin access to the customer's:

Lime CRM desktop client (VBA + Actionpads) (if they will use the Desktop app)
LISA (If you are not using the Addon Installer)
Lime Marketing site
Application config in CAFE or on the server
Lime Admin

1 - Add addon-manual-sms to the customer solution and install¶

Add the package to the customer solution by running poetry add addon-manual-sms

Before you proceed

Is the addon installed on the server? (Run pip show addon-manual-sms from Lime CRM command prompt for on-prem. It should show package details if installed on the server).

2 - Setup tables and fields¶

Now it's time to set up the required tables and fields. You can do this by running the Addon Installer in Lime Admin under Settings -> Addon Manual SMS -> Setup or manually by following this spec.

If you are using the Desktop Client:

Add the VBA modules from the folder vba
Create all localize records (defined in lip.json)

The tables and fields are not required to have to the same naming as in our docs but the relation between the tables must be the same. The table and field names are then configured in Lime admin if they differ from the default.

If you have made any changes to the default tables and field setup be prepared to configure the changes in lime admin later.

Info

If you are using the Addon Installer, remember to add the relations between smsrecipient and your chosen limetypes before you press "Check installation".

Info

If you are not using the Addon Installer and you want to configure smsrecipients to have more than one relation you need to create these in LISA. Read more under Receiver Configuration.

Before you proceed

Are all required tables and fields set up?
If the customer is using the desktop client, have you added the icons to the tables?

3 - Permissions¶

When setting up the integration an API key in Lime CRM will be used. Make sure that the user for that API key has the correct permissions.

The account will need permissions to all tables used by the integration. If you make any changes on the tables names etc. you need to set the permissions for those tables.

Info

The Addon Installer will add the required user and group for you. You can skip step 1 and 2 below if you installed the package with the Addon Installer.

Create an integration group addon-manual-sms
Create a new sms integration user, we will call it [email protected] and add it to the addon-manual-sms group.
Open limefu console and generate an api-key for apiuser [email protected]. Read more here
Create table policies for tbl_smsrecipient, tbl_smstemplate and tbl_smssendout.

Policy name	R	W	A	Apply to
tbl_smssendout	•	•	•	smssendout table
tbl_smsrecipient	•	•	•	smsrecipient table
tbl_smstemplate	•	•		smstemplate table
tbl_xyz	•			xyz table if relation to xyz exists and is used on smsrecipient

Assign the policies to the corresponding tables and assign the [email protected] user correct permission for the policies.

4 - Lime Marketing set up¶

Log in to Lime Marketing

Create a new publication from where all SMS messages will be sent.
Navigate to the Administration page
Configure Sms recipient properties. (If you can't find sms recipient properties, make sure that SMS-functionality is activated for this customer.) The recipient properties will be the merge-codes that can be used from the app. For example: Firstname, Lastname, Company name and so on.
Create a new Lime Marketing user that will be used for the integration, for example: [email protected].
- This is the same user as api_user in application config
- Make the user only able to be used via integration
- Set publication permissions for the user to only be able to see the SMS publication you created in step 1.
Go to Integrations>Api-keys, and generate an apikey for the user you just created. They key will be used later in step 7.
Go to Integrations and either select an existing Lime CRM integration or create a new one.
- Click the Edit SMS integration settings button
- Add the API-url. It is the application webclient base URL + /addon-manual-sms. You can find the base-url by opening the API documentation in the Lime CRM webclient
- Add the API-key for the Lime CRM user [email protected] that was created earlier.
- Select the publication you created in step 1 under Configuration -> Publication.
- Click the Synchronize to Lime CRM button
- Finally click the Validate settings button in the toolbar and make sure that the error message Could not connect to the endpoint. Verify that the URL and the API-key are correct! does not appear.

sms-integration-settings-page

Info

If you get other validation errors regarding the config you can ignore them for now.
Continue to step 5 and 6 in this guide and they should dissapear.

5 - Configure application config¶

Follow the instructions to set up the application config in CAFE or in application_config.yaml on the server

6 - Lime-admin configuration¶

Follow the instructions to configure the lime-admin config.

Go to the Lime Marketing connection page in lime-admin and make sure that the connection works.

After the config is saved successfully in lime-admin. Go back to the integration settings page in lime-marketing, click Validate settings and make sure that you don't get any validation errors.

7 - Webclient views and webcomponents (For customers using the webclient)¶

Follow the instructions to configure the webclient views, commands and webcomponents

8 - VBA files and actionpad (Only if the customer uses the desktop client)¶

Info

The LBS app SMS depends on lbs-lime-api. The package is partially installed when installing addon-manual-sms through LIP, however you still need to add the apps/lime_api folder to Actionpads/apps manually. If you don't use LIP you'll need to install the app manually, follow the instructions in the GitHub repo.

Info

LIP simulates the installation for the lime_api package several times. This is fine and you can simply choose "Yes, continute" and let it overwrite itself.

Connect to the server using the Lime CRM desktop client and open VBA

Add the following to the GeneralControlsHandler in VBA:

<!-- At the top of the file near the other declarations -->
    Private m_AO_ControlsHandlerSmsTemplate As AO_ControlsHandlerSmsTemplate

<!-- In AfterActiveControlsChanged command -->
    Case "smstemplate"
    Set m_AO_ControlsHandlerSmsTemplate = New AO_ControlsHandlerSmsTemplate

Warning

Sometimes m_AO_ControlsHandlerSmsTemplate is incorrectly added as a Module instead of a Class module by LIP

Move the apps/SMS folder to the apps folder in the root of the Actionpads folder
Move the file Actionpads/smstemplate.html to the root of the Actionpads folder
Copy the icons from lisa/icons to the Actionpads/resources folder, to enable use in actionpads

To use the app in the desktop client you can add it as an actionpad, from which you call the VBA Module AO_SMS.OpenSMSModule. See the code example below: Add the parameter inspector if the receiver is on current card, add explorer if the receiver(s) are from a tab view

    <!-- example for sending to multiple recipients -->
    <div
        class="btn btn-lime btn-warning"
        data-bind="vba:'AO_SMS.OpenSMSModule, explorer', text:'Skicka SMS'"
    ></div>

    <!-- example for sending to a single recipient on the current card -->
    <div
        class="btn btn-lime btn-warning"
        data-bind="vba:'AO_SMS.OpenSMSModule, inspector', text:'Skicka SMS'"
    ></div>

Optional Optout-option code:

<!-- Add the following code in app.html for opt-out option in actionpad app -->

<li data-bind="
 text: 'opt-out',
 vba: 'AO_Actionpad_SmsTemplate.InsertTextToMessage, ' + 'add better description here http://$$publication.unsubscribe$$',
 tooltip: 'info about opt out'"
/>

9 - Verify that everything works¶

Try to send a SMS message to yourself using a template and some merge codes. Make sure that the smssendout and a smsrecipient is created in Lime. Make sure that the sendoutstatus is updated for the smssendout and the smsrecipient.
🎉 Celebrate 🎉