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

Introduction to the Manifest

Overview

Module loadable packages rely on a manifest.php file to define the basic properties and installation steps for the package. This documentation explains the various components that make up the manifest file.

Note: Sugar Sell Essentials customers do not have the ability to upload custom file packages to Sugar using Module Loader.

Manifest Definitions

Inside of the manifest.php file, there is a $manifest variable that defines the basic properties of the module loadable package. The various manifest properties are outlined below:

Name Type Displayed in
Module Loader		 Description

key

 String No A unique identifier for the package
$manifest['key'] = '32837';

name

 String Yes The name of the package
$manifest['name'] = 'Example Package';

description

 String Yes The description of the package
$manifest['description'] = 'Example Package Description';

built_in_version

 String No The version of Sugar that the package was designed for
$manifest['built_in_version'] = '{latest_version}';
Note: Some packages designed for 6.x versions of Sugar are not compatible with 14.2 and should not be installed.

version

 String Yes The version of the package, i.e. "1.0.0" 
$manifest['version'] = '1.0.0';

Note: The version string should be formatting according to  the Semantic Versioning 2.0 standard.

acceptable_sugar_versions

 Array No The Sugar versions that a package can be installed to
$manifest['acceptable_sugar_versions'] = array(
    'exact_matches' => array(
        '{latest_version}',
    ),
    //or
    'regex_matches' => array(
        '{$version|version_format:"minor":"regex"}',
    ),
);
Note: You can define exact versions and/or use a regex formula to define a range. Exact versions will be specified using the exact_matches index and will contain an array of exact version strings (i.e. '14.2.0'). Regex formulas will be specified using the regex_matches index and will contain an array of regular expressions designed to match a group of versions (i.e. '14.2.*').

acceptable_sugar_flavors

 Array No The Sugar products that the package can be installed to
$manifest['acceptable_sugar_flavors'] = array(
    'PRO',
    'ENT',
    'ULT'
);

author

 String No The author of the package (i.e. "SugarCRM")
$manifest['author'] = 'SugarCRM';

readme

 String No The optional path to a readme document to be displayed to the user during installation 
$manifest['readme'] = 'README.txt';

Note: Sugar expects README.txt on the MLP root, if not there, it will use the path specified here.

icon

 String No The optional path (within the package ZIP file) to an icon image to be displayed during installation (e.g. ./patch_directory/icon.gif and ./patch_directory/images/theme.gif)
$manifest['icon'] = '';

is_uninstallable

 Boolean No Whether or not the package can be uninstalled

Acceptable values:
  • 'true' will allow a Sugar administrator to uninstall the package
  • 'false' will disable the uninstall feature
$manifest['is_uninstallable'] = true;

published_date

 String No The date the package was published
$manifest['published_date'] = '2018-04-09 00:00:00';

remove_tables

 String No Whether or not tables generated by the $installdefs['beans'] index should be removed from an installed module (acceptable values: empty or 'prompt')
$manifest['remove_tables'] = 'prompt';

type

 String No
Acceptable 'type' values:
  • module : Use this type if you are installing a module or developing a plugin that should install via the Module Loader.
  • langpack : Use this type to install a language pack via the Module Loader. Any languages installed will automatically be added to the available languages on the Sugar login screen. For an example of a module loadable language pack, refer to the Language Framework page.
  • theme : Use this type to install a Sugar theme via the Upgrade Wizard. Themes are only supported in Sugar 6.x, and will be added to the "Theme" drop-down on the Sugar Login screen.
  • patch : Use this type to install a patch via the Upgrade Wizard.

dependencies

 Array No

Required dependency packages:

$manifest['dependencies'] = array(
    array(
        'id_name' => 'PackageName',
        'version' => '1.0.0'
    )
);

uninstall_before_upgrade

 Boolean No

This will allow Module Loader to ensure all traces of previously installed package versions (including packages that have been upgraded multiple times) have been removed.

$manifest['uninstall_before_upgrade'] = true;

Manifest Example

An example of a manifest is shown below:

    $manifest = array(
  'key' => 1397052912,
  'name' => 'My manifest',
  'description' => 'My description',
  'author' => 'SugarCRM',
  'version' => '1.0.0',
  'is_uninstallable' => true,
  'published_date' => '{doc_date date=$publish_date} 14:15:12',
  'type' => 'module',
  'acceptable_sugar_versions' => 
  array(
    'exact_matches' => array(
        '{latest_version}'
    ),
    //or
    'regex_matches' => array(
        '{$version|version_format:"minor":"regex"}' //any {$version} release
    ),
  ),
  'acceptable_sugar_flavors' => 
  array(
    'PRO', 
    'ENT', 
    'ULT'
  ),
  'readme' => '',
  'icon' => '',
  'remove_tables' => '',
  'uninstall_before_upgrade' => false,
);

