How to retrieve use story scenario via Open API

In requirement capturing use case is typically used to model the system goal where there user or stakeholder would like to achieve. Sometimes the use case could be very big and hard to manage. In agile development approach the use case would further break down into smaller pieces called user story. The user story is small and should be able to complete within a sprint so that the team can easily manage it and make progress to the development in consistent manner. Visual Paradigm support capture requirements with user stories, and within each user story user can define various execution scenarios that developers should be catered during development. The user story scenario is not just available to access within the VP’s interface, but also accessible from the Open API. In this article we will show you how to retrieve the scenario information using Open API.

The user story scenario is stored in the following structure:

Model structure of user story scenario

Therefore in order obtain the scenarios we have to drill down from use case to user story, then to scenario and finally obtain the steps. Let’s start from the use cases. We can make use of the toModelElementArray method form the IProject to obtain the use cases.

// Obtain the current opening project
IProject project = ApplicationManager.instance().getProjectManager().getProject();

// Retrieve all use cases in the project
IModelElement[] useCases = project.toModelElementArray(IModelElementFactory.MODEL_TYPE_USE_CASE);

Once we obtained the use cases into an array, we can walk though it (i.e. using for loop) to obtain the user stories under that particular use case.

for (int i = 0; i < useCases.length; i++) {
    IUseCase useCase = (IUseCase) useCases[i];
    // Print out the name of the use case
    ApplicationManager.instance().getViewManager().showMessage("Use Case: " + useCase.getName());
    // Retrieve all user stories from use case
    IUserStory[] userStories = useCase.toUserStoryArray();

Next we can retrieve the scenario (IStepContainer) from user story.

for (int j = 0; j < userStories.length; j++) {
    IUserStory userStory = (IUserStory) userStories[j];
    // Retrieve all scenarios from user story
    IStepContainer[] scenarios = userStory.toScenarioArray();

Finally we can obtain the steps (IStep) from IStepContainer

for (int k = 0; k < scenarios.length; k++) {
    IStepContainer scenario = (IStepContainer) scenarios[k];
    // Print put the name of the scenario
    ApplicationManager.instance().getViewManager().showMessage("Scenario: " + scenario.getName());
    // Retrieve all steps from scenario
    IStep[] steps = scenario.toStepArray();

Now we can walk through the steps and manipulate it.

Working with sub-steps

Each scenario step can contain sub-steps and they can be retrieved using the toStepArray() method from IStep.

// Retrieve the sub-steps
IStep[] steps = step.toStepArray();
if (steps != null && steps.length > 0) {
    // Walk through the sub-steps
    for (int i = 0; i < steps.length; i++) {

Working with Extensions

Similar to sub-steps, each steps can define its own extension steps. The extension steps can be retrieved using the toExtensionArray() method form IStep.

// Retrieve the extension steps
IExtension[] extensions = step.toExtensionArray();
if (extensions != null && extensions.length > 0) {
    // Walk through the extension steps
    for (int i = 0; i < extensions.length; i++) {

Sample Plugin

The sample plugin attached in this article demonstrate how to retrieve the scenarios under user stories and print them into message pane. After you deploy your plugin into Visual Paradigm you can click the Retrieve User Story Scenario button to list out the scenarios.

Trigger sample plugin

User story scenario output to message pane

Download Sample Plugin

You can click this link to download the sample plugin.