Let the platform do the work
SugarClubContact+1 (877) 842-7276

Delivery and Deployment Guide for Enterprises

Overview

SugarCRM Professional Services has a set of best practices for managing instances, delivering upgraded customizations, and deploying those upgraded customizations into Sugar on-site for our Enterprise customers. The following is an example of deployment practices used by SugarCRM Professional Services team when engaged on Enterprise Sugar development projects. It does not list all possible customizations that can be made in the system, it is intended to be used as a guide for how to automate the deployment of certain types of customizations into an on-premise Sugar instance. The techniques below cannot be used with Sugar's cloud service.

Deploying Application Configuration and Metadata

Use Case: Deployment of System Settings

System settings are stored in various places. In this section, we will address each type of storage for settings, and how to migrate each.

Storage types:

  • config_override.php
    • This is a file stored in the Sugar root directory that allows for overriding core config values (found in config.php). In the UI, the main place to make changes to this is via Admin -> System Settings
  • database 'config' table
    • It is loaded, used, and accessible throughout the Sugar application through the Config API.
    • System Tab Settings
    • Forecasting Settings
    • Portal Settings
    • This is a simple key/value/category store. There aren't too many components that use this. Here are some:

 

config_override.php

System considerations:

  • File System:
    • config_override.php is placed in Sugar web root directory 
  • Scripts required
    • PHP
      • You will need to write a script to read the current config_override.php and merge the existing array with the new values you'd like to change. This can be done one time, and re-used for all future config_override.php changes

 

Steps to migrate:

  1. Assess the values to be changed, added, or removed
  2. Write a script to read the existing config_override.php, make the changes to the array, and re-write the file back to the system.

 

database 'config' table

System considerations:

  • Database:
    • The 'config' table stores all these values. They are stored in a very simple table schema.
  • Scripts required
    • PHP
      • Write a simple PHP script to use Sugar object API. See Figure 1

 

Steps to migrate:

  1. Write script to use our object API for config table changes (See Figure 1)
  2. Copy script to Sugar root directory
  3. Execute the script
  4. Remove the script 

Screenshots:

Figure 1:

 config_override.php Figure 1

 

Use Case: Deployment of Reports

The customer creates a report in the Reports module. They would like to deploy that report so that end users can all access and run it.

System considerations:

  • Database
    • Row is inserted into the Reports module (saved_reports table)
    • (For new team combinations) Row is inserted into the team_sets table
    • (For new team combinations) Rows are inserted into the team_sets_teams table
  • Scripts required
    • SQL
      • Retrieve the relevant rows (saved_reports, team_sets, team_sets_teams) and create a SQL script to insert them.

Additional notes:

  • In the System considerations section, "new combination of teams" means that when creating the report, the end user created the Report with a set of teams that doesn't exist on any other record. This results in new entries in the team_sets and team_sets_teams tables.

Steps to migrate:

  1. Build a report in the dev instance
  2. Select the database rows associated with that report (saved_reports, possibly team_sets and team_sets_teams tables)
    1. example: "SELECT * FROM saved_reports WHERE id = 'REPORT_ID'"
  3. Export the row/rows into a SQL file
  4. Execute on the next system

 

Use Case: Deployment of Dashboards

The customer wants to deploy the pre-built dashboards in an automated way. See Figure 1 below. This example has two dashboards, "Help Dashboard" and "My Dashboard". Each dashboard has zero or more dashlets.

System considerations:

  • Database:
    • Row is inserted into the dashboards table for each user dashboard. The metadata column stores all the dashlets associated with that dashboard, and the assigned_user_id column stores the user who will see this dashboard.
  • Scripts required
    • PHP
      • After deploying the dashboards you will need to run the Quick Repair and Rebuild script found in the admin section.
      • Custom scripts: YES (if applying to multiple users)
        • Because users and id are dynamic, if applying to multiple users, you will need a custom script to retrieve those user ids and set them for each sql insert.
    • SQL
      • Script required to import the entry from the dashboards table.

