empty
| 
Sugar Community Edition 5.1 Documentation
Sugar Community Edition Installation and Administration Guide
Version 5.1
|
|
|
|
Chapter 2 Administering Sugar : System
The options listed under this section allow you to configure system-wide settings that apply to all users in your organization.
Use this option to configure the system-wide settings according to your organization’s specifications. Users can override some default settings, such as the datetime format, on their My Accounts page.
Listview items per page. Enter the maximum number of records you want displayed in the list view. The system paginates lists that contain more than the specified number of records.
Display server response times. By default, the footer on every page displays the time taken to respond when users attempt to perform an action, such as logging in or opening an item, in Sugar. Deselect this box if you do not want to display the response time.
Prevent user customizable Homepage layout. Select this box if you want to prevent users from moving Sugar Dashlets on the Home page. However, users can still create additional Sugar Dashlets.
Maximum number of Sugar Dashlets on Homepage. Enter the maximum number of Sugar Dashlets you want displayed on the Home page. Users will not be able to add more than the number of Sugar Dashlets that you specify. The default value is 15.
Subpanel items per page. Enter the maximum number of records you want displayed in the List View. The system paginates lists that contain more than the specified number of records.
Display tabs on login screen. By default, the Login page displays the Sugar module tabs on the Login page. Deselect this box if you do not want to display these tabs on the Login page.
Prevent user customizable subpanel layout. Select this box if you want to prevent users from dragging and dropping sub-panels to a different location in their Detail View layout.
Show Full Name (not Login). Select this box if you want the full name for users displayed instead of their login names.
|
2.
|
|
3.
|
To restore the default settings, click Restore; to exit the page without saving your changes, click Cancel.
|
Current logo. Displays your current organization’s logo that displays in the User Interface.
Upload new logo. Enter the path to the location of the logo that you want to upload from your local machine. Or, click Browse to navigate to the location of the logo on your local machine. The dimension should be 212 X 40, with the standard transparent background color, in PNG or JPG format.
|
2.
|
|
3.
|
To restore the previous settings, click Restore; to exit the System Settings page without saving your changes, click Cancel.
|
If your organization has implemented LDAP or Active Directory authentication, you can also enable authentication in Sugar. When your users attempt to log into Sugar, the application authenticates them against your LDAP directory or Active Directory. If authentication is successful, the user is allowed to log into Sugar. If you are using LDAP with SOAP, you will need to specify the encryption key for the system and forward the key to your users.
If your users are using the Sugar Plug-in for Microsoft Outlook, they will need to enter this key number in Outlook. The Sugar Plug-in for Microsoft Outlook uses this key to encrypt user passwords before forwarding them to Sugar for authentication. Sugar decrypts the password with the same key and forwards the user names and passwords to the LDAP server for authentication. If authentication is successful, the users are allowed to access Sugar through the Sugar Plug-in for Microsoft Outlook.
|
1.
|
In the LDAP Authentication Support sub-panel, select the Enable LDAP box and enter the following information:
|
Server. Enter the LDAP server name.
Port Number. Enter the server’s port number.
Base DN. Enter the base DN name.
Bind Attribute. Enter the attribute name that is used to bind the user’s name in LDAP.
Login attribute. Enter the attribute name that is used to search for the user in LDAP.
Authenticated User. Enter the user name.
Authenticated Password. Enter the user’s password.
Auto Create Users. Select this option check the Sugar database for the user name and add it if it does not exist in the database.
Encryption Key. If you are using LDAP with SOAP, enter the encryption key to encrypt user passwords in the Sugar Plug-in for Microsoft Outlook.
|
2.
|
|
3.
|
If you are using a proxy server to connect to the Internet, you will need to enter the information here to allow the system to check for Sugar updates.
Use proxy server. If you want to connect to the Internet through a proxy server, select this option.
Proxy Host. Enter the name of the proxy server host
Port. Enter the port number for the proxy host.
Authentication. Select this box if you want to enable proxy authentication to allow Sugar to connect to the company’s proxy server.
User Name. Enter the user name.
Password. Enter a password for the user.
|
2.
|
|
3.
|
|
1.
|
Select the Enable SkypeOut integration box.
|
|
2.
|
|
3.
|
If you have installed the Sugar Plug-in for Microsoft Word, this option allows you to perform a mail merge with Word documents. For example, you can merge contact information from Sugar with form letters created in Microsoft Word.
|
1.
|
Select the Enable mail merge box.
|
|
2.
|
To restore the previous setting, click Restore. To exit the System Settings page without saving your changes, click Cancel.
Validate user IP address: Select this option to validate, for security purposes, the IP addresses of users who log into Sugar.
Log slow queries. Select this option to log the system’s slow responses to user queries in the sugarcrm.log file. This information is for performance tuning investigation.
Maximum upload size. Enter the maximum file size, in bytes, that users are allowed to upload.
Portal Session Timeout. Enter the maximum time, in seconds, for a SugarPortal session. The session will timeout when the time limit is reached.
Log memory usage. Select this option to record memory usage in the sugarcrm.log file.
Slow query time threshold. Specify the threshold, in milliseconds, that defines slow queries. Queries that take longer than the threshold time are logged in the sugarcrm.log file. This information is for performance-tuning investigation.
Display stack trace of errors. When you select this option, if an error occurs when users are running the application, the system displays where the error occurred in the application’s stack trace. This information is for debugging purposes.
Developer Mode. Select this option to disable caching so that you can immediately view changes made to language, vardefs, and template files.
|
2.
|
|
3.
|
To restore the previous settings, click Restore; to exit the System Settings page without saving your changes, click Cancel.
|
The Sugar Logger logs events that occur in the Sugar application. By default, the logs are written to sugarcrm.log in the Sugar root directory.
When you upgrade to Sugar 5.1, Sugar automatically parses your Logger settings from the log4.php properties file of your previous Sugar version and populates the Logger Settings sub-panel with the information.
|
•
|
debug: Logs events that would help to debug the application.
|
|
•
|
info: Logs informational messages.
|
|
•
|
warn: Logs potentially harmful events.
|
|
•
|
error: Logs error events in the application.
|
|
•
|
fatal: Logs severe error events that leads the application to abort. This is the default level.
|
|
•
|
security. Logs events that may compromise the security of the application.
|
|
•
|
off. The logger will not log any events.
|
When you specify a logging level, the system will create log files for the specified level as well as higher levels. For example, if you specify ‘Error’, the system creates log files for ‘error’, ‘fatal’, and ‘security’.
Log File Name. Specify a name for the log file.
Extension. Enter the file extension. The default is .log.
Append After File Name. From the drop-down list, select a time period to append to the file name. This makes it easier to identify the log that you want to view.
Log Level. From the drop-down list, select the event level that you want to capture in the log file. The default is fatal.
Default Date Format. Enter the default date format for the log file. This format must be supported by strftime. The default is %c.
Maximum Number of Logs. Specify the maximum number of log files to save. When the number of log files exceed this limit, Sugar deletes the log file that was created first. The default is 10 logs.
The Scheduler integrates with external UNIX systems and Windows systems to run jobs that are scheduled through those systems. You can schedule the following types of jobs:
Prune Tracker Tables. This job deletes older activity data.
Check Inbound Mail Accounts. This job monitors inbound emails in active mail accounts that you set up using the Inbound Email option in the Email panel of the Admin page.
Run Nightly Process Bounced Campaign Emails. This job polls any mail account in which, the “Possible Actions” parameter is set to “Bounce Handling”. This is an essential component of monitoring mass email campaigns.
Run Nightly Mass Email Campaigns. This job processes the outbound email queue for your organization’s mass campaign emails.
Prune Database on 1st of Month. This job reads all the tables in your Sugar database, finds records that have been soft-deleted (deleted = 1), creates a large SQL file, and physically deletes those records on the 1st of every month. It is mostly a performance job, and is not essential to the use of Sugar. The backup files are placed in cache/backups with time-stamped filenames.
Update Tracker Session Tables. This job sets the status of timed-out sessions.
For UNIX and Linux systems, you will need to add a new cronjob to your Crontab. For Microsoft Windows, you can use the Task Scheduler.
|
1.
|
At the command prompt, type crontab -e.
|
* * * * * cd /path/to/sugar/crm; php -f cron.php > /dev/null 2>&1
|
3.
|
Ensure that the /path/to/ is correct for your instance.
|
In a properly configured virtual host environment provided by your host, Apache will run as your Login user ID for files in your virtual directory. If you are unsure, contact the Customer Service department for your host.
|
a.
|
Search for a file named httpd.conf. Typically, this file is located in the /etc folder. It will vary with the distribution.
|
|
b.
|
Open the file using a text editor and locate a line that starts with “User”. The word(s) that follow it directly is the name of the User that Apache will run as on your system.
|
The Sugar Scheduler is designed to work with PHP and its extensions; specifically the database connector, the IMAP libraries, and the cURL libraries.
|
a.
|
Type which php. On most correctly configured PHP installations, you will find the binary in /usr/bin or /usr/local/bin. If so, move on to Step 3.
|
|
b.
|
Type find / -name php. Typically, this command will return a long list. Parse through the list to find an executable file named php.
|
|
c.
|
If you cannot find the PHP binary, scroll down to the Troubleshooting Tips at the end of this section and read item No. 2.
|
|
3.
|
Create a cronjob for the Apache user
|
|
a.
|
Type crontab -e -u [the Apache user].
|
* * * * * cd /path/to/sugar/crm; php -f cron.php > /dev/null 2>&1
|
c.
|
To fine tune this job, change the first two “*”. The first is the “Minutes” value, the second is the “Hours” value.
|
"*/3 * * * * cd /path/to/sugar/crm; php -f cron.php > /dev/null 2>&1
|
a.
|
At a terminal prompt, copy and paste the command for your cronjob, and run it; the logic here is that if the command will execute successfully when run manually, the crontab will be able to execute successfully as well.
|
* * * * * cd /var/www/html/sugarcrm; php -f cron.php > /dev/null 2>&1
This folder should contain the cron.php file.
If your system has a 4.x version of PHP, the PHP-CGI binary is named php.exe and is typically located in the root folder of your PHP install folder. To allow it to interact with the dynamic libraries, specify the location of the php.ini file. This can vary from system to system. If you are unsure, assuming that php.exe is located in c:\php, enter the following command at the command prompt:
The system will identify the php.ini file and its location.
If your system has a 5.x version of PHP, the PHP-CGI binary is named php-cgi.exe (not php-cli.exe) and is typically located in the root folder of your PHP install folder. To allow it to interact with the dynamic libraries, specify the location of the php.ini file. This can vary from system to system. If you are unsure, enter the command described above.
The system will identify the php.ini file and its location.
|
a.
|
At the bottom of the default screen, you will see the contents of the commands you need to add to a batch file.
|
b.
|
Open notepad.exe, copy and paste what Sugar’s recommendation into a blank file.
|
|
Note:
|
This is only a recommendation. It may not work for your particular instance. Check the folder paths because they are often the cause for problems with the Scheduler.
|
|
a.
|
Click Start and navigate to Control Panel/Scheduled Tasks/Add Scheduled Task.
|
|
c.
|
Schedule a daily job, and ensure that you select Open advanced properties for this task when I click finish.
|
|
d.
|
|
e.
|
Check off Repeat task to enable the fields below it, and select Every Minute or specify the interval you think is appropriate.
|
|
1.
|
Job Name. Enter a name for the job.
Status. From the drop-down list, select Active to run the job at the specified intervals; select Inactive if you only want to save the job schedule information but not run the job.
Job. Select a job from the drop-down list. The OR field is not used.
Interval. Specify the time interval to check for new scheduled jobs.
|
3.
|
For advanced options, click the Advanced Options link below the Job field.
|
The Advanced Options sub-panel displays below.
Execute If Missed. Select this box to run any jobs that the scheduler missed.
Date & Time Start. Click the Calendar icon and select the start date for the job; select the time, in hours and minutes, from the adjacent drop-down list.
Date & Time End. Click the Calendar icon and select the end date for the job; select the time, in hours and minutes, from the adjacent drop-down list.
Active From. From the drop-down list, select the time, in hours and minutes, when the job becomes active.
Active To. From the drop-down list, select the time, in hours and minutes, when the job becomes inactive.
|
5.
|
|
6.
|
To export one or more scheduler definitions in a .csv file format to a local machine, select them from the list and click Export.
|
|
1.
|
The Schedule List page displays on the page.
|
2.
|
Select any job from the job list to view its settings or the Job log. You can edit, duplicate, or delete the settings. You can also delete a job by clicking the del icon corresponding to the job in the Schedule list.
 |