Note: If you wish to include a license agreement to prompt during a package installation, include a LICENSE.txt file in the root of your package zip file with the text of your license agreement.
The same can be done with a README.txt file which will be displayed as an expandable panel during installation. Please note that the 'readme' manifest.php entry is only necessary when declaring a different file location than root.

Installation Definitions

The following section outlines the indexes specified in the $installdefs array contained in the ./manifest.php file. The $installdefs array indexes are used by the Module Loader to determine the actual installation steps that need to be taken to install the package.

$installdef Actions

Name Type Description

action_file_map

 Array  ActionFileMap is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

action_remap

  Array ActionReMap is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

action_view_map

  Array ActionViewMap is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

administration

  Array Administration is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

appscheduledefs

  Array Application ScheduledTasks is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

beans

  Array Modules is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

connectors

 Array

An array containing Connector definitions as outlined in the Connector documentation.

$installdefs['connectors'] = array (
     array (
         'connector' => '<basepath>/example/source',
         'formatter' => '<basepath>/example/formatter',
         'name' => 'ext_rest_example',
     ),
);

copy

 Array An array detailing the files and folders to be copied to Sugar

Required parameters for each file in the array:
  • from (string) : The location of the file in the module loadable package
    $installdefs['copy'][0]['from'] = '<basepath>/Files/custom/modules/Accounts/accounts_save.php';
  • to (string) : The destination directory relative to the Sugar root
    $installdefs['copy'][0]['to'] = 'custom/modules/Accounts/accounts_save.php';
Example: 
$installdefs['copy'] = array(
    array(
        'from' => '<basepath>/Files/custom/modules/Accounts/accounts_save.php',
        'to' => 'custom/modules/Accounts/accounts_save.php',
    ),
);

csp

 Array

CSP directives needed for proper operation of the package should be represented as an associative array
where keys are directive names and values are corresponding trusted sources.
Example:

  $installdefs = array(
          ...
          'csp' => [
             'default-src' => '*.trusted.com example.com',
             'img-src' => 'http: https:'
             ...
         ]
         ...
     );

This parameter takes a space-delimited string of domains - just like the admin module. Setting the value of the default-src via MLP is an append operation. The values you put into the csp parameter of your manifest will be added to the CSP list in the admin module. Note that uninstall DOES NOT remove a value.

custom_fields

 Array An array of custom fields to be installed for the new module

Required sub-directives for each custom field formatted as: 
$installdefs['custom_fields'][0]['<attribute>'] = <value>;
  • name (String) : The internal name of the custom field
    Note: The suffix "_c" is appended to all custom field names (e.g. fieldname_c).
  • label (String) : The display label for the custom field
  • type (String) : The type of custom field (e.g. varchar, text, textarea, double, float, int, date, bool, enum, relate)
  • max_size (Integer) : The custom field's maximum character storage size
  • require_option (String) : Defines whether fields are 'required' or 'optional'
  • default_value (String) : The default value for the custom field
  • ext1 (String) : Used to specify a drop-down name for enum and multienum type fields
  • ext2 (String) : Not used
  • ext3 (String) : Not used
  • audited (Boolean) : Denotes whether or not the custom field should be audited
  • module (String) : The module where the custom field will be added

Example:

