addTask
Add task instance to process model
Description
adds the task specified by taskObj
= addTask(pm
,taskNameOrInstance
)taskNameOrInstance
to the process model. You
can access the task using the task object taskObj
. For more
information, see Add Tasks to Process.
specifies the properties of the task using one or more taskObj
= addTask(___,Name=Value
)Name=Value
arguments.
Examples
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 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 afterTaskA
because of therunsAfter
function.TaskC
depends onTaskB
, meaning that you cannot completeTaskC
untilTaskB
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
Process for project, specified as a padv.ProcessModel
object.
Example: pm = padv.ProcessModel
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
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) | |
| 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
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
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
Inputs to the task, specified as:
a
padv.Query
objectthe name of
padv.Query
objectan array of
padv.Query
objectsan 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)
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
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
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
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
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
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
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
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
Task description, specified as a string.
Example: padv.Task("myTask",DescriptionText = "This is my
task.")
Data Types: string
Path to task documentation, specified as a string.
Example: padv.Task("myTask",DescriptionCSH =
fullfile(pwd,"taskHelpFiles","myTaskDocumentation.pdf"))
Data Types: string
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
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
Task object, returned as a padv.Task
object.
For more information, see padv.Task
.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)