padv.ProcessModel

Define tasks and process for project

Description

This object requires CI/CD Automation for Simulink Check. A padv.ProcessModel object represents the process model that defines the tasks and process for a project. A task performs an action and is a single step in your process. A process is a series of tasks that run in a specific order. The process model defines the tasks that you can perform on the project, and the order and relationships between tasks in the process. You can use tasks and queries to dynamically perform actions and find artifacts in the project. Use the addTask object function to add tasks to the process model. You can use the function runprocess to run the tasks defined in the process model. For more information, see Overview of Process Model.

Creation

Syntax

pm = padv.ProcessModel()

Description

pm = padv.ProcessModel() creates an empty process model object, pm.

Properties

TaskNames — Tasks added to process model object

string array

Tasks added to process model object, returned as string array.

Use the object function addTask to add a task instance to a process model.

Example: ["padv.builtin.task.GenerateSimulinkWebView" "padv.builtin.task.RunModelStandards"]

Data Types: string

QueryNames — Queries added to process model object

string array

Queries added to process model object, returned as string array.

Use the object function addQuery to add a query instance to a process model.

Example: ["padv.builtin.query.FindModels" "padv.builtin.query.FindProjectFile"]

Data Types: string

ProcessNames — Processes in process model

string

Processes in the process model, specified as a string.

For more information about processes, see Manage Multiple Build and Verification Workflows Using Processes.

Example: ["CIPipeline" "ProcessA"]

Data Types: string

DefaultQueryName — Default query for tasks added to process model object

"padv.builtin.query.FindProjectFile" (default) | name of padv.Query query

Default query for tasks added to process model, specified as the name of a padv.Query query.

Example: "padv.builtin.query.FindModels"

Data Types: string

DefaultOutputDirectory — Default output directory for results

fullfile("$PROJECTROOT$","PA_Results") (default) | string array

Default output directory, specified as a string array. Set the default output directory to a path inside your project. The path can be either a relative or absolute path. Consider using the path relative to the project root to promote consistency across local environments and CI systems, and allow for more portable builds.

The default property value uses the token $PROJECTROOT$ as a placeholder for dynamic path resolution during run-time. The build system considers paths that use tokens as absolute paths. For more information, see Dynamically Resolve Paths with Tokens.

By default, Process Advisor and the build system output results in a folder PA_Results in the project root.

Example: fullfile("$PROJECTROOT$","Process_Results")

Data Types: string

JUnitReportName — Name of generated JUnit-style XML report

"$TASKNAME$_$ITERATIONARTIFACT$_JUnit.xml" (default) | string array

Name of generated JUnit-style XML report , specified as a string array.

By default, the generated JUnit report for a task has the format taskName_iterationArtifact_JUnit.xml.

The default property value uses the tokens $TASKNAME$ and $ITERATIONARTIFACT$ as placeholders for dynamic path resolution during run-time. For more information, see Dynamically Resolve Paths with Tokens.

Example: "$TASKNAME$_$ITERATIONARTIFACT$_JUnitReport.xml"

Data Types: string

JUnitReportPath — Location for JUnit-style XML report

fullfile("$DEFAULTOUTPUTDIR$","junit") (default) | string array

Location for JUnit-style XML report, specified as a string array.

The default property value uses the token $DEFAULTOUTPUTDIR$ as a placeholder for dynamic path resolution during run-time. For more information, see Dynamically Resolve Paths with Tokens.

Example: fullfile("$DEFAULTOUTPUTDIR$","junit","reports")

Data Types: string

DefaultProcessId — Name of default process for project

string

Name of default process for project, specified as a string.

The first time that you open Process Advisor, the app opens to the default process. Otherwise, Process Advisor re-opens your last opened process. By default, several APIs use the default process unless you specify a different process in the process model. For more information, see Manage Multiple Build and Verification Workflows Using Processes.

Example: "ProcessA"

Data Types: string

EnablePerformanceChecks — Turn on performance improvement checks

1 (true) (default) | 0 (false)

Turn on performance improvement checks for the process model, specified as a numeric or logical 1 (true) or 0 (false).

When EnablePerformanceChecks is true, the build system identifies and warns you about inefficient process model code. For example, the build system can generate a warning if multiple tasks in the process model use the same query but do not share the same query object.

Example: false

Data Types: logical

DefaultDryRunResults — Default task results when task dry-runs

padv.TaskResult() (default) | padv.TaskResult object

Default task results when task dry-runs, specified as a padv.TaskResult object.

If you dry-run a task that does not have a dry-run behavior specified, the task returns the default dry-run results specified by DefaultDryRunResults. To specify a dry-run behavior for a task, you can use the dryRun method for class-based tasks or the DryRunAction function for function-based tasks.

By default, DefaultDryRunResults returns a padv.TaskResult object. You can create a different set of default dry-run results by creating and using a padv.TaskResult object with different property values. For example, to have the default dry-run results be failing task results with specific result values in the Details column, in your process model you can create a padv.TaskResult object and update the value of the DefaultDryRunResults property:

res = padv.TaskResult;
res.Status = padv.TaskStatus.Fail;
res.Values = struct(...
    "Pass",1,...
    "Warn",2,...
    "Fail",3);

pm.DefaultDryRunResults = res;

Example: padv.TaskResult

RootFileName — Name of process model file

string

Name of process model file, returned as a string.

