Sugar Community Edition Installation and Administration Guide Version 5.0

Developer Tools

The Developer tools sub-panel displays options to build new modules and customize existing ones. The Module Builder enables you to build custom modules and Studio enables you to customize existing modules.

After you build a module, use the Module Loader to install it in Sugar. For more information, see “Module Loader” on page 45.

Module Builder

Use the Module Builder to create custom modules.

The process of creating a custom module is as follows:

1.	Create a package to house the new module. You can create one or more modules for the package.

2.	Create a module using one of the following templates that Sugar provides for you.

Basic. This template provides basic fields such as ID, Date Entered, and Created By. Use this template to create a module from scratch.

Company. This template provides organization-specific fields such as Company Name, Industry, and Billing Address. Use this template to create a module that is similar to the Accounts module.

Person. This template provides individual-specific fields such as salutation, title, name, address, and phone number. Use this template to create a module that is similar to the Contacts module or the Leads module.

Issue. This template provides case and bug-specific fields such as ID, Description, and Created By. Use this template to create a module that is similar to the Cases module or Bug Tracker module.

3.	Customize existing fields and labels from the selected template and create new fields as needed.

Note:

You cannot edit the default fields in the selected template but you can duplicate them and save them as new fields to customize them.

4.	Customize page layouts for List View, Edit View, Detail View, and Search fields if needed.

5.	Create relationships between the new module and other modules.

6.	Save the package and distribute it.

You can choose one of the following options to distribute the package:

•	Publish. This option is designed for distribution to specific users or customers. The system creates a zip file, which you can save on your local machine. You can then email it to one or more individuals who can use the Module Loader to upload the zip file into their Sugar instance.

Through Studio, you can add or remove fields and make other changes to a published module.

•	Deploy. This option is designed to install the custom module on your Sugar instance and make it available to all users in your organization. Through Studio, you can add or remove fields and make other changes to a deployed module.

•

Export. This option is designed for distribution to developers. The system creates a zip file, which you can save on your local machine and email to other developers. Using the Module Loader, developers can install it on their Sugar instance and customize it further if necessary. The package is visible only in Module Builder and, hence, only developers can access it.

A Sugar module has multiple relationships with other Sugar modules. Therefore, when you create a custom module, you must define its relationship with other Sugar modules. For more information, see “Creating Relationships” on page 69.

To create a package

1.	In the Developer Tools sub-panel, click Module Builder to view the Module Builder page.

2.	Click New Package.

The Package page displays on the screen.

3.	Enter a name for the package and click Save.

The system refreshes the page and displays options to duplicate, publish, deploy, export, and delete the package.

4.	Enter information for the following fields:

Author. Enter your name as the creator of the package.

Key. Enter an alphanumeric key to distinguish modules with similar names. The system will prefix all class names, directories and tables names with this key.

Description. Enter a brief description of the package.

5.	Click Save to create the package.

6.	Click Duplicate to create a copy of the package.

The system appends a “1” to the package name and saves it as a new package.

7.	Click Publish to save the package as a zip file.

8.	Click Deploy to deploy the package on your Sugar instance.

9.	Click Export to save the package as a zip file.

10.	Click Delete to delete the package.

To create a module

1.	Click the New Module icon on the Package page.

The Module page displays

2.	Enter information for the following fields:

Name. Enter a name for the module.

Label. Enter a name for the module that you want displayed in the Sugar User Interface.

Package. The name of the package associated with this module displays on the page.

Navigation Tab. By default, this option is enabled to create a tab for the module that is identical to other Sugar module tabs.

Type. Click a template to select it for your module

3.	Click Save to save the module and add it to the package.

The system refreshes the page to display the selected template. The new module is nested within the package listed in the Packages panel on the Module Builder home page.

You can now view the fields available in the template, add new fields to your module, and create relationships with other Sugar modules.

To view and create fields

1.	In the Packages panel of the Module Builder home page, select the module from the package and click Fields.

The system displays the default fields available in the template.

2.	To view an existing field, click its name and view its properties in the right panel.

You cannot edit the default fields. You can, however, edit and delete custom fields.

3.	To add a new field, click Add Field and enter the information as described in “To add custom fields” on page 73.

4.	Click Save to create the new field.

The new field is now listed underneath the module name.

To view and edit page layouts

1.	In the module, click View Layouts.

2.	Select the page layout that you want to edit.

You can edit List View, Detail View, Edit View, and the Search form.

3.	Edit the layout as described in “Editing the Page Layout” on page 79.

Creating Relationships

