addRecommendedActions

Add recommended actions to assessment

Syntax

addRecommendedActions(assessmentObj,recommendedActions)

Description

addRecommendedActions(assessmentObj,recommendedActions) adds recommended actions to the assessment.

Examples

Add Recommended Actions to Assessment

You can define and manage formal assessments of your task inputs and outputs by using a padv.Assessment object. Your assessments can provides instruction to help users fix the issues identified in the assessment results. You can add these instructions by adding recommended actions objects, padv.RecommendedAction, to the assessment by using the function addRecommendedActions.

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. The assessment contains a recommended action specified by the addRecommendedActions function.

• A2 — An assessment that uses the action function assessOutputFileContent to check if the output file is empty. The assessment contains a recommended action specified by the addRecommendedActions function.

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);
    A1.addRecommendedActions(padv.RecommendedAction(Instruction="Change task action to output a TXT file."));
    A2 = padv.Assessment("A2",Objective="Output file should not be empty.",Action=@assessOutputFileContent);
    A2.addRecommendedActions(padv.RecommendedAction(Instruction="Change task action to output content into file."));

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

    % Add task to 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. You can view the recommended actions for addressing assessment compliance issues in the Assessments dialog.

By default, non-compliant assessments cause the task to fail. But suppose that you want a 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

assessmentObj — Task assessment

padv.Assessment object

Task assessment, specified as a padv.Assessment object.

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

recommendedActions — Recommended actions

padv.RecommendedAction object | array of padv.RecommendedAction objects

Recommended actions, specified as a padv.RecommendedAction object or an array of padv.RecommendedAction objects.

See padv.RecommendedAction.

Example: padv.RecommendedAction(Instruction="Link requirement to test.")

Example: [padv.RecommendedAction(Instruction="Link requirement to test."),padv.RecommendedAction(Instruction="Add new test and link test to requirement.")]