Automate and Run Tasks with Process Advisor

This example uses:

CI/CD Automation for Simulink Check CI/CD Automation for Simulink Check

You can automate common tasks in your model-based development and verification workflow by using the CI/CD Automation for Simulink Check support package. The support package contains a default process model with built-in tasks for performing common activities such as checking modeling standards with Model Advisor, running tests with Simulink^® Test™, and generating code with Embedded Coder^®. You can view, edit, and run these tasks from the Process Advisor app or run tasks by using the Process Advisor function runprocess.

This example shows how to:

View and modify the default process model to fit your development process.
Run tasks and review results by using Process Advisor.
Identify the impact of a change and incrementally rerun impacted tasks.
Export a build report that summarizes the task results.

View and Modify Default Process

You can define development and verification processes for a project by using a script called a process model. Process Advisor automatically reads the process model and uses the file to determine which tasks to run, how the tasks perform their actions, and the order in which tasks run. If your project does not already have a process model, Process Advisor automatically opens a default process model file that uses built-in tasks to perform common model-based design activities. You can edit the process model to add, remove, or reconfigure the tasks in the process. For information on how Process Advisor generates pipelines of tasks based on the process model, tasks, and queries, see Overview of Process Model.

Open a project that contains your files. If you do not have a project, see Create Projects or open an example project by entering:
```
openExample('simulink/UsingAProjectExample')
```
Open Process Advisor. On the Project tab, in the Tools section, click Process Advisor or enter processAdvisorWindow at the command line.
Process Advisor opens in a standalone window. If Process Advisor needs to perform an initial analysis on your project, the app shows the Enable Artifact Tracing dialog box. Click Enable and Continue.
The tasks defined in the process model appear in the Tasks column in Process Advisor. The default process model contains built-in tasks for several common tasks like checking modeling standards with Model Advisor, running tests with Simulink Test, and generating code with Embedded Coder.
To view information about a task, point to the task in the Tasks column and click the information icon .

You can add or remove tasks from the process by editing the process model. Inspect and edit the process model by clicking the Edit button in the toolstrip. Process Advisor opens the process model file, processmodel.m, in the MATLAB^® Editor.

You can add or remove built-in tasks from the process by setting the variable associated with a built-in task to true or false. For example, to add the built-in task for design error detection to your process, you can update the code to set includeDesignErrorDetectionTask to true.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Include/Exclude Tasks in processmodel
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

includeModelMaintainabilityMetricTask = true;
includeModelTestingMetricTask = true;
includeModelStandardsTask = true;
includeDesignErrorDetectionTask = true;
includeFindClones = true;
includeModelComparisonTask = false;
includeSDDTask = true;
includeSimulinkWebViewTask = true;
includeTestsPerTestCaseTask = true;
includeMergeTestResultsTask = true;
includeGenerateCodeTask = true;
includeAnalyzeModelCode = true && exist('polyspaceroot','file');
includeProveCodeQuality = true && (~isempty(ver('pscodeprover')) ...
    || ~isempty(ver('pscodeproverserver')));
includeCodeInspection = false;
includeGenerateRequirementsReport = false;

Each variable is associated with a task in the default process model.

Variable in Default Process Model	Task Title	Built-In Task
`includeModelMaintainabilityMetricTask`	Collect Model Maintainability Metrics	`padv.builtin.task.CollectMetrics`
`includeModelTestingMetricTask`	Collect Model Testing Metrics	`padv.builtin.task.CollectMetrics`
`includeModelStandardsTask`	Check Modeling Standards	`padv.builtin.task.RunModelStandards`
`includeDesignErrorDetectionTask`	Detect Design Errors	`padv.builtin.task.DetectDesignErrors`
`includeFindClones`	Find Clones	`padv.builtin.task.FindClones`
`includeModelComparisonTask`	Generate Model Comparison	`padv.builtin.task.GenerateModelComparison`
`includeSDDTask`	Generate SDD Report	`padv.builtin.task.GenerateSDDReport`
`includeSimulinkWebViewTask`	Generate Simulink Web View	`padv.builtin.task.GenerateSimulinkWebView`
`includeTestsPerTestCaseTask`	Run Tests	`padv.builtin.task.RunTestsPerTestCase`
`includeMergeTestResultsTask`	Merge Test Results	`padv.builtin.task.MergeTestResults`
`includeGenerateCodeTask`	Generate Code	`padv.builtin.task.GenerateCode`
`includeAnalyzeModelCode`	Check Coding Standards	`padv.builtin.task.AnalyzeModelCode`
`includeProveCodeQuality`	Prove Code Quality	`padv.builtin.task.AnalyzeModelCode`
`includeCodeInspection`	Inspect Code	`padv.builtin.task.RunCodeInspection`
`includeGenerateRequirementsReport`	Generate requirements report	`padv.builtin.task.GenerateRequirementsReport`