RootFileName uses processmodel.m as the name of the process model file, unless a processmodel.p file exists. If you have both a P-code file and a .m file, the P-code file takes precedence over the corresponding .m file for execution, even after modifications to the .m file.

The default name of the process model file is specified by DefaultRootFileName.

Data Types: string

DefaultRootFileName — Default name of process model file

"processmodel.m" (default) | string

Default name of process model file, specified as a string.

Data Types: string

Object Functions

reset	Removes tasks and queries from process model pm = padv.ProcessModel(); reset(pm);
reload	Load process model by executing process model file for project pm = padv.ProcessModel(); reload(pm);
addProcess	Add process to process model processA = pm.addProcess("processA");
addSubprocess	Add subprocess instance to process model addSubprocess(pm,"MySubprocess");
addTask	Add task instance to process model addTask(pm,"MyCustomTask",... Action=@SayHello,... IterationQuery=padv.builtin.query.FindModels); When you use addTask on a process model object, the function adds the task to the default process. To add a task to a specific process inside the process model, use addTask on the process object. For information, see addTask.
addQuery	Add query instance to process model addQuery(pm,"MyCustomQuery") For information, see addQuery.
findProcess	Find process in process model pm = getprocess; ci = pm.findProcess("CIPipeline")
findQuery	Find query instance by name pm = padv.ProcessModel(); QUERY = findQuery(pm,... "padv.builtin.query.FindModels")
findTask	Find task instance by name pm = padv.ProcessModel(); TASK = findTask(pm,... "padv.builtin.task.RunModelStandards");
exists	Check if process model exists for project [FOUND, PATH] = padv.ProcessModel.exists()

Examples

Add Tasks to Process Model Object

You can add tasks directly to your process model by using the object function addTask for the padv.ProcessModel object in your process model. When you add a task using this approach, the padv.ProcessModel object automatically creates a process named CIPipeline and adds the task to that process. For information on how to create your own processes, see Manage Multiple Build and Verification Workflows Using Processes.

Open the Process Advisor example project.

processAdvisorExampleStart

The model AHRS_Voter opens with the Process Advisor pane to the left of the Simulink^® canvas.

In the Process Advisor pane, click the Edit process model button to open the processmodel.m file for the project.

Replace the contents of the processmodel.m file with this code:

function processmodel(pm)
    arguments
        pm padv.ProcessModel
    end

    addTask(pm,"taskA");
    addTask(pm,"taskB");
    
end

The function addTask adds the task objects to the padv.ProcessModel object.

Use the function getprocess to get the process model object for the project.

pm = getprocess;

Get the task object for "taskA" defined in the current process model.

taskAObj = findTask(pm, "taskA");

taskAObj is a padv.Task object that you can use to view the properties of the task "taskA".

Add Processes to Process Model

You can add processes to your process model by using the object function addProcess for the padv.ProcessModel object inside your process model. Then you can add tasks to those processes by using the addTask function.

Open the Process Advisor example project.

processAdvisorExampleStart

The model AHRS_Voter opens with the Process Advisor pane to the left of the Simulink canvas.

In the Process Advisor pane, click the Edit process model button to open the processmodel.m file for the project.

Replace the contents of the processmodel.m file with this code:

function processmodel(pm)
    % Defines process model for project by setting up proceses and tasks

    arguments
        pm padv.ProcessModel
    end

    % --- Processes ---
    processA = pm.addProcess("ProcessA");
    processB = pm.addProcess("ProcessB");

    % --- Tasks ---
    taskA1 = processA.addTask("TaskA1");
    taskB1 = processB.addTask("TaskB1");
    taskA2 = processA.addTask("TaskA2");
    taskB2 = processB.addTask("TaskB2");

end

The function addProcess adds processes to the padv.ProcessModel object. The function addTask adds example tasks to specific processes.

For information on how to create your own processes, see Manage Multiple Build and Verification Workflows Using Processes.

Change Default Dry Run Results

Suppose that you want the default dry run results to show failing task results with specific result values in the Details column.

By default, if a task does not have a dry run functionality defined, the task returns the default dry run results specified by the padv.ProcessModel property DefaultDryRunResults. You can create a different set of default dry run results by creating and using a padv.TaskResult object with different property values.

Inside your process model, you can create a padv.TaskResult object and update the value of the DefaultDryRunResults property of the process model. In this example, the process model also includes a custom task, MyCustomTask, that does not specify any specialized dry run functionality.

function processmodel(pm)
    % Defines the project's processmodel
    arguments
        pm padv.ProcessModel
    end

    res = padv.TaskResult;
    res.Status = padv.TaskStatus.Fail;
    res.Values = struct(...
    "Pass",1,...
    "Warn",2,...
    "Fail",3);
    pm.DefaultDryRunResults = res;

    pm.addTask("MyCustomTask");

end

In Process Advisor, dry run the task MyCustomTask. Since there is no specialized dry run behavior for the task, the task uses the default dry run results specified by DefaultDryRunResults.

Tips

By default, if you make a change to the process model file, Process Advisor marks task results as outdated because the tasks in the updated process model might not match the tasks that generated the task results from the previous version of the process model. If you do not want changes to the process model to make task results outdated, you can open the Settings in Process Advisor and clear Add process model as dependency in the user settings. For more information, see Specify Settings for Process Advisor and Build System and padv.UserSettings.

For more information on artifact tracking, see Exclude Files from Change Tracking in Process Advisor.