A Sugar module has multiple relationships with other modules. Therefore, when you create a module, you must define its relationship with one or more modules. For example, Accounts is related to Contacts, Leads, Opportunities, and several other modules. Related records from these modules display in sub-panels on an account’s detail page. Therefore, when you create a module, you must define its relationship with one or more modules. You create one relationship at a time.

When you create a relationship, you are also selecting the type of information that you want to display. For example, when you create a relationship with the Contacts module, you can choose contacts for opportunities or accounts. Therefore the relationship type varies depending on the module with which you create the relationship.

Similarly, you can specify the modules in which you want to display the custom module as a sub-panel.

To view and create relationships

1.	On the module’s page, click View Relationships.

Existing relationships display on the page.

2.	To create a relationship, click Add Relationship.

The relationship fields display in the Properties tab in the right panel.

3.	Enter information for the following fields:

Relate to. From the drop-down list, select the module you want to associate with your custom module.

Label. Enter a name of the relationship.

Subpanel. From the first drop-down list, select Default if you want to display the associated module as a sub-panel on the detail page of the custom module.

From the second drop-down list, select Default if you want to display the custom module as a sub-panel on the detail page of the related module. If not, select a specific module. The sub-panel options vary depending on the module that you associate with your custom module.

4.	Click Save to create the relationship.

The new relationship displays under the Add Relationship button in the middle panel.

To distribute a package

1.	In Module Builder, select the package and click Publish, Deploy, or Export.

When you select Publish or Export, the system saves it as a zip file that you can export to your local machine and distribute as needed. When you select Deploy, the system installs all the custom modules in the package on your Sugar instance.

2.	When you choose Publish or Export, select Save to Disk and click OK.

Use the Module Loader to upload the file from your machine into Sugar and install the module. For more information, see “Module Loader” on page 45.

Deleting Packages

You can delete a package if necessary. When you delete a package, all the files that it contains are also deleted. If you delete a package after it has been installed, you can uninstall it after deletion using the Module Loader. When you uninstall a package, you have the option of retaining or removing the database tables.

You do not need to delete a package before you install a newer version. The files from the new version will override any existing files from the earlier package.

Studio

Studio enables you to customize modules by adding new fields, editing existing fields, field labels, page layouts, sub-panels, and Quick Create forms. You can export a customized module to your local machine and upload in into Sugar using the Module Loader.

Users can use their My Account page to override some of the configurations that the administrator makes in Studio. For more information, see “Setting Your Preferences” in the Sugar Community Edition User Guide.

The Studio home page displays a list of existing modules in the left panel. These include the default Sugar modules as well as any custom modules that you create. The associated fields, labels, layouts, and sub-panels for each module are grouped within the module. You can click the Plus sign (+) preceding the module name to view them. The right panel displays the same information in the form of icons. You can click a module in either panel to drill down to its fields, labels, layouts, and sub-panels.

Editing a Module

You can add and edit custom fields, drop-down lists, and field labels. You can also edit the default layout and sub-panels. After you complete editing the module, the updated version will not available to other user until you publish it. You can use Studio to make changes to a published module.

To edit a module

1.	In Studio, select the module that you want to edit.

The screen above illustrates the Accounts module.

2.	Select from the following options:

Labels: Select this option to edit field labels. For more information, see “Editing Field Labels” on page 78.

Fields: Select this option to create and edit custom fields. For more information, see “To add custom fields” on page 73. Select this option to edit and create drop-down lists. For more information, see “Creating and Managing Drop-down Lists” on page 75.

Layouts: Select this option to edit the List View, Detail View, Edit View, Search form, and Quick Create form. For more information, see “Editing the Page Layout” on page 79.

Subpanels: Select this option to edit one or more of the module’s sub-panels. For more information, see “To edit a sub-panel” on page 82.

3.	Click Save to save your changes.

Creating and Managing Custom Fields

You can add custom fields to any module in Sugar. When you add a custom field, the application adds the field to the appropriate database table and stores the generated metadata. You can then add the fields to the desired layout, such as Edit View and Detail View. For custom modules, you can create fields in the Module Builder. Use Studio to edit a custom module after it has been published.

To add custom fields

1.	To add a new custom field to a module, select the module and then click Fields.

The page displays the current default fields that Sugar provides as well as any existing custom fields. It displays the Field Editor in the right panel.

The field types that you can create are shown on the screen below:

The information that you need to specify varies depending on the selected data type. First, select the module in which to add custom fields. Then you can define field properties for the new field. You can edit and delete custom fields.

2.	In the Field Editor, enter values for the following:

Data Type. From the drop-down list, select one of the data types listed below.

•	Text Field. Creates a text field for fields such as first name and last name.

•	Address. Creates fields for street, city, postal, state, and country.

•	Checkbox. Creates a checkbox.

•	Currency. Creates a field to enter an currency. The system automatically creates a field of the currency type if the field does not exist.

•	Date. Creates a field to enter a date.

•	DropDown. Creates a drop-down list. For more information on drop-down lists, see “Creating and Managing Drop-down Lists” on page 75.

•	Decimal. Creates a field to specify the precision past the decimal point.

•	HTML. Creates an HTML field to add HTML snippets.

•	Integer. Creates a field to specify positive or negative numbers. You can specify a range with the min and max value fields.

•	MultiSelect. Creates a drop-down list to select multiple values.

Note:

You cannot create a MultiSelect field in the Module Builder.

•	Flex Relate. Creates a field and a drop-down list from which you can associate a related record. You can add only one Flex Relate field to a module. Hence, this option does not display in the Data Type drop-down list if you attempt to add it to a module that already contains a Flex Relate field.

•	Phone. Creates a field to enter a phone number.

•	Radio. Creates a radio button.

•	Relate. Creates a field to associate a record with another record. You can add multiple Relate fields to a module.

•	Parent. This data type displays only if the module does not currently contain a Parent field. Creates a drop-down list to specify a parent module for a one-to-one parent-child relationship.

Depending on the data type that you select, you will need to specify values for some of the fields listed below.

•	Field Name. Enter a name for the field. The system adds it to the Sugar database.

•	Field Label.The system automatically creates and displays the field label that will be added to the database.

•	Label Value. The system uses the field name as the label value. You can enter a new value if needed.

•	Help Text. Enter descriptive text for the field. This text displays when the user points the cursor at the field.

•	HTML. This box display when you select the HTML data type. Enter the HTML code in this box.

•	Default Value. Enter a default value for the field, if necessary.

•	Max Size. Enter the maximum number of characters that the field can contain.

•	Mass Update. This box displays when you select the DropDown data type or the Date data type. For information on creating a drop-down list, see “To create a drop-down list” on page 76.

•	Min Value. This field displays if you select the Integer data type. Enter a minimum value during data input.

•	Max Value. This field displays when you select the Integer data type. Enter a maximum value during data input.

•	Precision. This field displays when you select the Decimal data type. Enter the number of digits you want to express the precision for the fractional part of the number.

•	Required Field. Check this box to specify that users must enter a value for the field.

•	Audit. Check this box to display field values when a user clicks the View Audit Log link.

•	Duplicate Merge. From the drop-down list, specify one of the following options for the Duplicate Merge functionality on a record’s detail page.

•	Enabled: The field can be used as a filter, and will be a default filter field.

•	Disabled: This field cannot be selected as a filter.

•	In filter: This field will be available to be used as a default filter.

•	Default Selected Filter: This is a filter field by default.

•	In Filter Only: This field can be selected as a filter to search for identical fields during a duplicate merge operation. However, you cannot merge the values into a single field.

3.	Click Save to create the field.

The new field is listed in the Custom section. The system appends the field name with ‘_c’ to indicate that it is a custom field.

To edit and manage fields

1.	To edit a field, select it from the list to display its details in the Field Editor.

2.	Make the necessary changes and click Save.

3.	To duplicate the field, click Clone, enter a new name, and click Save.

4.	To delete the field, click Delete.

5.	Click Save to update the field.

Creating and Managing Drop-down Lists

Most modules display at least one drop-down list consisting of several values that users can choose from. For example, when users creates an account, they can choose a specific industry type and an account type from their respective drop-down lists.

As the administrator, you can create and edit values in all of the drop-down boxes in the system to suit your organization’s needs. You can also create new drop-down lists for a module.

To create a drop-down list

1.	From the Data Type drop-down list in the Field Editor panel, select DropDown.

2.	Enter values for the following fields:

Field Name. Enter a name for the drop-down list.

Field Label. Enter a label name for the field to display in Sugar.

Help Text. Enter descriptive text for the field. This text displays when the user points the cursor at the field.

Drop Down List. To create a new list, do the following:

a.	Click Add.

The system displays the Dropdown Editor.

b.	In the Name field, enter a label for the drop-down list.

c.	In the Name field below, enter a name and its value.

The name displays in the User Interface and its value is stored in the Sugar database.

d.	To edit a name or its value, click the Edit icon; to delete them, click the Delete icon.

e.	To add additional parameters, click Add.

f.	Click Save to save the list.