Steps to migrate:

  1. Build a dashlet against a specific user
  2. Select the database rows associated with that user
    1. example: "SELECT * FROM dashlets WHERE assigned_user_id = 'USER_ID'"
  3. Pick the dashboard you'd like to apply to other users, and export it into a SQL file
  4. Decide what set of users you need to create the dashboard for.
  5. Write a script to pull that list of users, dynamically set the assigned_user_id and id (id must be unique) with the insert query you exported in step 3, and run for each one of those users.

 

Screenshots:

Figure 1

 Dashboards Figure1

Use Case: Deployment of Roles

The customer wants to deploy the roles in an automated way. This includes creating new roles and updating previously existing roles.

System considerations:

  • Database:
    • Row is inserted into the acl_roles table for each role setting. Depending on how specific the role is, we might have acl_fields and acl_actions mapped to roles through acl_roles_actions
  • Scripts required
    • PHP
      • Sugar has a SugarACL object API that can be used to create, read, and write roles and role definitions. 

Steps to migrate:

  1. Write a script using our object API to create or write roles
    1. Define the metadata for the changes or additions to be made
    2. Write logic to add/update based on metadata
  2. Execute script on dev instance and confirm changes
  3. Use script to promote to next instance
  4. Note: See functional sample script below
    1. https://gist.github.com/sadekbaroudi/3191513e2bbce2170326

 

Use Case: Deployment of Teams

The customer wants to deploy the teams in an automated way. This should be done via the Sugar object API.

System considerations:

  • Scripts required
    • PHP
      • Follow steps in "Additional Notes" section below for details on building Team scripts.
      • TeamSets are cached per user by SugarCache.  SugarCache should be cleared after installing new teams.

Additional notes:

To build a script to do this, see the following:

  • modules/Teams/Save.php
    • This file is called when a user posts data through the form in the UI. This code should be replicated (until the Teams module is refactored).
  • modules/Teams/Team.php
    • function save() - this should be called as part of the save
    • function mark_deleted() - this should be called on the object when you want to delete a team, be sure to make sure there are no related users before doing so.

Steps to migrate:

    1. Write a script using our Teams object API
      1. Create needed team object
      2. Set appropriate data on object and/or POST data
      3. After saving, potentially add users to the team
    2. Execute script on dev instance and confirm changes
    3. Use script to promote to next instance

 

Use Case: Deployment of User Settings

The customer wants to deploy the user settings in an automated way. There are a couple of places where we store User settings.

Storage types:

  • User Preferences

This is a key value pair with a serialized and then base64 encoded value. We store many user preferences, all encoded. These are non-critical settings, and can be blown away. However, doing so will require the user to reconfigure their preferences. The data is stored in the user_preferences table. This includes data such as:  Subpanel display order, Timezone preferences, etc.

  • Users module settings

 These are direct values on the Users module (users table). Here we track persistent User attributes such as: Address, Phone number, etc 

User preferences

System considerations:

  • Database:
    • Row is inserted into the user_preferences table for each user setting change.
  • Scripts required
    • PHP 
      • In order to update values with a user's preferences, you would need to write a custom script to read, update, and rewrite to the user_preferences table 

Steps to Migrate:

  1. Write a script using our User Preferences API
    1. Query the database to retrieve the row for a given user
    2. base64 decode the value
    3. unserialize the value
    4. update the data required
    5. serialize the data
    6. base64 encode
    7. rewrite the row to the database
    8. (repeat for all applicable users)
    1. (See modules/UserPreferences/UserPreference.php or modules/Users/User.php, specifically getPreference() and setPreference())
    2. Load the User object
    3. Call getPreference for the specified value
    4. Make changes
    5. Call setPreference for the specified value
    1. Better performance method (direct database queries and updates):
    2. More robust, but slower performance method (API):

 

User table

 

System considerations:

  • Database:
    • Users table is updated
  • Scripts required:
    • SQL
      • You can directly update the Users table directly, provided the data is not encoded or encrypted (like password).

 

Steps to Migrate:

  1. Write a SQL script to update values in the users table based on need
  2. Execute script on dev instance and confirm changes
  3. Use script to promote to next instance

 

Use Case: Deployment of custom fields

