SuiteCRM Post-Installation Housekeeping

If you’ve been following along any of my other SuiteCRM (“SCRM” from hereon in) blog posts, you’ll know that I’m a big fan of this free and open SuiteCRM software project. As such, I do my best to document things that are either easily forgotten or difficult to find online. Hopefully some of this is valuable to you.

1 – Setting up Basic Outbound Email for Functionality

The built-in email functionality of SCRM is not just for sending emails to people with relative ease (which it can do right inside the interface) but also, if not more importantly, it serves to deliver messages from the Workflow module. For example, if you have a task due and you want an email to remind you, this does that. If you don’t set up the email you will only be able to log in and see your tasks.

This gent did a great, slow and methodical Suitecrm email setup video so it is definitely worth the 7 minutes if you haven’t done this before.

I would like to make a few additional comments, though, on the following points:

“Outbound Email” in Admin

When I first started using SCRM I started by adding an ‘outbound email’ server in that specific spot. However, this seems to not be required / redundant. When you go into ‘Email Settings” and do all the items in the video above, an outbound email server is automatically created. I am not sure why there is access to this via two doors. Perhaps to do a quick adjustment (such as a password change?) later? But you can also do that in “Email settings”. I feel better notes should be left in the “Outbound Email’ section user interface to explain, but until then, unless you have a reason, simply don’t use this section and do your adjustments / setup in “Email settings”

Spam Protection Headaches

I have had a repeated issue where I can perfectly send test emails from SCRM to any email address except an email address that shares the same domain name. For example, let’s say my email in SCRM is wayneoutthere@example.com. I can send perfectly to wayneoutthere@whatever.com but emails sent to bob@example.com don’t make it through. I don’t yet know the technical reason for this but it could be something as simple as the server not yet being ‘warmed up’ and still possibly on a ‘spam radar’ or worse yet, a spam blacklist.

As such, I would always start your email setup with a test email to various email addresses that do not share a domain with the system-sending email address as well as emails to ones that do share. It’s very important, obviously, that emails from the system make it to your organization’s email addresses – that’s the entire purpose of the system! If all else fails, and you don’t care about privacy and security, you could probably set up a quick gmail address to do the sending, but this doesn’t look good from a professionalism standpoint or data privacy.

POSSIBLE / PROBABLE SOLUTION TO EMAIL SEND FAILS TO INTERNAL EMAIL ADDRESSES
For me, the cause of the problem seemed to be the fact that I changed the "From" Address: * field to an non-existing account called ‘do_not_reply@’ So, the ‘real’ account (the one that had legitimate SMTP server credentials) was ‘orders@’, but I entered ‘do_not_reply@’ and this caused emails to fail to internal email addresses. My theory is that the email service provider has some anti-spoofing technology going on that said ‘Hey. This email came from an SMTP thing on the internet using your domain when an account called ‘do_not_reply’ doesn’t actually exist. They might be spoofing you!’ However, this still doesn’t explain why all the do_not_reply@ emails successfully were received by various gmail and other emails. Anyway, consider making a dedicated, real, email address just for this sending if you encounter this issue.

2 – Jobbing your Crons

As mentioned above, the Workflow module is very powerful and can send messages as well as part of an ‘event’. As described on the /install.php page of SuiteCRM (if you recall), in order to enjoy the full power of the Workflow module, you need ‘cron jobs’ working as per requirements mentioned on install page. Not only that, but SCRM has other internal ‘things’ it needs to do (such as indexing) which require this to work. In short, just do the following instructions from the install page now, but, be careful of one thing and that is to make sure that your folder is actually named ‘suitecrm’ and that it’s located at /var/www/html/ otherwise, adjust the path in the following accordingly:

This is a copy and paste from the installation page in case you didn’t note it:

To Setup Crontab
In order to run SuiteCRM Schedulers, edit your web server user’s crontab file with this command:
sudo crontab -e -u www-data
… and add the following line to the crontab file:

• * * * * cd /var/www/html/suitecrm; php -f cron.php > /dev/null 2>&1
  You should do this only after the installation is concluded.

If the above wasn’t clear enough for you, here is my detailed explanation:

1. ssh into your SCRM server
2. Open the crontab file for editting: sudo crontab -e -u www-data
   Note: if this is the first time creating a crontab file on an ubuntu machine, you will be told so and it will automatically start a fresh one for you. You will be prompted to choose a text editor and it will also advise nano (option 1). Choose this default if you aren’t sure since all you need to do is paste a line of code at the bottom
3. Copy this line of code: * * * * * cd /var/www/html/suitecrm; php -f cron.php > /dev/null 2>&1
4. Paste it to the bottom of the crontab file
5. save changes (control x, enter, etc)

