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
- 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 required. 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.
You can do this manually by following this spec or by installing LIP-packages found here if its supported in the environment.
If you can not use LIP:
- Create the tables and fields that are defined in
lip.json
package - Add the VBA modules from the folder
vba
- Create all localize records (defined in
lip.json
)
Its important that you use a addon-manual-sms LIP-package matching the installed version of addon-manual-sms on the Lime CRM server. If that release of addon-manual-sms does not contain a LIP package asset use the first LIP package you can find in a previous version of addon-manual-sms.
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 want to configure smsrecipients to have more than one relation you also need to create these in LISA. Read more under Field Relations.
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 - Create a sms user in LISA¶
When setting up the integration an API key in Lime CRM will be used. Make sure that the user for that API key has he 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.
- Create an integration group
addon-manual-sms
- Create a new sms integration user, we will call it
[email protected]
and add it to theaddon-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
andtbl_smssendout
.
Policy name | R | W | A | D | 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 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.
- This is the same user as
- 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>Webhook subscriptions
, and create a new webhook subscription with the following information:- Name:
Lime CRM SMS addon
- URL:
https://<server>/<limeenvironment>/addon-manual-sms/webhook/
- AppId:
<Leave empty>
- Secret:
<Leave empty>
- Send batched webhooks:
ON
- Hide header settings:
ON
- Headers:
x-api-key: <API-key for the lime crm smsapiuser, that you generated in LISA>
- Subscribe to all webhooks:
Chose specific
- Turn on webhooks for:
sms.message.delivered_to_recipient
sms.message.send_finished
sms.message.send_started
sms.message.sent_to_recipient
Warning
Spaces matter! Don't remove the one after
x-api-key:
Info
Remember to check
Hide header settings
to not display the API key in plain text - Name:
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.
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 theapps
folder in the root of the Actionpads folder - Move the file
Actionpads/smstemplate.html
to the root of theActionpads
folder - Copy the icons from
lisa/icons
to theActionpads/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 parameterinspector
if the receiver is on current card, addexplorer
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 asmsrecipient
is created in Lime. Make sure that the sendoutstatus is updated for thesmssendout
and thesmsrecipient
. -
🎉 Celebrate 🎉