addTask

Add task instance to process model

Syntax

taskObj = addTask(pm,taskNameOrInstance)

taskObj = addTask(___,Name=Value)

Description

taskObj = addTask(pm,taskNameOrInstance) adds the task specified by taskNameOrInstance to the process model. You can access the task using the task object taskObj. For more information, see Add Tasks to Process.

taskObj = addTask(___,Name=Value) specifies the properties of the task using one or more Name=Value arguments.

Examples

Add Tasks to Process Model

You can use the addTask function to create function-based tasks directly in the process model.

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,"MyCustomTask",Action=@SayHello,...
        IterationQuery=padv.builtin.query.FindModels);

end

function results = SayHello(~)
    disp("Hello, World!");
    results = padv.TaskResult;
    results.Values.Pass = 1;
end

This code adds a task, MyCustomTask to the process model while specifying that the task runs the function SayHello one time for each model found in the project. The function SayHello also specifies the results returned by the task.

Add User Tasks

Add a checklist of user actions to your process by adding user tasks to your process model. Users can select the checkbox next to a user task to quickly mark the task as complete. You can specify other task statuses and task outputs by using the Edit Task State dialog box for the task.

Open a project. For this example, you can open the Process Advisor example project.

processAdvisorExampleStart

Create a task for users to review a spreadsheet by editing the process model to use the following process model instead. The process model specifies that the task is a user task by setting the TaskType to padv.TaskType.User.

function processmodel(pm)
    % Defines the project's processmodel

    arguments
        pm padv.ProcessModel
    end

    tReview = pm.addTask("ReviewSpreadsheetTask", ...
      TaskType=padv.TaskType.User, ...
      Title="Review Spreadsheet");

end

In Process Advisor, click Refresh Tasks. In the Tasks list, the task appears next to a checkbox. You can mark the task as complete by selecting the checkbox. To clean the task and clear the task status, you can clear the checkbox.

You can add files as task outputs and specify other task statuses by using the Edit Task State dialog box. To open the dialog box, point to the task and click the edit user task button .

In the Edit Task State dialog box, you can manage task outputs and set the task status.

In the Output files section, you can:

• Add a file as a task output by clicking the plus button . The build system tracks changes to these files. If you modify a file, the build system marks the task results as outdated.

  As a best practice, update the process model to specify the directory in which you expect the user to save the task output. For example, specify a folder named spreadsheets within the project root.

  function processmodel(pm)
      % Defines the project's processmodel
  
      arguments
          pm padv.ProcessModel
      end
  
      tReview = pm.addTask("ReviewSpreadsheetTask", ...
          TaskType=padv.TaskType.User, ...
          Title="Review Spreadsheet", ...
          OutputDirectory = fullfile("$PROJECTROOT$","spreadsheets"));
  
  end

• Remove a task output by selecting the file in the Output files section and clicking the minus button . Removing the files as task outputs does not delete the files.

You can select a task status of either:

• Complete — This marks the task as complete and is equivalent to a Passed task status.

• Draft — This indicates that work is in progress and is equivalent to a Failed task status. If you add task outputs, those outputs appear in the I/O results for the task. If the task had existing task results, the draft overwrites those results.

• Error — This indicates that your work on a task is blocked and is equivalent to an Errored task status. You can optionally provide an error message that indicates why you cannot complete the task by expanding the Advanced options and typing an error message.

Then, click Save to set the task status and save the task outputs. If you want to clear the task status and remove the task outputs, you can click Clean Task. Removing the files as task outputs does not delete the files.

To manage the task order in the Tasks column, you can use task relationship functions like runsAfter and dependsOn. For example, in the following process model:

• TaskB appears after TaskA because of the runsAfter function.

• TaskC depends on TaskB, meaning that you cannot complete TaskC until TaskB is complete. You can only set the task status as Draft or Error.

function processmodel(pm)
    % Defines the project's processmodel

    arguments
        pm padv.ProcessModel
    end

    taskA = pm.addTask("TaskA",TaskType=padv.TaskType.User);
    taskB = pm.addTask("TaskB",Action=@MyTaskAction);
    taskC = pm.addTask("TaskC",TaskType=padv.TaskType.User);
    taskC.dependsOn(taskB); % unable to complete task C until task B complete
    taskB.runsAfter(taskA); % put task A before task B in the Tasks column

end

function taskResult = MyTaskAction(~)
    taskResult = padv.TaskResult;
end

In this example, TaskB is an automated task that user task TaskC depends on. You can automatically run the predecessors for a user task by pointing to the task, opening the task options menu (...), and clicking Run Predecessors.

After TaskB runs and passes, you are able to edit and mark TaskC as complete.

Alternatively, you can programmatically set user task results by using the utility function padv.util.setUserTaskResult.

Note

If you make a change to a task output, the user task results become outdated, but tasks that depends on the user task do not become outdated.

Input Arguments

pm — Process for project

padv.ProcessModel object (default)

Process for project, specified as a padv.ProcessModel object.

Example: pm = padv.ProcessModel

taskNameOrInstance — Name or instance of task

string | padv.Task object

