Write Callbacks to Analyze Safety Analysis Manager Documents

You can use callbacks in the Safety Analysis Manager to analyze the status of your documents and populate the content by reassigning values or adding flags. You can run callbacks manually or automatically.

Create Callbacks

To create a callback:

Open or create a Safety Analysis Manager document. For more information on creating spreadsheets, see Create Spreadsheets in the Safety Analysis Manager.
In the Analyze section, click Edit Callbacks. The Callbacks Editor window opens.

Enter your script in one or more of these callback types:

Callback Type	When Executed
PreLoadFcn	Before the spreadsheet loads
PostLoadFcn	After the spreadsheet loads
AnalyzeFcn	When you click Analyze Spreadsheet or press F5
PreSaveFcn	Before the spreadsheet is saved
PostSaveFcn	After the spreadsheet is saved
CloseFcn	Before the spreadsheet is closed

Exit the Callbacks Editor window to save the callbacks.

You can write scripts manually in the Callback Editor window or write scripts that execute other MATLAB^® files on path.

The AnalyzeFcn callback type includes a default callback that is always enabled. You can also add custom AnalyzeFcn callbacks that you can enable or disable (since R2024a). See Create and Select Custom Callbacks for Safety Analysis Manager Documents.

If your spreadsheet uses derived columns that call externally defined MATLAB functions, and you update the function, the spreadsheet does not automatically refresh the derived cell values. To refresh the cell values and then run the AnalyzeFcn callbacks, click Analyze Spreadsheet > Refresh Values and Analyze Spreadsheet (since R2024b).

Modify Spreadsheets with Keywords

To modify a spreadsheet by using callback, retrieve the Spreadsheet object by using the sfa_spreadsheet keyword. For example, this code retrieves and stores the Spreadsheet object in the variable x.

x = sfa_spreadsheet;

If you write MATLAB files and call them in the callback, the files cannot use this keyword.

Add Flags to Documents

Use flags to visually indicate errors, warnings, and checks. In spreadsheets, you can add multiple flags to cells (since R2023b) and rows (since R2024b). You can use callbacks to add flags to your spreadsheets.

To add flags to a spreadsheet by using a callback:

Retrieve the Spreadsheet object by using the sfa_spreadsheet keyword.
Retrieve the cell by using the getCell function, or retrieve the row by using the getRow function. The getCell function returns the cell as a SpreadsheetCell object, and the getRow function returns the row as a SpreadsheetRow object.
Add the flag by using the addFlag function on the object.

Safety Analysis Manager spreadsheets support these flags.

Flag Type	Description
Error	An error flag. Cells and rows with an error flag display the error icon .
Warning	A warning flag. Cells and rows with a warning flag display the warning icon .
Check	A check flag. Cells and rows with a check flag display the check icon .

After you add flags, the Safety Analysis Manager displays the flags in the Properties pane. The Spreadsheet tab displays the cells for the entire spreadsheet, the Row tab displays the flags in the selected row, and the Cell tab displays the flags in the selected cell. For example, this image shows the Spreadsheet tab in a Safety Analysis Manager spreadsheet that contains three flags in cells, and one flag in a row.

The Spreadsheet tab in a Safety Analysis Manager spreadsheet that contains three flags in cells, and one flag in a row. Each flag has a description just below the link.

When you run callbacks in the AnalyzeFcn parameter, the Safety Analysis Manager clears the flags from the document before executing the script. To manually clear the flags without running the callback, in the Analyze section, click Clear Flags. To clear individual flags in spreadsheets, in the Properties pane, in the Cell, Row, or Spreadsheet tabs, in the Flags section, select the flag description and press Delete on your keyboard. To delete multiple flags, select the flag type, containing column, or containing row, and press Delete on your keyboard.

Spreadsheet Callback Example

Open Script

This example runs a callback on a Safety Analysis Manager spreadsheet to flag cells based on their content. Open the FMEA_spreadsheet_example.mldatx file to view the spreadsheet.

The spreadsheet is a Failure Mode and Effects Analysis (FMEA) that assesses possible failures in the volume control of a mixing vessel. The vessel takes in liquid from an inlet pump, mixes it with other products, and then expels the new solution through an outlet pump. The vessel must maintain a steady mixing volume by consistently taking in as much liquid as it expels.

