addAssessments

Add assessments to task

Syntax

addAssessments(taskObj,assessmentObj)

Description

addAssessments(taskObj,assessmentObj) adds assessments to the task. Each assessment that you add to the task must have a unique Id. Assessments appear in the Assessments property of the task.

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.

Examples

Assess Quality of Task Results

You can define and manage formal assessments of your task inputs and outputs by using a padv.Assessment object. The padv.Assessment object specifies the assessment objectives, the assessment action that the assessment performs to evaluate the task and determine the task status, and recommended actions. You can associate an assessment with a specific task by using the addAssessments method.

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 the following example code. The code defines:

• T — A custom task that uses the action function myTaskAction to create a task output file output.txt.

• A1 — An assessment that uses the action function assessOutputIsTxt to check if that output file is a text file.

• A2 — An assessment that uses the action function assessOutputFileContent to check if the output file is empty.

The assessment action functions summarize the results of the assessment by using padv.AssessmentResult objects.

function processmodel(pm)
    % Define process model for project

    arguments
        pm padv.ProcessModel
    end

    % --- Assessments ---
    A1 = padv.Assessment("A1",Objective="Output file must be a TXT file.",Action=@assessOutputIsTxt);
    A2 = padv.Assessment("A2",Objective="Output file should not be empty.",Action=@assessOutputFileContent);

    % --- Task ---
    T = padv.Task("MyTask",Action=@myTaskAction,OutputDirectory=fullfile("$PROJECTROOT$"));
    addAssessments(T,[A1,A2]);

    % Add the task to the process model
    pm.addTask(T);

end

function taskResult = myTaskAction(~)
    % Create a file named "output.txt"
    filename = "output.txt";
    fileID = fopen(filename,'w');
    fclose(fileID);
    % Create task result and specify file as task output
    taskResult = padv.TaskResult;
    taskResult.Status = padv.TaskStatus.Pass;
    taskResult.OutputPaths = fullfile(pwd,filename);
end

function res = assessOutputIsTxt(assessment, inputs, taskResult)
    try
        % Get first output artifact and its file address
        outputFile = taskResult.OutputArtifacts(1);
        fileAddress = outputFile.ArtifactAddress.getFileAddress();
        
        % Check if file has .txt extension
        [~, ~, ext] = fileparts(fileAddress);
        if strcmp(ext, ".txt")
            res = padv.AssessmentResult(assessment.Id, Status="Compliant");
            res.Summary = "Output file is TXT.";
            res.addCompliantArtifacts(outputFile);
        else
            res = padv.AssessmentResult(assessment.Id, Status="Warning");
            res.Summary = "Output file is not TXT.";
            res.addWarningArtifacts(outputFile);
        end
    catch
        res = padv.AssessmentResult(assessment.Id, Status="NonCompliant");
        res.Summary = "Output file is inaccessible or missing.";
    end
end

function res = assessOutputFileContent(assessment, inputs, taskResult)
    try
        % Get first output artifact and its file info
        outputFile = taskResult.OutputArtifacts(1);
        fileAddress = outputFile.ArtifactAddress.getFileAddress();
        fileID = fopen(fileAddress, 'r');
        fileContent = fread(fileID);
        fclose(fileID);
        % Check if file is empty
        if isempty(fileContent)
            res = padv.AssessmentResult(assessment.Id, Status="Warning");
            res.Summary = "Output file is empty.";
            res.addWarningArtifacts(outputFile);
        else
            res = padv.AssessmentResult(assessment.Id, Status="Compliant");
            res.Summary = "Output file is not empty.";
        end
    catch
        res = padv.AssessmentResult(assessment.Id, Status="NonCompliant");
        res.Summary = "Output file is inaccessible or missing.";
    end
end

In Process Advisor, run the task by clicking the Run All button.

In the Tasks column, the task status shows that the task passed. But the Details column shows one warning and one passing result.

Point to the task status to the left of the task name. Starting in R2024a, the Assessments section shows that the passing result comes from the A1 assessment because the task successfully generated a text file. The warning result comes from the A2 assessment because the task generates an empty text file.

View a breakdown of the assessments, assessment results, and the compliant, warning, and non-compliant artifacts by clicking Assessments in the task status pop-up. If you add recommended actions to your assessments by using the addRecommendedActions function, you can view those recommended actions in the Assessments dialog.

By default, non-compliant assessments cause the task to fail. But suppose that you want the warning assessment result to cause the task to fail. You can change the task definition in the process model to make the task fail on any warning results from the assessments by using the task property FailTaskOn.

    % --- Task ---
    T = padv.Task("MyTask",Action=@myTaskAction,OutputDirectory=fullfile("$PROJECTROOT$"));
    addAssessments(T,[A1,A2]);
    T.FailTaskOn="AnyWarning";

Run the task in Process Advisor by clicking Refresh Tasks and clicking the run button for the task.

In the Tasks column, the task status now shows that the task failed. If you point to the task status, the Assessments section now indicates that warnings and non-compliant assessments cause the task to fail.

Input Arguments

taskObj — Task

padv.Task object

Task, specified as a padv.Task object.

Example: padv.Task("MyTask")

assessmentObj — Task assessment

padv.Assessment object | array of padv.Assessment objects

Task assessment, specified as a padv.Assessment object or an array of padv.Assessment objects.

Each assessment that you add to the task must have a unique Id.

Example: padv.Assessment("A1",Objective="Each requirement has at least one test.",Action=@assessRequirementsTraceability)

Example: [padv.Assessment("A1",Objective="Obj 1",Action=@assessModels),padv.Assessment("A2",Objective="Obj 2",Action=@assessTestCases)]