Import Requirements from a Microsoft Excel Document

Open Live Script

This example shows how to import requirements from a Microsoft® Excel® document. You can map columns from the Excel spreadsheet to certain requirements properties and custom attributes. You can also assign specific values to the imported requirements, such as the requirement type or index, by using a callback that executes after the requirements import. You can only import requirements from Microsoft Excel on Microsoft Windows® platforms.

This example uses the ExampleRequirements Excel file. To open the file, enter:

winopen("ExampleRequirements.xlsx")

Author a `PostImportFcn` Callback Script

You can author a script and register it as the PostImportFcn callback to process imported requirements in Requirements Toolbox™ immediately after the import finishes. This example uses the slreqExamplePostImportXls script as the PostImportFcn callback. View the script by entering:

edit("slreqExamplePostImportXls.m")

Requirements import from Excel with the Functional type by default. The first for loop in the script iterates over each imported requirement to assign the requirement type. The loop checks the original requirement type from the Microsoft Excel file and then sets the imported requirement type to the built-in Requirements Toolbox requirement type that aligns with the imported type. If the requirement in Excel does not have a requirement type, the script leaves the requirement as a Functional type requirement.

idToRef = containers.Map('KeyType','char','ValueType','Any');
topRefs = slreq.getCurrentObject;
reqSet = topRefs(1).parent;

refs = reqSet.find('type','Reference');
for i = 1:numel(refs)
    ref = refs(i);
    switch ref.getAttribute('orig_Type')
        case 'Heading'
            ref.Type = 'Container';
        case 'Note'
            ref.Type = 'Informational';
        otherwise
            % leave AS IS
    end
    % build the Map of IDs for the next step
    idToRef(ref.Id) = ref;
end

The second for loop iterates over each imported requirement and applies the requirements hierarchy defined in Excel.

sortedIds = sort(keys(idToRef));
for i = 2:numel(sortedIds)
    thisId = sortedIds{i};
    % Find the parent ID by truncating this ID at the last '.'
    parentId = '';
    dotCharIdx = find(thisId == '.');
    if ~isempty(dotCharIdx)
        parentId = thisId(1:dotCharIdx(end)-1);
    end
    if ~isempty(parentId)
        ref = idToRef(thisId);
        parentObj = idToRef(parentId);
        setParent(ref,parentObj.SID);
    end
end

The Excel file uses a period (.) in the requirement ID to indicate different levels of the requirement hierarchy. The script uses the period to identify the hierarchy levels and re-create the hierarchy.

Configure Import Options

Create a structure that contains the options to use during import. List the range of columns and rows of the Excel file that contain requirements.

importOptions = struct("columns",[2 7],"rows",[3 56]);

Add information to map the requirements data from requirements in Excel to Requirements Toolbox. Map columns 2, 4, and 5 to the built-in slreq.Reference properties ID, Summary, and Description.

importOptions.idColumn = 2;
importOptions.summaryColumn = 4;
importOptions.descriptionColumn = 5;

Columns 3, 6, and 7 cannot be directly mapped to slreq.Reference properties. Map these columns to custom attributes called orig_Type, Remark, and Status. Note that the requirement type in Excel maps to a custom attribute, instead of to the Type property of the slreq.Reference objects.

importOptions.attributes = {'orig_Type','Remark','Status'};
importOptions.attributeColumn = [3 6 7];

importOptions.postImportFcn = "slreqExamplePostImportXls";

Import the Requirements

Import the requirements from the Requirements sheet in the ExampleRequirements Excel file into a new requirement set called ImportedFromExcel by using slreq.import. Import the requirements as plain text referenced requirements with additional import options specified from the options structure. Return the number of imported referenced requirements, the requirement set file path, and a handle to the requirement set.

[count,reqSetFilePath,reqSet] = slreq.import("ExampleRequirements.xlsx", ...
    ReqSet="ImportedFromExcel",AsReference=true,RichText=false, ...
    subDoc="Requirements",options=importOptions);

Save the imported requirement set, then examine it in the Requirements Editor.

save(reqSet);
explore(reqSet);

The slreqExamplePostImportXls script is registered as the PostImportFcn callback function for the Import node. The callback also executes if you update the requirement set.

Examine the Imported Requirement Types

Examine the imported requirements and compare the requirement types to the requirements in Excel. The callback function assigned types to the imported requirements by using the Requirements Toolbox built-in types. For example, requirement 1 had the type Heading in the Excel file and imports with the type Container.

req1 = slreq.find(Type="Reference",Index="1");
originalType1 = getAttribute(req1,"orig_Type")

originalType1 = 
'Heading'

importedType1 = getAttribute(req1,"Type")

importedType1 = 
'Container'

Requirement 1.1 had the type Note in Excel and imports with the type Informational.

req2 = slreq.find(Type="Reference",Index="1.1");
originalType2 = getAttribute(req2,"orig_Type")

originalType2 = 
'Note'

importedType2 = getAttribute(req2,"Type")

importedType2 = 
'Informational'

Requirement 2.1.1 had no indicated type in Excel and imports with the type Functional.

req3 = slreq.find(Type="Reference",Index="2.1.1");
originalType3 = getAttribute(req3,"orig_Type")

originalType3 =

  0×0 empty char array

importedType3 = getAttribute(req3,"Type")

importedType3 = 
'Functional'

Examine the Imported Requirement Hierarchy

Examine the hierarchy of the imported requirements and compare the hierarchy to the Excel file. The callback function created the hierarchy of the imported requirements based on the hierarchy from the Excel file. For example, requirement 2.1.1 in Excel has 6 child requirements.

Get the child requirements for the imported requirement 2.1.1.

childReqs = children(req3)

childReqs=1×6 object
  1×6 Reference array with properties:

    Id
    CustomId
    Artifact
    ArtifactId
    Domain
    UpdatedOn
    CreatedOn
    CreatedBy
    ModifiedBy
    IsLocked
    Summary
    Description
    Rationale
    Keywords
    Type
    IndexEnabled
    IndexNumber
    SID
    FileRevision
    ModifiedOn
    Dirty
    Comments
    Index

In Excel, the first child requirement of 2.1.1 has the title Cruise. Get the summary for the first child requirement in the array.