Name or instance of a task, specified as a string or padv.Task object.

Example: "NameOfMyTask"

Example: padv.builtin.task.RunModelStandards

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: addTask(pm,"RunOnceForEachModel",IterationQuery=padv.builtin.query.FindModels)

Parameterization

RequiredIterationArtifactType — Artifact type that task can run on

"sl_model_file" | "m_file" | "zc_file" | ...

Type of artifact, specified as one or more of the values listed in this table. To specify multiple values, use an array.

Category	Artifact Type	Description
MATLAB®	"m_class"	MATLAB class
	"m_file"	MATLAB file
	"m_func"	MATLAB function
	"m_method"	MATLAB class method
	"m_property"	MATLAB class property
Model Advisor	"ma_config_file"	Model Advisor configuration file
	"ma_justification_file"	Model Advisor justification file
Model Finder	"mf_database"	Model Finder database file
Process Advisor	"padv_dep_artifacts"	Related artifacts that current artifact depends on
	"padv_output_file"	Process Advisor output file
Project	"project"	Current project file
Requirements	"mwreq_file"	Requirement file (since R2024b)
	"mwreq_item"	Requirement (since R2024b)
	"sl_req"	Requirement (for R2024a and earlier)
	"sl_req_file"	Requirement file (for R2024a and earlier)
	"sl_req_table"	Requirements Table
Stateflow®	"sf_chart"	Stateflow chart
	"sf_graphical_fcn"	Stateflow graphical function
	"sf_group"	Stateflow group
	"sf_state"	Stateflow state
	"sf_state_transition_chart"	Stateflow state transition chart
	"sf_truth_table"	Stateflow truth table
Simulink	"sl_block_diagram"	Block diagram
	"sl_data_dictionary_file"	Data dictionary file
	"sl_embedded_matlab_fcn"	MATLAB function
	"sl_block_diagram"	Block diagram
	"sl_library_file"	Library file
	"sl_model_file"	Simulink model file
	"sl_protected_model_file"	Protected Simulink model file
	"sl_subsystem"	Subsystem
	"sl_subsystem_file"	Subsystem file
System Composer™	"zc_block_diagram"	System Composer architecture
	"zc_component"	System Composer architecture component
	"zc_file"	System Composer architecture file
Tests	"harness_info_file"	Harness info file
	"sl_harness_block_diagram"	Harness block diagram
	"sl_harness_file"	Test harness file
	"sl_test_case"	Simulink Test™ case
	"sl_test_case_result"	Simulink Test case result
	"sl_test_file"	Simulink Test file
	"sl_test_iteration"	Simulink Test iteration
	"sl_test_iteration_result"	Simulink Test iteration result
	"sl_test_report_file"	Simulink Test result report
	"sl_test_result_file"	Simulink Test result file
	"sl_test_resultset"	Simulink Test result set
	"sl_test_seq"	Test Sequence
	"sl_test_suite"	Simulink Test suite
	"sl_test_suite_result"	Simulink Test suite result

Example: padv.Task("myTask",RequiredIterationArtifactType = "sl_model_file")

Data Types: string

IterationQuery — Artifacts that task iterates over

padv.Query object | name of padv.Query object

Artifacts that task iterates over, specified as a padv.Query object or the name of a padv.Query object. By default, task objects run one time and are associated with the project. When you specify IterationQuery, the task runs one time for each artifact returned by the padv.Query. In the Process Advisor app, the artifacts returned by IterationQuery appear under task title.

For example, if the IterationQuery for a task finds three models, Model_A, Model_B, and Model_C, the build system creates three task iterations under the title of the task in the Tasks column.

For more information, see Overview of Process Model and Find Artifacts with Queries.

Example: padv.Task("myTask",IterationQuery = padv.builtin.query.FindModels)

Data Types: string

InputDependencyQuery — Artifact dependencies for task inputs

padv.Query object | name of padv.Query object

Artifact dependencies for task inputs, specified as a padv.Query object or the name of a padv.Query object.

The build system runs the query specified by InputDependencyQuery to find the dependencies for the task inputs, since those dependencies can impact if task results are up-to-date. Typically, you specify InputDependencyQuery as padv.builtin.query.GetDependentArtifacts to get the dependent artifacts for each task input. For example, if you specify a model as an input to a task and you specify InputDependencyQuery as padv.builtin.query.GetDependentArtifacts, the build system can find artifacts, such as data dictionaries, that the model uses.

For more information, see Overview of Process Model and Find Artifacts with Queries.

Example: InputDependencyQuery = padv.builtin.query.GetDependentArtifacts

InputQueries — Inputs to task

padv.Query object | name of padv.Query object | array of padv.Query objects

Inputs to the task, specified as:

• a padv.Query object

• the name of padv.Query object

• an array of padv.Query objects

• an array of names of padv.Query objects

By default, padv.Task does not have inputs. When you specify InputQueries, the task uses the artifacts returned by the specified query or queries as inputs. Suppose a task runs once for each model in the project and you want to provide the models as inputs to the task. If you specify InputQueries as the built-in query padv.builtin.query.GetIterationArtifact, the query returns each artifact that the tasks iterates over, which in this example is each of the models in the project.

