addWarningArtifacts

Add artifacts with warnings to assessment result

Syntax

addWarningArtifacts(assessmentResult,padvArtifacts)

Description

addWarningArtifacts(assessmentResult,padvArtifacts) associates task artifacts with the assessment result and categorizes those artifacts with a warning.

Starting in R2024a, if you point to a task status and click Assessments, the Assessments dialog can show the artifacts with warnings.

Examples

Assess Quality of Task Results

When you define an assessment, you can use the assessment to categorize task artifacts with a warning by using the addWarningArtifacts function.

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$"),...
        Assessments=[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$"),...
        Assessments=[A1,A2],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

assessmentResult — Result from assessment

padv.AssessmentResult object

Result from assessment, specified as a padv.AssessmentResult object.

Example: padv.AssessmentResult("A1")

padvArtifacts — Artifacts

padv.Artifact object | array of padv.Artifact objects

Artifacts, specified as either a padv.Artifact object or an array of padv.Artifact objects.

You can create an artifact object by using padv.Artifact or you can find artifact objects by using built-in or custom queries. For more information, see Find Artifacts with Queries.

Example: padv.Artifact("artifactType","artifactAddress")