For more information on how to get started with the default process model, see Modify Default Process Model to Fit Your Process.

After you finish making changes to the process model, you can view the updated list of tasks in Process Advisor by returning to the Process Advisor window and, in the warning banner, clicking Refresh Tasks.
Process Advisor refreshes to reflect the updated process model. The Tasks column now includes a task for Detect Design Errors.
You can view the source code for a built-in task by pointing to the task and clicking ... > Edit Task.

Each built-in task has a default behavior, but you can reconfigure the task to perform differently by specifying different property values for the task object in the process model. You can also create your own custom tasks with custom behaviors. For more information, see Customize Your Process Model.

Run Tasks and Review Results

You can run tasks either from the Process Advisor app or by using the Process Advisor function runprocess.

To run a task on a specific artifact, you can point to that task iteration and click the run button. In the Tasks column, under Collect Model Maintainability Metrics, point to the model name AnalogControl and click the run button .
The Collect Model Maintainability Metrics task runs on the current model. Process Advisor logs task activity in the MATLAB Command Window. When the task runs successfully, the status in the Tasks column shows a green circle with a check mark . When you point to the status icon, you can view details about the status, including the task status and how long the task took to run.
If you point to the file icon in the I/O column, the pop-up shows hyperlinks to the outputs from the task, and inputs and dependencies for the task. In the Details column, you can see that the task successfully output a model maintainability report.
You can click the hyperlink to open and view the report.
If you want the task to generate a different report format, such as HTML, or to collect only specific metrics, you can reconfigure the task to change the task behavior. For more information, see Customize Your Process Model.
To view the metric results directly in the Model Maintainability Dashboard, you can point to the task iteration, click ... > Open Dashboard.
The task automatically collects metric results that describe the size, complexity, and architecture of the model and those metric results appear in the dashboard.
To run a task on each of the artifacts, point to the task title and click the run button . Collect model maintainability metrics for each model in the project by clicking the run button for the task Collect Model Maintainability Metrics.
Process Advisor highlights and runs the necessary task and the task iterations. If the Collect Model Maintainability Metrics task depended on results from other tasks, Process Advisor would automatically run those tasks first.
Process Advisor aggregates the results of each task. In the Details column, Process Advisor shows the number of passing, warning, or failing results:
- A green check mark indicates a passing result.
- An orange triangle indicates a warning result.
- A red "X" indicates a failing result.
In this example, the Collect Model Maintainability Metrics task successfully collected the model maintainability metrics for 7 models, so the Details column shows a value of 7 next to the green check mark for the task.

The task options menu and Process Advisor toolstrip have additional options for running each of the tasks in your process, cleaning tasks to clear results and delete outputs, and other functionalities. For more information, see Process Advisor.

Identify Impact of Changes

If you make a change to an artifact in your project, Process Advisor can detect the change and automatically determine the impact of the change on your existing task results. For example, if you make a change to an artifact or its dependencies, certain task results are no longer up to date. Process Advisor can identify the impacted task results automatically and invalidate the task completion by marking the task results as outdated.

