padv.RecommendedAction

Recommended action based on assessment results

Description

A padv.RecommendedAction object represents a recommended action based on assessment results. You can use assessments in your tasks and process model to evaluate the compliance of task inputs and outputs against specific standards or custom criteria that you define and manage in the padv.Assessment object. To provide instructions that can help users fix the issues identified in the assessment results, you can specify the RecommendedActions property of a padv.Assessment object by using a padv.RecommendedAction object.

Starting in R2024a, when you point to the task status, you can click Assessments and view detailed information about artifact compliance and recommended actions in the Assessments dialog box.

Creation

Syntax

padv.RecommendedAction(Instruction=instructionInfo)

Description

padv.RecommendedAction(Instruction=instructionInfo) defines a recommended action by specifying an instruction for a user.

Input Arguments

instructionInfo — Instruction to help users fix issues in assessment results

"" (default) | string

Instruction to help users fix issues in assessment results, specified as a string.

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

Data Types: string

Properties

Instruction — Instruction to help users fix issues in assessment results

"" (default) | string

Instruction to help users fix issues in assessment results, specified as a string.

For example, if your assessment objective is to have each requirement link to at least one test, then in the assessment you can specify a recommended action of "Link requirement to test".

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

Data Types: string

Examples

Provide Recommended Action for Task Assessment

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 define a recommended action by using a padv.RecommendedAction object. You can add a recommended action to an assessment by using the addRecommendedActions 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. 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.