I also had an issue where my cron jobs didn’t start, so it was advised around the internet to run this restart command on it to be sure:

sudo service cron restart

Your crontab stuff is now complete.

You can see if things are working by going into Admin / Schedulers and looking at some regularly-occurring items to see the job logs. Choose one with an interval of ‘As often as possible’ and this will give you a good idea if it’s working.

You can also go to Admin / System Settings and at the bottom view the logs to see if there are any errors if things are supposed to happen but don’t seem to be. Note it’s not intuitive but you have to actually click the job log menu to show any results. It looks blank otherwise. A bit weird indeed. There should at least be an icon to show you that you could /should click it, but it’s not there yet.

Note this tip from documentation, too, in case it affects you:

If you were running your cron jobs as root for some time, due to a wrong crontab configuration, after you fix it, remember to reset correct >ownership and permissions on the entire SuiteCRM directory tree, and then do a Quick Repair and Rebuild

The ‘Quick Repair and Rebuild’ is quite amazing at fixing things you don’t even understand. 🙂

3 – Setting up some Pretty Critical Missing Fields

Payment Method

Surprisingly, this very important field “Payment Method” is missing in both the Quotes and the Invoice module. It’s easy to create but I thought I would provide a quick and easy resource where you can come back here and re-create or create it quickly without doing so much thinking.

First, Quotes module:

1. Go do Admin
2. Studio
3. Hit the home icon which magically takes you to the secretive ‘Dropdown editor’
4. Click ‘Dropdown editor’
5. CLick ‘Add dropdown’ button
6. add ‘pay_method’ before the ‘_list’ in the Name: field at the top
7. Start building the list as follows (you can copy and paste mine or change the items and the order as you like) hitting the ‘Add’ button after each one is completed:

ITEM NAME | DISPLAY LABEL

credit_card | Credit Card
cheque | Cheque
e_transfer | Email Transfer (E-transfer)
eft | Electronic Funds Transfer (EFT)
cash | Cash
wire_trans | Wire Transfer
bitcoin | Bitcoin

