Programmatically Customize Tasks and Folders for the Model Advisor

Customization File Overview

The sl_customization.m file contains a set of functions for registering and defining custom checks, tasks, and groups. To set up the sl_customization.m file, follow the guidelines in this table.

Note

If the By Product folder is not displayed in the Model Advisor window, select Show By Product Folder from the Settings > Preferences dialog box.

Function	Description	Required or Optional
`sl_customization()`	Registers custom checks and tasks, folders with the Simulink^® customization manager at startup. See Define Custom Model Advisor Checks.	Required for customizations to the Model Advisor.
One or more check definitions	Defines custom checks. See Define Custom Model Advisor Checks.	Required for custom checks and to add custom checks to the By Product folder.
One or more task definitions	Defines custom tasks. See Define Custom Tasks.	Required to add custom checks to the Model Advisor, except when adding the checks to the By Product folder. Write one task for each check that you add to the Model Advisor.
One or more groups	Defines custom groups. See Define Custom Tasks.	Required to add custom tasks to new folders in the Model Advisor, except when adding a new subfolder to the By Product folder. Write one group definition for each new folder.

Register Tasks and Folders

Create sl_customization Function

To add tasks and folders to the Model Advisor, create the sl_customization.m file on your MATLAB^® path. Then create the sl_customization() function in the sl_customization.m file on your MATLAB path.

Tip

You can have more than one sl_customization.m file on your MATLAB path.
Do not place an sl_customization.m file that customizes the Model Advisor in your root MATLAB folder or its subfolders, except for the matlabroot/work folder. Otherwise, the Model Advisor ignores the customizations that the file specifies.

The sl_customization function accepts one argument, a customization manager object, as in this example:

function sl_customization(cm)

The customization manager object includes methods for registering custom checks, tasks, and folders. Use these methods to register customizations specific to your application, as described in the sections that follow.

Register Tasks and Folders

The customization manager provides the following methods for registering custom tasks and folders:

addModelAdvisorTaskFcn (@factorygroupDefinitionFcn)
Registers the tasks that you define in factorygroupDefinitionFcn to the By Task folder of the Model Advisor.
The factorygroupDefinitionFcn argument is a handle to the function that defines the checks to add to the Model Advisor as instances of the ModelAdvisor.FactoryGroup class.
addModelAdvisorTaskAdvisorFcn (@taskDefinitionFcn)
Registers the tasks and folders that you define in taskDefinitionFcn to the folder in the Model Advisor that you specify using the ModelAdvisor.Root.publish method or the ModelAdvisor.Group class.
The taskDefinitionFcn argument is a handle to the function that defines custom tasks and folders. Simulink adds the checks and folders to the Model Advisor as instances of the ModelAdvisor.Task or ModelAdvisor.Group classes.

The following example shows how to register custom tasks and folders:

function sl_customization(cm)

% register custom factory group
cm.addModelAdvisorTaskFcn(@defineModelAdvisorTasks);

% register custom tasks.
cm.addModelAdvisorTaskAdvisorFcn(@defineTaskAdvisor);

Note

If you add custom checks within the sl_customization.m file, include methods for registering the checks in the sl_customization function.

Define Custom Tasks

Add Check to Custom or Multiple Folders Using Tasks

You can use custom tasks for adding checks to the Model Advisor, either in multiple folders or in a single, custom folder. You define custom tasks in one or more functions that specify the properties of each instance of the ModelAdvisor.Task class. Define one instance of this class for each custom task that you want to add to the Model Advisor. Then register the custom task. The following sections describe how to define custom tasks.

To add a check to multiple folders or a single, custom folder:

Create a check using the ModelAdvisor.Check class.
Register a task wrapper for the check.
If you want to add the check to folders that are not already present, register and create the folders using the ModelAdvisor.Group class.
Add a check to the task using the ModelAdvisor.Task.setCheck method.
Add the task to each folder using the ModelAdvisor.Group.addTask method and the task ID.

Create Custom Tasks Using MathWorks Checks

You can add MathWorks^® checks to your custom folders by defining the checks as custom tasks. When you add the checks as custom tasks, you identify checks by the check ID.

To find MathWorks check IDs:

In the hierarcy, navigate to the folder that contains the MathWorks check.
In the left pane of the Model Advisor, select the check.
Right-click the check name and select Send Check ID to Workspace. The ID is displayed in the Command Window and sent to the base workspace.
Select and copy the Check ID of the check that you want to add from the Command Window as a task.

Display and Enable Tasks

The Visible, Enable, and Value properties interact the same way for tasks as they do for checks.

Define Where Tasks Appear

You can specify where the Model Advisor places tasks within the Model Advisor using the following guidelines:

To place a task in a new folder in the Model Advisor Task Manager, use the ModelAdvisor.Group class.
To place a task in a new folder in the By Task folder, use the ModelAdvisor.FactoryGroup class.

Task Definition Function

The following example shows a task definition function. This function defines three tasks.

% Defines Model Advisor tasks and a custom folder
% Add checks to a custom folder using task definitions
function defineTaskAdvisor
mdladvRoot = ModelAdvisor.Root;

% Define task that uses Sample Check 0: Check whose Results are Viewed as Detailed Result Collections
MAT8 = ModelAdvisor.Task('com.mathworks.sample.TaskSample8');
MAT8.DisplayName='Example task using new check style (recommended style)';
MAT8.setCheck('com.mathworks.sample.Check0');
mdladvRoot.register(MAT8);

% Define task that uses Sample Check 1: Informational check
MAT1 = ModelAdvisor.Task('mathworks.example.task.configManagement');
MAT1.DisplayName = 'Informational check for model configuration management';
MAT1.Description = 'Display model configuration and checksum information.';
setCheck(MAT1, 'mathworks.example.configManagement');
mdladvRoot.register(MAT1);

% Define task that uses Sample Check 2: Basic Check with Pass/Fail Status
MAT2 = ModelAdvisor.Task('mathworks.example.task.unconnectedObjects');
MAT2.DisplayName = 'Check for unconnected objects';
setCheck(MAT2, 'mathworks.example.unconnectedObjects');
MAT2.Description = ['Identify unconnected lines, input ports, and output ' ...
                                      'ports in the model or subsystem.'];
mdladvRoot.register(MAT2);

% Define task that uses Sample Check 3: Check with Subresults and Actions
MAT3 = ModelAdvisor.Task('mathworks.example.task.optimizationSettings');
MAT3.DisplayName = 'Check safety-related optimization settings';
MAT3.Description = ['Check model configuration for optimization ' ...
                    'settings that can impact safety.'];
MAT3.setCheck('mathworks.example.optimizationSettings');
mdladvRoot.register(MAT3);

% Custom folder definition
MAG = ModelAdvisor.Group('mathworks.example.ExampleGroup');
MAG.DisplayName = 'My Group';
% Add tasks to My Group folder
MAG.addTask(MAT8);
addTask(MAG, MAT1);
addTask(MAG, MAT2);
addTask(MAG, MAT3);
% Add My Group folder to the Model Advisor under 'Model Advisor' (root)
mdladvRoot.publish(MAG);

Define Custom Folders

About Custom Folders

Use folders to group checks in the Model Advisor by functionality or usage. You define custom folders in:

A factory group definition function that specifies the properties of each instance of the ModelAdvisor.FactoryGroup class.
A task definition function that specifies the properties of each instance of the ModelAdvisor.Group class.

Define one instance of the group classes for each folder that you want to add to the Model Advisor.

Add Custom Folders

To add a custom folder:

Create the folder using the ModelAdvisor.Group or ModelAdvisor.FactoryGroup classes.
Register the folder.

Define Where Custom Folders Appear

You can specify the location of custom folders within the Model Advisor using the following guidelines:

To define a new folder in the Model Advisor Task Manager, use the ModelAdvisor.Group class.
To define a new folder in the By Task folder, use the ModelAdvisor.FactoryGroup class.

Note

To define a new folder in the By Product folder, use the ModelAdvisor.Root.publish method within a custom check. If the By Product folder is not displayed in the Model Advisor window, select Show By Product Folder from the Settings > Preferences dialog box.

Group Definition

The following examples shows a group definition. The definition places the tasks inside a folder called My Group under the Model Advisor root. The task definition function includes this group definition.

% Custom folder definition
MAG = ModelAdvisor.Group('mathworks.example.ExampleGroup');
MAG.DisplayName='My Group';
% Add tasks to My Group folder
MAG.addTask(MAT8);
MAG.addTask(MAT1);
MAG.addTask(MAT2);
MAG.addTask(MAT3);
% Add My Group folder to the Model Advisor under 'Model Advisor' (root)
mdladvRoot.publish(MAG);

The following example shows a factory group definition function. The definition places the checks into a folder called Demo Factory Group inside of the By Task folder.

function defineModelAdvisorTasks
mdladvRoot = ModelAdvisor.Root;

% --- sample factory group
rec = ModelAdvisor.FactoryGroup('com.mathworks.sample.factorygroup');
rec.DisplayName='Demo Factory Group';
rec.Description='Demo Factory Group';
rec.addCheck('com.mathworks.sample.Check0');
rec.addCheck('mathworks.example.configManagement');
rec.addCheck('mathworks.example.unconnectedObjects');
rec.addCheck('mathworks.example.optimizationSettings');
mdladvRoot.publish(rec); % publish inside By Task