The system displays the new drop-down list on the Properties tab.

g.	To undo your changes, click Undo.

h.	To redo your changes, click Redo

i.	On the Properties tab, click Save to save the drop-down list.

The new drop-down list displays under the module name in the center panel.

To use an existing drop-down list, do the following:

a.	Select an existing drop-down field listed under the module.

b.	In the Field Editor, click Edit.

The existing names and values display in the list.

c.	To change a value, click the corresponding Edit icon and enter the new value.

d.	To remove a name and its value, click the corresponding Delete icon.

e.	To add new values and labels, click Add.

f.	Click Save to save your changes.

g.	To undo your changes, click Undo.

h.	To redo your changes, click Redo.

i.	On the Properties tab, click Save to save your changes.

Default Value. Select a value from the drop-down list as the default for this drop-down list.

Mass Update. Checkmark this box to enable users to use the Mass Update functionality to update this field value.

Required Field. Checkmark this box to make this a required field.

Audit. Check this box to display field values when a user clicks the View Audit Log link.

Duplicate Merge. From the drop-down list, specify one of the following for the duplicate record merging functionality in modules such as contacts and accounts:

Disabled: This field cannot be used to merge records.

Enabled: This field can be used to merge records.

In filter: This field can be used as a filter when merging records.

Default selected filter: This field is the default filter when merging records.

Filter only: This field can be used only as a filter to merge records.

Editing Field Labels

Every field in a module has an label that displays in the Sugar User Interface. You can change the default field labels for all the language packs that you have installed.

To change field labels

1.	Select the module and click Labels.

A list of existing database fields and the labels to which they are mapped displays on the page.

2.	If you want to select a different language pack, select the appropriate one from the list of pre-installed language packs in the Language drop-down menu.

3.	Select the label that you want to edit and enter the new name.

4.	Click Save.

5.	To navigate back to a different module or to Studio, click the appropriate breadcrumb above the Save button.

Editing the Page Layout

You can edit the page layout for List View, Detail View, Edit View, Search form, and Quick Create form. You can remove existing fields and add new ones to a view. You can also rearrange existing fields to change the current layout.

When you select List View, the system displays separate columns of fields that are currently displayed in the view, fields that are available for display, and hidden fields. You can click and drag a field from one column to the other depending on what you want to display to users.

When you select Edit View or Detail View, the system displays the separate sections of the current layout, along with the fields under each section. You can click and drag a field to a different location within the layout.

In Edit View, you can also change the order in which the user can tab from field to field on a page. For example, when users create a new account, they can tab from the Account Name field to the Website field and so on. You can change the tabbing order to so that users tab from Account Name to Email.

The Quick Create form, which is the same as the Edit View, enables users to create a related record from the detail page of a record. For example, you can create a contact from the Contacts sub-panel on an account’s detail page. In Studio, you can shorten the Quick Create form by removing some fields. You can also add additional fields, if necessary.

The breadcrumbs to navigate back to Studio display above. The Toolbox provides space to store fields that you remove from a view. It also provides new rows to add to the view and a list of available fields that you can add.

To edit List View

1.	Select Layouts and then select List View.

The List View page displays on the screen. The Default column lists fields that are currently displayed in the User Interface. The Available column lists fields that are available to users through advanced search. Users can search for and add any of these fields that they want to view in the search results. The Hidden column lists fields that you want to hide from users when they perform an advanced search.

2.	To display a field in List View, select and drag the field from the Available or Hidden columns and drop it into the Default column.

3.	To remove a field from List View, select and drag the field from the Default column and drop it in the Available column.

4.	To hide a field from users, drag it from the Default or Available column and drop it in the Hidden column.

5.	Click Save & Publish to display the updated List View in the User Interface.

To edit Detail View, Edit View, and Quick Create forms

1.	Select Layouts.

2.	Select Detail View, Edit View, or Quick Create as appropriate.

3.	The Edit View page is shown below.To remove an existing field, drag it to the Recycling bin.

The field is removed from the view but is not deleted from the system.

4.	To replace an existing row in the view with another one, drag the new field from Available Fields and drop it on the field that you want to replace.

5.	To add placeholders for additional fields, drag the empty row under New Row and drop it into the view. You can then drag a field from the Available Fields into the empty row.

6.	To create a new panel, drag the empty row under New Panel and drop in into the view.

You can then create a label for the panel and add field.

7.	To edit a field name, select the Edit icon first. Then click within the field, select the current name and replace it with the new name.

8.	To move a field to a different location, point your cursor at the field name, hold down the mouse button, and drag it to the desired location on the page.

