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

padv.TaskStatus.Pass (default) | padv.TaskStatus.Fail | padv.TaskStatus.Error

Task result status, returned as:

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

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

• padv.TaskStatus.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.

Example: padv.TaskStatus.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

Note

For a padv.TaskResult object, you can either specify the Values property, specify the ComplianceStatusSummary property, or allow your assessments to specify the AssessmentResults property. You can only use one of these approaches for a given task. For more information, see Create Custom Tasks.

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

Assessments

ComplianceStatusSummary — Summary of compliant, warning, and non-compliant statuses in task assessment

dictionary

Summary of compliant, warning, and non-compliant statuses in task assessment, specified as a dictionary that maps the possible compliance statuses to the number of assessment results with that status.

The possible compliance statuses are:

• Compliant — The task meets the assessment objective.

• Warning — The task might not meet the assessment objective and needs review.

• NonCompliant — The task does not meet the assessment objective.

By default, the dictionary starts with each count set to zero. You can set these counts by using the setComplianceCount function to overwrite the values. Alternatively, you can add to these counts by using the addComplianceStatus function to increment the existing values.

  dictionary (padv.ComplianceStatus ⟼ uint64) with 3 entries:

    Compliant    ⟼ 0
    Warning      ⟼ 0
    NonCompliant ⟼ 0

The task result object uses these values to specify the Values property of the task result. The ComplianceStatusSummary property is read-only unless you specify the property value by using the setComplianceCount or addComplianceStatus functions.

Note

For a padv.TaskResult object, you can either specify the Values property, specify the ComplianceStatusSummary property, or allow your assessments to specify the AssessmentResults property. You can only use one of these approaches for a given task. For more information, see Create Custom Tasks.

Example: dictionary(padv.ComplianceStatus.Compliant,uint64(0),padv.ComplianceStatus.Warning,uint64(0),padv.ComplianceStatus.NonCompliant, uint64(0))

AssessmentResults — Results from assessment

padv.AssessmentResult object | array of padv.AssessmentResult objects

Results from assessment, specified as a padv.AssessmentResult object or an array of padv.AssessmentResult objects.

The AssessmentResults property is read-only. When you add assessments to a task and run the task, the task automatically runs the assessment and adds the assessment results to the task results. The task result object uses the assessment results to set the ComplianceStatusSummary property, which sets the Values property of the task result object.

Note

For a padv.TaskResult object, you can either specify the Values property, specify the ComplianceStatusSummary property, or allow your assessments to specify the AssessmentResults property. You can only use one of these approaches for a given task. For more information, see Create Custom Tasks.

Starting in R2024a, when you point to the task status, you can see a breakdown of the individual assessments for a task, the assessment results, and the impact of those assessment results on the overall task status. The assessment information provides the specific objectives associated with the failures, warnings, and passing results that you see in the Details column.

Example: padv.AssessmentResult("A1",Status="Warning")

Example: [padv.AssessmentResult("A1",Status="Warning"),padv.AssessmentResult("A2",Status="NonCompliant")]

Object Functions

applyStatus	Apply new task status if priority is higher
addComplianceStatus	Add to number of results with specified compliance status
setComplianceCount	Set number of results with specified compliance status

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.