padv.TaskResult

Create and access results from task

Description

This object requires CI/CD Automation for Simulink Check. A padv.TaskResult object represents the results from a task. The run function of a padv.Task creates a padv.TaskResult object that you can use to access the results from the task. When you create a custom task, you can specify the results from your custom task. You can also use the function getProcessTaskResults to view a list of the last task results for a project. The Process Advisor app uses task results to determine the task statuses, output artifacts, and detailed task results that appear in the Tasks, I/O, and Details columns of the app.

Creation

Syntax

resultObj = padv.TaskResult()

Description

resultObj = padv.TaskResult() creates a result object resultObj that represents the results from a task.

Properties

Status — Task result status

Pass (default) | Fail | Error

Task result status, returned as:

• Pass — A passing task status. The task completed successfully without failures or errors.

• Fail — A failing task status. The task completed, but the results were not successful.

• Error — An error task status. The task generated an error and did not complete.

The Status property determines the task status shown in the Tasks column in the Process Advisor app.

For custom tasks, you can specify the task result status as either:

• padv.TaskStatus.Pass — Sets the Status property to Pass.

• padv.TaskStatus.Fail — Sets the Status property to Fail.

• padv.TaskStatus.Error — Sets the Status property to Error.

For example, taskResult.Status = padv.TaskStatus.Fail sets the Status property of the task result object to Fail to represent a failing task status.

Example: Fail

OutputArtifacts — Artifacts created by task

padv.Artifact object | array of padv.Artifact objects

Artifacts created by the task, returned as a padv.Artifact object or array of padv.Artifact objects.

The OutputArtifacts property determines the output artifacts shown in the I/O column in the Process Advisor app.

The build system only manages output artifacts specified by the task result. For custom tasks, use the OutputPaths argument to define the output artifacts for the task result.

Details — Temporary storage for task-specific data

struct

Temporary storage for task-specific data, returned as a struct. The build system uses Details to store task-specific data that other build steps can use.

Note that Details are temporary. The build system does not save Details with the task results after the build finishes.

Data Types: struct

Values — Number of passing, warning, and failing conditions

struct with Pass: 0, Warn: 0, Fail: 0 (default) | struct with fields Pass, Warn, Fail

Number of passing, warning, and failing conditions, returned as a struct with fields:

• Pass — Number of passing conditions returned by task

• Warn — Number of warning conditions returned by task

• Fail — Number of failing conditions returned by task

The Values property determines the detailed results shown in the Details column in the Process Advisor app.

For example, the task padv.builtin.task.RunModelStandards runs several Model Advisor checks and returns the number of passing, warning, and failing checks. If you run the task and one check passes, two checks generate a warning, and three checks fail, Values returns:

ans = 

  struct with fields:

    Pass: 1
    Warn: 2
    Fail: 3

Data Types: struct

OutputPaths — Define OutputArtifacts for task result

string

This property is write-only.

OutputArtifacts for task result, specified as a string or string array.

The build system adds each path specified by OutputArtifacts to the OutputArtifacts argument as a padv.Artifact object with type padv_output_file.

Example: taskResultObj.OutputPaths = string(fullfile(pwd,filename))

Example: taskResultObj.OutputPaths = [string(fullfile(pwd,filename1)), string(fullfile(pwd,filename2))]

Data Types: char | string

Object Functions

• applyStatus

Examples

Create Task Result for Custom Task

Create a padv.TaskResult object for a custom task that has a failing task status, outputs a single .json file, and 1 passing condition, 2 warning conditions, and 3 failing conditions.

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 example process model code:

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

    arguments
        pm padv.ProcessModel
    end

    addTask(pm,"ExampleTask",Action=@ExampleAction);

end

function taskResult = ExampleAction(~)

    % Create a task result object that stores the results
    taskResult = padv.TaskResult();

    % Specify the task status shown in the Tasks column
    taskResult.Status = padv.TaskStatus.Fail;

    % Specify the output files shown in the I/O column
    cp = currentProject;
    rf = cp.RootFolder;
    outputFile = fullfile(rf,"tools","sampleChecks.json");
    taskResult.OutputPaths = string(outputFile);
    
    % Specify the values shown in the Details column
    taskResult.Values.Pass = 1;
    taskResult.Values.Warn = 2;
    taskResult.Values.Fail = 3;

end

Save the processmodel.m file.

Go back to the Process Advisor app and click Refresh Tasks to update the list of tasks shown in the app.

In the top-left corner of the Process Advisor pane, switch the filter from Model to Project.

In the top-right corner of the Process Advisor pane, click Run All.

• The Tasks column shows a failing task status to the left of ExampleTask. This code from the example process model specifies the task status shown in the Tasks column:

  taskResult.Status = padv.TaskStatus.Fail;

• The I/O column shows an output artifact associated with the task. This code from the example process model specifies the output artifact shown in the I/O column:

  taskResult.OutputPaths = string(fullfile(pwd,outputFile));

• The Details column shows 1 passing condition, 2 warning conditions, and 3 failing conditions. This code from the example process model specifies the detailed task results shown in the Details column:

  taskResult.Values.Pass = 1;
  taskResult.Values.Warn = 2;
  taskResult.Values.Fail = 3;

Version History

R2023a: ResultValues will be removed

The ResultValues property will be removed in a future release. Use the Values property instead.