To add an input query to an existing task object, you can use addInputQueries.

For more information, see Overview of Process Model and Find Artifacts with Queries.

Example: padv.Task("myTask",InputQueries = padv.builtin.query.GetIterationArtifact)

OutputDirectory — Location for standard outputs that the task produces

"" (default) | string array

Location for standard outputs that the task produces, specified as a string.

Built-in tasks automatically specify OutputDirectory. If you do not specify OutputDirectory for a custom task, the build system stores task outputs in the DefaultOutputDirectory specified by padv.ProcessModel.

Data Types: string

TaskType — Type of task

padv.TaskType.Automated (default) | padv.TaskType.Manual | padv.TaskType.User

Type of task, specified as either:

• padv.TaskType.Automated — Automatically performs the task action and returns a task status. For example, this image shows automated tasks that passed, failed, and generated errors.

  

• padv.TaskType.Manual — Represents an action that a user manually performs as part of the process. The task is a reminder for the user. For example, this image shows a manual task that reminds users to link their requirements to tests. You can associate tools with the task to help users complete the task activity. The task does not have a status and you cannot run the task by using the build system. In Process Advisor, in the Tasks column, the manual task appears with a hand icon . For more information on task tools, see padv.TaskTool.

  

• padv.TaskType.User — Represents an action that a user performs and marks as complete by checking a checkbox. For example, this image shows user tasks that are not complete, drafted, blocked, and marked complete. For more information, see Add User Tasks.

  

These values belong to the enumeration class padv.TaskType.

Example: padv.TaskType.User

Behavior

Action — Function that task can run

function handle

Function that task can run, specified as the function handle.

If the task is defined in a function, the build system runs the function specified by Action. If the task is defined in a class, the build system ignores the Action and runs the run method for the class instead. The built-in tasks are defined in classes, so the build system calls the run method for those tasks.

Example: padv.Task("myTask",Action = @myFunction)

Data Types: function_handle

DryRunAction — Function that task can use during dry-run

function handle

Function that task can use during dry-run, specified as the function handle.

If the task is defined in a function, the build system dry-runs by calling the function specified by DryRunAction. If the task is defined in a class, the build system ignores the DryRunAction and dry-runs by calling the dryRun method for the class instead. The built-in tasks are defined in classes, so the build system calls the dryRun method for those tasks.

Example: padv.Task("myTask",DryRunAction = @myFunction)

Data Types: function_handle

DryRunLicenseCheckout — Dry-runs check out product licenses associated with tasks in process

logical.empty (default) | true or 1 | false or 0

Dry-runs check out product licenses associated with tasks in process, returned as a numeric or logical 1 (true) or 0 (false).

To perform a dry-run, you can specify the runprocess argument DryRun as true.

Example: true

Data Types: logical

Enabled — Controls if the padv.Task is enabled in the process model

true or 1 (default) | false or 0

Controls if the padv.Task is enabled in the process model, specified as a numeric or logical 1 (true) or 0 (false).

For an example, see Disable Task in Process Model.

Example: padv.Task("myTask",Enabled = false)

Data Types: logical

AlwaysRun — Always force task to run, even if the task results are already up to date

false or 0 (default) | true or 1

Always force task to run, even if the task results are already up to date, specified as a numeric or logical 0 (false) or 1 (true).

Example: padv.Task("myTask",AlwaysRun = true)

Data Types: logical

Description

Title — Human readable name that appears in Process Advisor app

string

Human readable name that appears in the Tasks column of the Process Advisor app, specified as a string. By default, the Process Advisor app uses the Name property of the task as the Title.

Example: padv.Task("myTask",Title = "My Task")

Data Types: string

DescriptionText — Task description

string

Task description, specified as a string.

Example: padv.Task("myTask",DescriptionText = "This is my task.")

Data Types: string

DescriptionCSH — Path to task documentation

string

Path to task documentation, specified as a string.

Example: padv.Task("myTask",DescriptionCSH = fullfile(pwd,"taskHelpFiles","myTaskDocumentation.pdf"))

Data Types: string

Licenses — List of licenses that task requires

string array

List of licenses that the task requires, specified as a string array.

Example: padv.Task("myTask",Licenses = ["matlab_report_gen" "simulink_report_gen"])

Data Types: string

Tools

LaunchToolAction — Function that launches a tool

function handle | cell array of function_handle objects

Function that launches a tool, specified as the function handle or a cell array of function_handle objects. For each action that you specify in LaunchToolAction, you must have corresponding text specified in LaunchToolText.

When the property LaunchToolAction is specified, you can point to the task in the Process Advisor app and click the ellipsis (...) and then Open Tool Name to open the tool associated with the task.

For tasks that are not built-in tasks, the task options show the ellipsis (...) and then Launch Tool.

Example: @openTool

Example: {@openToolA,@openToolB}

Data Types: cell | function_handle

Output Arguments

taskObj — Task object

padv.Task object

Task object, returned as a padv.Task object.

For more information, see padv.Task.