Open the AnalogControl model in the project by clicking the model name in the Tasks column. The artifact names shown in the Tasks column are hyperlinks to the artifacts.
Note that a model-specific view of Process Advisor is available in a pane to the left of the Simulink canvas. You can use either view to interact with your tasks, but this example uses the standalone window instead. For more information, see Process Advisor.
In Simulink, make a change to the AnalogControl model and save the model. For this example, click and drag a block to a different part of the Simulink canvas, save, and close the model.
Process Advisor automatically detects the change to the project file and prompts you to refresh the tasks by using the Refresh Tasks button in the warning banner.
View the updated task statuses in the standalone Process Advisor window by clicking Refresh Tasks.
Process Advisor marks the task statuses for both the AnalogControl model and the slproject_f14 model as outdated.
For the slproject_f14 task iteration, point to the file icon in the I/O column.
Process Advisor shows that the app marked the task results for slproject_f14 model as outdated because the slproject_f14 references the AnalogControl model, which became invalidated.

Note

There are limitations to the types of changes that the Process Advisor can detect. For more information, see Limitations on Incremental Build. Note that the warning banner can appear while you are running tasks or after you have finished running tasks, depending on when file system events reach MATLAB.

Rerun Impacted Tasks with Incremental Build

By default, Process Advisor can rerun tasks with outdated results and automatically skip tasks that are up to date. These incremental builds can help you reduce run times by reducing the number of tasks that you need to rerun after making changes to your project artifacts to only rerun tasks that were impacted by the change. The task status icons in the Tasks column indicate whether the task results are up to date or outdated. Up to date task results have task status icons that are green for tasks that pass and red for tasks that fail or generate errors. Outdated task results have task status icons that are gray.

Get updated task results by rerunning the Collect Model Maintainability Metrics task. Point to the task and click the run button.
Process Advisor automatically reruns the Collect Model Maintainability Metrics task for the models with outdated results, AnalogControl and slproject_f14, and skips the other models because those results are still up to date.

In the MATLAB Command Window, you can find a summary of which tasks were run or skipped at the end of the log.

#####################
## Ending Process Advisor build at 31-May-2024 17:45:05
#### Duration:                  00:00:08
#### Build Status:              Pass
#### Number of tasks:           7
#### Number of tasks executed:  2
#### Number of tasks skipped:   5
#### Number of tasks in queue:  0
#### Number of tasks failed:    0
#### Tasks that were skipped:(Status::Task::IterationArtifact)
####      Pass::padv.builtin.task.CollectMetrics::models/DigitalControl.slx
####      Pass::padv.builtin.task.CollectMetrics::models/LinearActuator.slx
####      Pass::padv.builtin.task.CollectMetrics::models/NonLinearActuator.slx
####      Pass::padv.builtin.task.CollectMetrics::models/f14_airframe.slx
####      Pass::padv.builtin.task.CollectMetrics::models/vertical_channel.slx
#####################

If you want Process Advisor to always force tasks to rerun, you can turn off incremental builds by clicking Settings in the toolstrip and clearing the Incremental build check box. For more information about settings, see Specify Settings for Process Advisor and Build System.

Export Build Report

You can export a build report that summarizes the Process Advisor task statuses, task results, and other information about the task execution.

In the Process Advisor toolstrip, in the Export section, click Report. In the Export Report dialog box, you can specify options for the report an export a report for the current process by clicking Export.

Alternatively, you can programmatically generate a report by using padv.ProcessAdvisorReportGenerator to specify options for the report and generateReport to generate the report. For example:

rptObj = padv.ProcessAdvisorReportGenerator;
generateReport(rptObj)

For more information, see Generate Build Report.

Explore Other Options

You can use Process Advisor to automate and run tasks on your machine and deploy a consistent development and verification process across your team. If you use source control and continuous integration (CI) for your project, you can also use Process Advisor as part of your prequalification process to make sure your team runs specific tasks before submitting their changes to source control. Having a consistent process, defined by the process model, can help your team prevent build and test failures in CI.

Use this table to find more information based on your goals.

Goal	Related Information
Learn more about the Process Advisor app.	Process Advisor
Customize the pipeline of tasks by reconfiguring the built-in tasks, removing tasks, and adding custom tasks.	Customize Your Process Model
Integrate into a continuous integration (CI) system.	Integrate Process into CI
Debug failures seen in CI.	Locally Reproduce Issues Found in CI