(OPTIONAL: Add a blank entry if you want the option of leaving the payment method blank when users are choosing the payment method. Otherwise you’ll be forced to select one as a default – you do this by pushing the ‘ADD’ button with nothing in the item name or display label fields.

8. Hit save – you should get the ‘This operation is completed successfully’ message

Now you have your Payment method dropdown but you don’t yet have a useable field so let’s make that next.

1. Hit the home button to go back up a level
2. Go to Studio
3. Go to Quotes
4. Fields
5. Add Field
6. Choose ‘dropdown’ drom the ‘Data Type:’ list at the top
7. Field name: ‘payment_method’
8. Display Label: ‘Payment Method’
9. Drop Down List: search for the one you just made above called ‘pay_method_list’
10. Choose default value
11. “Save”

Congrats! You now have a usable field but you do not have a visible field – so… it’s still useless. Let’s make it visible:

1. Studio (you’re getting good at this now!)
2. Quotes
3. Layouts
4. Edit view
5. Drag a ‘New row” button over to the ‘Overview’ panel
6. Drag your new ‘Payment Method’ field onto new row from the left column (you should see it there)
7. Arrange remaining fields however you like
8. “save and deploy’ to save and launch your changes
9. Go create a new quote, and make sure that your changes exist in “Edit View’ after pressing ‘edit’ button in quote

If everything went well, you now have a fully-functional ‘Payment Method’ field in the Quotes module of SCRM.

Update the Detailed View
Now you can repeat steps 1,2,3 and then select ‘Detail View’ and repeat steps 5, 6, 7, 8 to make the same fields visible in the “Detail View’ (the view before you hit the edit view)

Create fields for Invoice Module
Now, let’s repeat the same thing for the invoice module since we’ll need it there too. However, we’ll also want the contents of the quotes module field to convert to the invoice during conversion when the user clicks ‘conver to invoice’. This will happen if we give the field the exact same name in the Invoice module.

I would advise opening the following up in a separate browser tab for convenience: Studio / Quotes / Fields / ‘payment_method_c’ (the one you created above in the quotes module)

Now in a new tab do the following:

1. Studio
2. Invoices
3. Fields
4. Add Field
5. Choose ‘dropdown’ drom the ‘Data Type:’ list at the top
6. Field name: ‘payment_method’ (Exactly the same as you did in Quotes field above)
7. Display Label: ‘Payment Method'(Exactly the same as you did in Quotes field above)
8. Drop Down List: ‘pay_method_list’ (Exactly the same as you did in Quotes field above)
9. Select your default entry, if any
10. Save
11. Refresh the ‘Studio / Invoices / Fields’ list to makes sure you see your ‘Payment Method’ field appear (probably near bottom)

If everything is good, you now should have a fully functioning field, which can receive the data from the Quotes module when the user clicks ‘convert to invoice.

The second last steps, as always, is to make it visible to the user and usable via the ‘Layouts’ feature.

1. Studio
2. Invoices
3. Layouts
4. Edit view
5. Drag a ‘New row” button over to the ‘Overview’ panel
6. Drag your new ‘Payment Method’ field onto new row
7. Arrange remaining fields however you like
8. “Save and deploy’ to save and launch your changes
9. Go create a new Invoice by itself (ie. not by converting from a quote to an invoice), and make sure that your new fields exist in the Invoice as an option and that all the dropdowns are working as expected. If everything looks good, go back in and add the same fields to your ‘detail view’ (instead of Edit view) in layouts if youw want to see those same fields after saving and leaving edit view.

If everything is now satisfactory, let’s proceed to the last step which is testing to make sure the new fields make it through an Quote-to-Invoice conversion.

Test the New Fields Through the Quote-to-Invoice Conversion Process

1. Create a new fake test quote in Quotes module
2. Make sure your new field(s) have data in them
3. Pay special attention to exactly what data you put in each test field because you’ll need to check this.
4. Save your quote
5. Click the ‘Actions’ button
6. Select ‘Convert to Invoice’
7. Did ALL fields perfectly convert over?

If so, you are good to go.

If not, there is probably a problem with the field name. As mentioned above it has to be exact or it won’t make it through conversion.

In my case, I had a failed conversion. The issue was because I had typo’d the field name in the Invoice module and it didn’t perfectly match the original quote module hence – failed conversion. I had to delete the Invoice field and start all over again and recreate it exactly. That’s why we test early and not after we’ve created 10 real quotes, ha.

4 – Dealing with the “Terms” Field and Other Hard-coded Fields

SCRM by default, appends a _c to the end of any custom field that you create. This has a purpose and that is to make sure that your custom fields don’t die when you upgrade your SCRM install. However, in this case, it’s a pain because let’s use the out-of-the-box field name ‘term’ that comes in the Quote module. This field is used to put the poorly spelled ‘Nett 15’ payment terms on the quote. So, I thought I would wisely add a field in the Invoice module (it’s oddly missing as mentioned above) and give it exactly the same name and watch it work.

Nope.

There is no way to create a field called term because it’s hard coded in the system. When you attempt to create it it will automatically create term_c which, as we know, is not a match and won’t make it through conversion from Quote field to Invoice field.

As such, the workaround for this situation is as follows:

1. Create a replacement field for the original ‘term’ in Quotes (first). Give it a better name such as payment_terms. This will create a field called payment_terms_c after saving the field. (see instructions above for more details)
2. Map it to the correct drop field down as per instructions above
3. Remove the original out-of-box term field from the layouts (effectively archiving it from use forever since no users will be able to see it) – see instructions above for changing layouts
4. Rename the original term field to ‘Payment Terms-OLD’ in the Display Label field for this field (just trust me otherwise it’s a recipe for pain if it shares the same Display Label)
5. Insert your newly-created replacement field (payment_terms_c) into the layouts where the old one was. Note: Be sure to do ALL layouts including ‘quick create’ or it will bite you later.
6. Save and deploy

Now you have your Quotes module field ready to go. Now you just follow the instructions above and create an invoice field with the exact same payment_terms_c field name… or is it ‘payment_terms’… let’s see…

Payment Terms

As mentioned above, the ‘payment terms’ dropdown list has spelling errors (Nett 15, Nett 30) and it’s basically void of specific things you’d probably want. Instead of creating my own, I just updated the existing one, correcting the errors and adding some good ones for our business. You can copy this list below, or adjust as you’d like, but here is the list I ended up with:

Oddly, the dropdown list is called ‘quote_term_dom’ if you are searching for it in the Dropdown Editor section of Studio..

ITEM NAME | DISPLAY LABEL

due_upon_receipt | Due upon receipt
due_upon_order | Due upon order placement
due_prior_ship | Due prior to shipping
due_upon_del_rec | Due upon receipt of delivery
due_ord_ship_date | Due on order ship date
net_7 | Net 7
net_14 | Net 14
net_30 | Net 30
net_60 | Net 60
blank | blank

See above for instructions on creating a blank field in a dropdown list

You can edit a dropdown list entry by clicking the pencil icon in the row, making the change, then clicking outside in some white space to mark the change as ready for deployment.

Save the changes with the Save button when complete.

I hope this post helped you get setup more quickly with SCRM.

Tagged howto, installation, SuiteCRM, tips, tutorial