Inspect the RPN Calculation

The FMEA assesses the importance of the failure by calculating the risk priority number (RPN) for each failure mode, its cause, and its likelihood of detection. This number appears in the derived column named RPN. View the column formula to see the code. In the spreadsheet, right-click the column label and click Edit Formula.

The column formula checks the Severity, Failure Probability, and Detection Rating column values by using the sfa_columnValue operator. See Define Derived Values. If at least one of the column values is empty, then the derived column outputs a message. Otherwise, the column calculates the RPN by taking the product of the values in the Severity, Failure Probability, and Detection Rating columns.

if isempty(sfa_columnValue("Failure Probability")) ||...
          isempty(sfa_columnValue("Severity")) || ...
          isempty(sfa_columnValue("Detection Rating"))
    sfa_derivedValue = "Unable to calculate";
else
    fp = str2double(sfa_columnValue("Failure Probability"));
    s = str2double(sfa_columnValue("Severity"));
    d = str2double(sfa_columnValue("Detection Rating"));
     sfa_derivedValue = fp*s*d;
end

Inspect the Callback

The spreadsheet includes an AnalyzeFcn callback that executes when you analyze the spreadsheet. Open the callback to view the code. In the Analyze section, click Edit Callbacks and select AnalyzeFcn. Running the callback adds flags to cells and rows based on these conditions:

If the cell in the Verified column is not checked, add a warning flag to it.
If the cell in the Severity, Failure Probability, or Detection Rating column does not have a value, add an error flag to the corresponding cell.
If at least one of the cells in the Verified, Severity, or Failure Probability columns is empty, do not add a flag to the cell in RPN column of the same row.
If the value of the cell in the RPN column is greater than 100, add an error flag to the row.
If the value of the cell in the RPN column is less than or equal to 100 and greater than 35, add a warning flag to the row.
If the value of the cell in the RPN column is less than or equal to 35 add a check flag to the row.

for rowIndex = 1:sfa_spreadsheet.Rows
% Get the cells to update
   failurePCells = getCell(sfa_spreadsheet,rowIndex,...
          "Failure Probability");
    severeCells = getCell(sfa_spreadsheet,rowIndex,...
          "Severity");
    detectCells = getCell(sfa_spreadsheet,rowIndex,...
          "Detection Rating");
    updatedCells = getCell(sfa_spreadsheet,rowIndex,...
          "Failure Mode");

     isVerifiedCells = getCell(sfa_spreadsheet,...
           rowIndex,"Verified");
     rpnCells = getCell(sfa_spreadsheet,rowIndex,"RPN");
     rpnRows = getRow(rpnCells);

% Flag rows that are not verified or rated
    if isVerifiedCells.Value == 0
        addFlag(isVerifiedCells,"warning",Description=...
           "Failure mode has not been verified.")
    end
    if isempty(severeCells.Value)
        addFlag(severeCells,"error",Description=...
            "Failure mode needs severity rating.")
    end
    if isempty(failurePCells.Value)
        addFlag(failurePCells,"error",Description=...
            "Failure mode needs probability rating.")
    end
    if isempty(detectCells.Value)
        addFlag(detectCells,"error",Description=...
            "Failure mode needs detection rating.")
    end

% Evaluate RPN and assign flags
    if isempty(severeCells.Value) || ...
             isempty(failurePCells.Value) || ...
             isempty(detectCells.Value)
        continue
    elseif str2double(rpnCells.Value) > 100
        addFlag(rpnRows,"error",Description=...
            "Risk Priority Number exceeds allowable amount." +...
            "Create a mitigation strategy.")
    elseif str2double(rpnCells.Value) <= 100 && ...
            str2double(rpnRows.Value) > 35
        addFlag(rpnRows,"warning",Description=...
            "Risk Priority Number is high." +...
            "Consider a mitigation strategy!")
    elseif str2double(rpnCells.Value) <= 35
        addFlag(rpnRows,"check",Description=...
            "Risk Priority Number is sufficiently low.")
    end
end

Analyze the Spreadsheet

Click Analyze Spreadsheet to run the callback.

To view different flag outputs, adjust the cell values and rerun the analysis.