|
3.
|
|
4.
|
Make the necessary changes and click Save to update the settings; click Cancel to exit the page without saving your changes.
|
|
1.
|
The Sugar Scheduler fails to run even though the cron.log file shows that the crontab is triggering the new job.
|
|
•
|
The Apache user's PATH does not include the location of the php.ini file, and thus the external libraries (such as mod_mysql and mod_imap) are unavailable at run time.
|
|
•
|
Change the crontab entry to include a PHP switch to explicitly define a php.ini to use as shown below.
|
* * * * * php -c /path/to/your/php.ini -f cron.php > /dev/null 2>&1"
|
•
|
Determine if this is an option at this time by finding either “curl” or “wget” on your system. This is done with the commands “which curl” and “which wget”.
|
If you use cURL, your crontab entry should look as follows:
* * * * * curl --silent http://yourdomain/yoursugarcrminstance/cron.php
If you use wget, your crontab entry should look like:
* * * * * wget -q http://yourdomain/yoursugarcrminstance/cron.php
|
Note:
|
Both curl and wget have numerous switches that do not always map to different versions on different platforms. Experiment in the terminal until you find the “perfect” line, and add it as the line for your crontab entry.
|
|
1.
|
The most common problem is that the PHP binary does not have the proper libraries available at run time. As a result, it cannot make calls to your database or to your Email server. To force PHP to be aware of these libraries, it needs to access the php.ini file, which in turn tells it where to find everything that is available.
|
|
a.
|
Locate the php.ini file: if you are unsure, run the following command:
|
The system identifies the php.ini file and its location.
|
2.
|
The second most common breakage is incorrect paths to the extensions that PHP needs; a map is useless if the information is bad.
|
|
a.
|
Open php.ini in your favorite text editor.
|
|
c.
|
The pertinent entry is “extension_dir”.
|
|
d.
|
Keeping in mind that this file piggybacks on Window's $PATH$ variable, double-check the paths listed.
|
|
e.
|
Correct any errors - sometimes giving an absolute path solves hard-to-diagnose problems, for example, full path listing from c:\... onwards.
|
|
f.
|
Open your php.ini file in a text editor.
|
|
i.
|
Make sure that the necessary extensions are uncommented (no “;” preceding the line). The bare minimum for Sugar Scheduler to run is to have php_curl, your database connector, typically php_mysql (for PHP5), and php_imap.
|
Use this option to capture system configuration for diagnostics and analysis. The diagnostic tool pulls up system information and stores it in a zip file on the server for download. When you send a help request to Customer Support, you can attach the file because it summarizes all the basic information required to resolve the problem.
|
1.
|
|
2.
|
To capture specific configuration information, click the Advanced link below the Execute Diagnostic button.
|
The system displays a list of system configuration files. By default, the system captures configuration information for all the selected files.
SugarCRM Config.php - Copies the config.php file from the root directory after replacing the DB password with asterisk for security purposes.
SugarCRM Custom directory - Copies the custom directory to a Zip file to enable Customer Support to know what has been customized through the Layout Editor.
phpinfo() - Executes phpinfo and stores it in a file.
MySQL - Configuration Table Dumps - copies a few tables from the database and replaces sensitive information with asterisk for security purposes.
MySQL - All Tables Schema - writes the schema for all tables to an HTML file.
MySQL - General Information - Pulls up some general information, like MySQL version, character sets, etc.
MD5 info - Runs md5 checks on all files in the sugar directory and compares it against a stock Sugar installation’s md5s. This enables Customer Support to learn which, if any, files have been manually customized.
BeanList/BeanFiles files exist - If a custom module has been loaded, and the author did not define these references correctly, it can cause problems. This action checks all the references to ensure they are correct.
SugarCRM Log file - copies the log file.
Sugar schema output (VARDEFS) - copies the Sugar database schema.
|
3.
|
Deselect the ones you do not want to view and then click Execute Diagnostic.
|
|
4.
|
To view the file, click the Download the Diagnostic file link at the bottom of the page; to delete the file, click the Delete the Diagnostic file link.
|
|
5.
|
If you choose to download the file, the File Download dialog box displays on the page. To view its contents, click Open, and click the file you want to view. To save the Zip file contents, click Save, and select a location on your local machine.
|
When you obtain the Sugar upgrade .zip file from Sugar, you can save it to your local machine and upload it into Sugar using the Upgrade Wizard. For more information, see the Sugar Upgrade Guide.
Use this option to backup the Sugar configuration files. Note that this option does not backup the database.
|
1.
|
|
2.
|
In the Directory field, specify a directory that is writable by the same user as the Apache process.
|
|
4.
|
To ensure that backup can be performed, click Confirm Settings.
|
|
5.
|
Click Run Backup to create the .zip file of your Sugar application files.
|
|
Note:
|
Use this option to upgrade and rebuild data from a previous version of Sugar for the current version of the program. You also use this option to convert a Sugar installation to offline mode.
Quick Repair and Rebuild: Repairs and rebuilds the database, extensions, vardefs, Sugar Dashlets, and so on for selected modules. Click this option, select the modules you want to repair, and click Repair.
Repair Database: This option is applicable to MYSQL databases only. It repairs your Sugar database based on values defined in the vardefs. You can choose to display the SQL that will be executed on the screen, export it, or execute it.
Clear Chart Data Cache: Removes cached data files that charts use.
Clear Template Data Cache: Removes cached template files. Click this option, select the modules you want to repair, and click Repair.
Clear Vardefs Data Cache: Removes vardefs from the cache. Click this option, select the modules you want to repair, and click Repair.
Rebuild .htaccess file: Rebuilds the .htaccess file to limit access to certain files directly.
Rebuild Audit: Rebuilds the audit table.
Rebuild Config File: Rebuilds the config.php file by updating the version and adding defaults when not explicitly declared. Click this option to check the file and if, necessary, click Rebuild.
Rebuild Extensions: Rebuilds extensions including extended vardefs, language packs, menus, and administration
Rebuild Relationships: Rebuilds relationship metadata and drops the cache file.
Rebuild Schedulers: Rebuilds your out-of-the-box Scheduler Jobs. Click this option and then click Rebuild.
Rebuild Sugar Dashlets: Rebuilds the cache file for Sugar Dashlets.
Rebuild Javascript Languages: Rebuilds Javascript versions of language files.
Rebuild JS Compressed Files: Copies original Full JS Source files and replaces existing compressed JS files.
Rebuild JS Grouping Files: Re-concatenates and overwrites existing group files with latest versions of group files.
Rebuild Minified JS Files: Copies original Full JS Source Files and minifies them, then replaces existing compressed files.
Repair JS Files: Compresses Existing JS files - includes any changes made, but does not overwrite original JS Source files
Repair Roles: Repairs roles by adding all new modules that support access control as well as any new access controls to existing modules.
Repair Indexes: Validates and, optionally, repairs database indexes against definitions in vardef files.
Repair Inbound Email Accounts: Repairs Inbound Email accounts and encrypts account passwords.
Remove XSS: Removes XSS Vulnerabilities from the database. Click this option, select a module, and click Execute. If any XSS strings are found, the system lists them in the Object(s) found field below.
Repair Activities: Repairs Activities (Calls, Meetings) end dates.
Enable/Disable Seed Users: Enables or disables seed users populated during demo installation. Click this option, and if the seed users are enabled, click Deactivate to disable them. If the seed users are disabled, click Activate to enable them.
For each new currency that you define, enter the name, symbol (for example, $), conversion rate to the US $, the currency code (such as CDN for the Canadian dollar). Set the Status to Inactive if you do not want users to use this currency for transactions.
Use this option to set system-wide default formats for date, time, language, name, and currency. If you are using MySQL, you can also specify the collation order for records in the application.
Default Date Format. From the drop-down list, select a date format for all records. Users can override the default format by setting a different date format in their My Account page.
Default Time Format. From the drop-down list, select a time format to display in all records such as Cases. Users can override the default format by setting a different time format in their My Account page.
Default Language. From the drop-down list, select the default language for the Sugar User Interface. Users can select a different language from the login page, provided they have installed the appropriate language pack.
Default Name Format. Enter the default salutation and name format to display in list views and detail views. You can specify any combination of salutation first name, and last name. For example: Mr. John Smith, Mr. Smith, or John Smith. Users can override the default format by setting a different time format in their My Account page.
Use this sub-panel to override the default currency that you set during installation. On the My Accounts page, users can override the default currency that you specify in this panel.
Currency. Enter the name of the currency that your organization uses to conduct business.
Currency symbol. Enter the symbol for the currency.
ISO 4217 Currency Code. Enter the ISO code for the currency.
1000s Separator. Specify a delimiter to separate thousands when users specify a numeric value for the amount.
Decimal Symbol. Specify a default decimal symbol.
Use this panel to specify export settings such as the delimiter used to separate data in export files and the default character set used to export data from Sugar. The settings you specify here apply to all users in the organization. However, users can define a different default export character set on their My Account page to export data from Sugar.
By default, Sugar uses UTF-8 to store data and CP1252 to export data. For locales that use character encoding other than CP1252, you must specify the appropriate default character set. This ensures that the character set used by the Sugar system to create the exported file is mapped to the correct character set on the user’s machine. For example, MS Windows uses SJIS in Japan. So, for users in this locale, you will need to select SJIS as the default export character set.
By default, both users and administrators can export files from Sugar. However, you can prevent users from exporting files.
Export Delimiter. Specify the delimiter, such as a comma or a period, to use while exporting data.
Default Export Character Set. The default is CP 1252. For locales other than US and Western Europe, select the appropriate character set from the drop-down list.
Disable export. Select this option if you want to prevent end users and users with administrative privileges from exporting data.
Admin export only. Select this option to allow only users with administrative privileges to export data.
This sub-panel displays only if you are using the MYSQL database. You can select the desired collation order from the drop-down list. The default is utf8_general_ci.
|
|
|
|
|
Copyright 2004-2008 SugarCRM Inc.
Product License