$installdefs['custom_fields'] = array((
    array((
        'name' => 'text_c',
        'label' => 'LBL_TEXT_C',
        'type' => 'varchar',
        'max_size' => 255,
        'require_option' => 'optional',
        'default_value' => '',
        'ext1' => '',
        'ext2' => '',
        'ext3' => '',
        'audited' => true,
        'module' => 'Accounts',
    ),
);

console

 Array Console is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

dashlets

 Array

An array containing the Dashlet definition.

Required parameters for each file in the array:

  • name (string) : The name of the dashlet. Used for the folder name where the Dashlet files will be stored in Sugar file system.
  • from (string) : The location of the dashlet files in the module loadable package.
$installdefs['dashlets'] = array(
	array(               
		'name' => 'MyDashlet',
		'from' => '<basepath>/MyDashlet'
	)
);

dependencies

  Array Dependencies is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

entrypoints

  Array EntryPointRegistry is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

extensions

  Array Extensions is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

file_access

  Array FileAccessControlMap is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

hookdefs

  Array LogicHooks is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

id

 String A unique id for the installdef definition
$installdefs['id'] = 'unique_name';

image_dir

 String The directory that contains the icons for the module
$installdefs['image_dir'] = '<basepath>/icons';

jsgroups

  Array JSGroupings is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

language

  Array Language is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

layoutdefs

  Array Layoutdefs is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

layoutfields

 Array

An array of custom fields to be added to the edit and detail views of the target modules' existing layouts

logic_hooks

  Array

 An array containing full logic Hook definitions, as outlined in the LogicHook documentation.

$installdefs['logic_hooks'] = array(
      array(
          'module' => 'Accounts',
          'hook' => 'before_save',
          'order' => 99,
          'description' => 'Example Logic Hook - Logs account name',
          'file' => 'custom/modules/Accounts/accounts_save.php',
          'class' => 'Accounts_Save',
          'function' => 'before_save',
      ),
);

LogicHooks defined for install using the $installdefs['logic_hooks'] index, will be added to the module or application folder in the custom directory, in the logic_hooks.php file. Examples:

./custom/modules/Accounts/logic_hooks.php

./custom/application/logic_hooks.php

Note: You will still need to utilize a $installdefs['copy'] index to move the LogicHook class file into the system.

platforms

 Array

Platforms is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

pre_execute

 Array Executes logic from a file (or set of files) before a package is installed

Example:
$installdefs['pre_execute'] = array( 
    '<basepath>/pre_execute.php',
);
Where the content of <basepath>/pre_execute.php is: 
<?php

//pre_execute logic
echo 'pre_execute script<br>';

post_execute

 Array Executes logic from a file (or set of files) after a package is installed

Example:
$installdefs['post_execute'] = array(
    '<basepath>/post_execute.php',
);
Where the content of <basepath>/post_execute.php is:
<?php

//post_execute logic
echo 'post_execute script<br>';

pre_uninstall

 Array Executes logic from a file (or set of files) before a package is uninstalled

Example:
$installdefs['pre_uninstall'] = array(
    '<basepath>/pre_uninstall.php',
);
Where the content of <basepath>/pre_uninstall.php is:
<?php

//pre_uninstall logic
echo 'pre_uninstall script<br>';

post_uninstall

 Array Executes logic from a file (or set of files) after a package is uninstalled

Example:
$installdefs['post_uninstall'] = array(
    '<basepath>/post_uninstall.php'
);
Where the content of <basepath>/post_uninstall.php is:
<?php

//post_uninstall logic
echo 'post_uninstall script<br>';

relationships

 Array An array of relationship files used to link the new modules to existing modules
Note: A metadata path must be defined using meta_data (string): 
$installdefs['relationships'][0]['meta_data'] = 
'<basepath>/SugarModules/relationships/relationships/my_module_accountsMetaData.php';
Where the content of my_module_accountsMetaData.php is:
<?php

$dictionary['my_module_accounts'] = array (
    'true_relationship_type' => 'many-to-many',
    'relationships' =>
        array((
            'my_module_accounts' =>
                array((
                    'lhs_module' => 'my_Module',
                    'lhs_table' => 'my_module',
                    'lhs_key' => 'id',
                    'rhs_module' => 'Accounts',
                    'rhs_table' => 'accounts',
                    'rhs_key' => 'id',
                    'relationship_type' => 'many-to-many',
                    'join_table' => 'my_module_accounts_c',
                    'join_key_lhs' => 'my_module_accountsmy_module_ida',
                    'join_key_rhs' => 'my_module_accountsaccounts_idb',
                ),
        ),
    'table' => 'my_module_accounts_c',
    'fields' =>
        array((
            0 =>
                array((
                    'name' => 'id',
                    'type' => 'varchar',
                    'len' => 36,
                ),
            1 =>
                array((
                    'name' => 'date_modified',
                    'type' => 'datetime',
                ),
            2 =>
                array((
                    'name' => 'deleted',
                    'type' => 'bool',
                    'len' => '1',
                    'default' => '0',
                    'required' => true,
                ),
            3 =>
                array((
                    'name' => 'my_module_accountsmy_module_ida',
                    'type' => 'varchar',
                    'len' => 36,
                ),
            4 =>
                array((
                    'name' => 'my_module_accountsaccounts_idb',
                    'type' => 'varchar',
                    'len' => 36,
                ),
        ),
    'indices' =>
        array((
            0 =>
                array((
                    'name' => 'my_module_accountsspk',
                    'type' => 'primary',
                    'fields' =>
                        array((
                            0 => 'id',
                        ),
                ),
            1 =>
                array((
                    'name' => 'my_module_accounts_alt',
                    'type' => 'alternate_key',
                    'fields' =>
                        array((
                            0 => 'my_module_accountsmy_module_ida',
                            1 => 'my_module_accountsaccounts_idb',
                        ),
                ),
        ),
);

scheduledefs

  Array ScheduledTasks is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

sidecar

  Array Sidecar is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

tinymce

  Array TinyMCE is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

user_page

  Array UserPage is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

utils

  Array Utils is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

vardefs

  Array Vardefs is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

wireless_modules

  Array WirelessModuleRegistery is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

wireless_subpanels

  Array WirelessLayoutDefs is part of the Extension Framework. More detail can be found in the Extension Framework documentation.

Note: Anything printed to the screen in the pre_execute, post_execute, pre_uninstall, or post_uninstall scripts will be displayed when clicking on the Display Log link.

Topics