A user wants to deploy custom fields created in an automated way. This includes anything created through Studio.

System considerations:

  • File System:
    • Files are potentially created in the following directories:
      • Custom field vardef:
        custom/Extension/modules/<module_name>/Ext/Vardefs/sugarfield_<field_name>.php
      • Custom field label (and app_list_string if necessary): ./custom/Extension/modules/Accounts/Ext/Language/en_us.lang.php
  • Database:
    • The <module_name>_cstm table is created, if it doesn't already exist.
    • The field <field_name>_c is created against that table
  • Scripts required
    • A Quick Repair and Rebuild is required after copying the files and fields_meta_data table values.
    • SQL
      • You will need to insert the relevant entries from the fields_meta_data table

Steps to migrate:

  1. Export the fields_meta_data entries for the custom fields into a script
  2. Copy the files for the custom fields
  3. Apply #1 and #2 to another system, and execute a Quick Repair and Rebuild
    1. Execute the DDL generated by the QRR above

 

Use Case: Deployment of custom modules

A developer creates a custom module and wants to deploy it, this use case refers to a basic module, because each additional feature (logic hooks, relationships,dependencies, etc) has its  own deployment scenario.

System considerations:

  • File System:
    • ./custom/Extension/application/Ext/Include/<package_name>.php
    • ./modules/<new_module>/*
    • ./custom/modules/<new_module>/*
    • ./custom/themes/default/images/*<new_module>*.(gif/png)
    • ./custom/Extension/modules/<new_module>/*
  • Database:
    • new tables <new_module> and <new_module>_audit
      • Note: the DDL gets generated by the Quick Repair and Rebuild script, at which point you can execute manually or automatically
    • fields_meta_data table
      • Note: this stores all the custom fields built through Studio (not Module Builder) after the module is deployed. Make sure you retrieve all rows from this table that apply to this module and create a SQL script to insert into the next system
  • Scripts required
    • After deploying the custom module, you will need to run the Quick Repair and Rebuild script found in the admin section.
    • SQL
      • Script required to import the entry from the <new_module> and <new_module>_audit table.
      • Script required to import fields_meta_data table entries for this module (if there are any)

Additional notes:

  • For a full custom module deployment scenario, this deployment scenario should be ran first then all of the extended module features deployment scenarios should be run:

Steps to migrate:

  1. Copy all files listed in file system section above
  2. Export fields_meta_data table entries as apply to the custom module (if any)
  3. Run Quick Repair and Rebuild
    1. Either manually or automatically run the DDL output from QRR
  4. Test functionality 

Use Case: Deployment of custom Relationships

A user wants to deploy custom relationships created in an automated way. This includes anything created through Studio. 

Follow the same instructions as for Custom Fields, but:

  • Ignore the fields_meta_data table
  • Be sure to consider the following:
    • custom/Extension/modules/<side_1_of_relationship>/Ext/
    • custom/Extension/modules/<side_2_of_relationship>/Ext/
    • custom/Extension/modules/relationships/

Otherwise, the same process applies.

Use Case: Deployment of custom View or Layout metadata (Web)

The user creates custom layouts and views for web from studio and wants to deploy them.

System considerations:

  • File System:
    • Layouts:
      • ./custom/modules/<module>/clients/<platform>/layouts/<layout>/ <layout>.php
    • Views
      • Creating a layout from Studio actually augments the Sidecar view metadata instead of Sidecar layout metadata
      • ./custom/modules/<module>/clients/<platform>/views/<layout>/ <layout>.php
  • Scripts required
    • After deploying you will need to run the Quick Repair and Rebuild script found in the admin section. 

Additional notes:

  • For layouts(record) you have the option to simply save the modified layout. In this case the metadata for the layout can be found in ./custom/working/modules/<module>/<platform>/views/<view>/<view>.php
  • Layouts created from studio create views in .custom/modules/<module>/views
    The created views can be record | list | selection-list
  • For the two popup layouts(created from studio), extra metadata is provided in the ./custom/modules/<module>/metadata/popupdefs.php

 

Use Case: Deployment of custom View or Layout metadata (mobile)

The user creates custom layouts and views for mobile from studio and wants to deploy them.

System considerations:

  • File System: YES
    • Layouts:
      • ./custom/modules/<module>/clients/mobile/layouts/<layout>/ <layout>.php
    • Views
      • ./custom/modules/<module>/clients/mobile/views/<view>/ <view>.php
  • Database: NO
  • Scripts required
    • After deploying you will need to run the Quick Repair and Rebuild script found in the admin section.

Additional notes:

  • Layouts and views are handled the same as with web. From Studio, you can augment detail, edit and list views.

Deploying Application Code and Integrations

Use Case: Deployment of custom CSS (LESS)

 

In order to update branding, developers can deploy customized CSS.

System considerations:

  • File System: YES 
    • ./custom/themes/custom.less
  • Scripts required
    • You will need to run the Quick Repair and Rebuild script found in the admin section to rebuild the Sugar CSS bundles.

Use Case: Deployment of Logic Hooks and Web Logic Hooks

The developer creates custom logic hooks, they want to deploy them.

System considerations:

Logic Hook:

  • File System: YES 
    • application hooks :
      • ./custom/Extension/application/Ext/LogicHooks/<file>.php
    • module specific hooks:
      • ./custom/Extension/modules/<module>/Ext/LogicHooks/<file>.php
  • Scripts required
    • You will need to run the Quick Repair and Rebuild script found in the admin section to rebuild the extensions.

Web Logic Hook:

  • Database: YES
    • Only for weblogic hooks : row is inserted into the weblogichooks table. 
  • Scripts required
    • After deploying the custom hooks and database entry in the weblogichooks table, you will need to run the Quick Repair and Rebuild script found in the admin section.
    • SQL
      • Script required to import the entry from the weblogichooks table.

Use Case: Deployment of custom API endpoints

The user creates a custom api endpoints, he wants to deploy them. 

System considerations:

  • File System
    • clients/<platform>/api/*
    • modules/:module/clients/<platform>/api/*
    • custom/clients/<platform>/api*
    • custom/modules/<module>/clients/<platform>/api/*
  • Scripts required
    • After deploying the custom api you will need to run the Quick Repair and Rebuild script found in the admin section. This will rebuild the ./cache/file_map.php and ./cache/include/api/ServiceDictionary.rest.php files to make your endpoint available.

Additional notes:

  • Logic for how api endpoints are loaded, can be found in ./include/api/ServiceDictionary.php (where api endpoints are loaded from, how they are built on Quick Build and Repair, etc.)

Use Case: Deployment of custom Administration Panels

The user creates custom administration panels, and wants to deploy them.

System considerations:

  • File System:
    • ./custom/Extension/modules/Administration/Ext/Administration/<file>.php
    • ./custom/Extension/modules/Administration/Ext/Language/<langtype.name>.php
    • ./custom/themes/default/images/<icon_image_name>.<img_extension>

and depending on the admin panel url, either :

    • ./custom/modules/<linkUrlModule>/*

or

    • ./custom/modules/<linkUrlModule>/clients/base/layouts/<route_name>/*
    • ./custom/modules/<linkUrlModule>/clients/base/views/<route_name>/*
  • Scripts required
    • After deploying the admin panels, you will need to run the Quick Repair and Rebuild script found in the admin section.

Additional notes:

  • The admin url can specify new sidecar routes, old bwc routes, edit view files, plain scripts, or just open a drawer. Determining the additional resources to be copied may be impossible without a standard in place.

Use Case: Deployment of custom Jobs / Schedulers

The user creates custom jobs and schedulers, and wants to deploy them.

System considerations:

  • File System: YES:
    • ./custom/Extension/modules/Schedulers/Ext/ScheduledTasks/<jobname>.php
    • ./custom/Extension/modules/Schedulers/Ext/Language/<langtype.jobname>.php
  • Database: YES
    • Row is inserted into the schedulers table, if a job is added as a scheduled job using Administration > Scheduler.
  • Scripts required
    • After deploying the custom jobs, you will need to run the Quick Repair and Rebuild script found in the admin section.
    • SQL
      • Script required to import the entry from the schedulers table.