9.	To add a custom field, click the Add Custom Field button and follow the process described in “To add custom fields” on page 73.

10.	To edit the tabbing order, in Edit View, click Edit Tabbing Order.

The tabbing order for each field is represented by numbers such as 1, 2, and 3. You can change one or more numbers to change the order in which users tab to those fields.

11.	Click Save to save your changes.

12.	Click Save & Publish to display the updated view in the Sugar User Interface.

To edit the Search form

1.	In Layouts, click Search.

2.	To edit the Basic Search form, click Basic Form; to edit the Advanced Search form, click Advanced Form.

The fields in the current Search form are listed in the Default column and the available fields are listed in the Hidden column.

3.	To remove an existing field from the search form, drag it from the Default list to the Hidden list.

4.	To add a field to the search form, drag it from Hidden column to the Default column.

5.	To save your changes, click Save & Publish.

Editing Sub-Panels

Every module’s Detail View and Edit View display sub-panels listing related records from other modules. You can add or remove fields for these sub-panels depending on the information that you want to display to users.

To edit a sub-panel

1.	Select the module and then click Subpanels.

The sub-panels for the selected module displays on the page.

2.	Select the sub-panel that you want to edit.

The page displays the list of default fields and a list of fields that are available for display.

3.	To add a field to the sub-panel, select it from the Hidden column and drag it to the Default column.

4.	To remove a field from the sub-panel, select it from the Default column and drag it to the Hidden column.

5.	To save and display your changes in the module, click Save & Publish.

Publishing Customized Modules

To publish a module after you customize it in Studio, you will need to export it as a zip file to your local machine and then upload it from your machine into Sugar using the Module Loader.

To publish a customized module

1.	On the Studio home page, click Export Customizations.

The Export Customizations page displays the customized modules and indicates the area of customization. The screen shown below indicates that Opportunities module contains one or more customized fields.

2.	Enter the following information:

Package Name. Enter a name for the export package. The package will contain the customized modules that you select.

Author. Enter your name as the author.

Description. Enter a brief description of the package.

3.	Select the modules that you want to export.

4.	Click Export.

The system creates a zip file and displays a dialog box that allows you to open the file or save it to a disk.

5.	Select Save to Disk and click OK.

On MS Windows, the system saves it in the Downloads directory.

You can upload the file into Sugar using the Module Loader. For more information, see “Module Loader” on page 45.

6.	To remove an existing field, drag it to the Recycling bin.

The field is removed from the view but is not deleted from the system.

7.	To replace an existing row in the view with another one, drag the new field from the left panel and drop it on the field that you want to replace.

8.	To add placeholders for additional fields, drag New Row and drop it into the view. You can then drag a field from the Available Fields into the empty row.

9.	Click Save to save your changes.

10.	Click Save and Deploy to make it available to all users in your organization.

Configuring Module Tabs

By default, all the module tabs are displayed when a user logs into Sugar. However, you can choose which module tabs to display when users log into Sugar. You can also choose the order in which these tabs are arranged in the Sugar User Interface.

By default, users can also configure module tabs on their My Account page. However, the user cannot add back module tabs that the administrator removed from the system. Administrators can deselect the Allow users to configure tabs check box if they do not want users to make any changes.

Note:

You cannot hide the Home tab.

To configure module tabs

1.	In Studio, select Configure Tabs.

The Configure Tabs page displays all the tabs in the Display Tabs list.

2.	To hide a tab, select it in the Display Tabs column and, using the Right arrow (>) button, move it to the Hide Tabs column.

3.	To rearrange the order in which the tabs are displayed, use the Up and Down arrows.

4.	To disallow users from configuring the tabs, deselect the Allow users to configure tabs option.

5.	Click Save to save the configuration; click Cancel to exit the page without saving your changes.

Renaming Tabs

You can rename the module tabs that display in Sugar.

To rename tabs

1.	In Studio, select Rename Tabs.

The tab labels and the corresponding database table keys display on the page. From the three drop-down lists displayed above the tab labels, you can select the module, a corresponding drop-down list, and the language to display the tab. By default, all the available drop-down lists in the system are displayed.

To view a drop-down list that is specific to a module, select the module from the drop-down list above the Database Key column and then select one of the related lists from the adjacent drop-down list.

2.	Click the label that you want to edit and replace it with the new value.

3.	Click Save to save your changes; click Undo to revert to the previous value; click Redo to go back to your change.

Configuring Group Tabs

By default, the system displays individual module tabs when users log into Sugar. However, you can use the Configure Group Tab option to organize