gh-secondsky-sap-skills-skills-sap-sac-scripting/references/best-practices-planning-stories.md

Best Practices for Planning Stories in SAP Analytics Cloud

Architectural patterns and user experience guidelines for building professional planning applications with multi-story navigation.

Source: SAP PRESS Blog - Best Practices for Planning Stories in SAP Analytics Cloud
Book: Application Development with SAP Analytics Cloud by Josef Hampp and Jan Lang (SAP PRESS, 2024)

---

Table of Contents

1. Entry Point Design
2. Multi-Story Architecture
3. Story Navigation via Scripting
4. User Assistance Patterns
5. Guided Process Implementation
6. Button Design Guidelines

---

Entry Point Design

Create an overview/start page as the single entry point for users into the planning process.

Structure

A well-designed entry page should be structured and not overloaded:

┌─────────────────────────────────────────────────────────┐
│  KPI TILES (Top Section)                                │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │
│  │ Metric1 │ │ Metric2 │ │ Metric3 │ │ Metric4 │       │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘       │
├─────────────────────────────────────────────────────────┤
│  NAVIGATION SECTIONS (Visually Separated)               │
│  ┌─────────────────┐ ┌─────────────────┐ ┌────────────┐│
│  │ Configure App   │ │ Plan FTE        │ │ Reports    ││
│  │ & Parameters    │ │ Demands & Costs │ │            ││
│  │                 │ │                 │ │            ││
│  │ > Settings      │ │ > Workforce     │ │ > Summary  ││
│  │ > Parameters    │ │ > Budget        │ │ > Details  ││
│  └─────────────────┘ └─────────────────┘ └────────────┘│
└─────────────────────────────────────────────────────────┘

Key Elements

Element	Purpose
KPI Tiles	Display most important key figures at a glance
Navigation Areas	Group related planning functions (3-4 max)
Jump Links	Text fields with onClick scripts to navigate to sub-stories
Visual Separation	Clear boundaries between functional areas

Benefits

• Provides orientation for users in complex planning processes
• Reduces cognitive load with organized navigation
• Enables easy access to all planning phases from one location

---

Multi-Story Architecture

Separate individual planning steps into distinct stories for simplified maintenance.

Folder Organization

Store all related stories in a dedicated folder structure:

SAC File System/
└── Planning_Application_2024/
    ├── 00_Entry_Point.story
    ├── 01_Application_Configuration.story
    ├── 02_Plan_FTE_Demands.story
    ├── 03_Plan_Costs.story
    ├── 04_Summary_Report.story
    └── 05_Detail_Report.story

Benefits

Benefit	Description
Easier Maintenance	Update one story without affecting others
Team Collaboration	Multiple developers can work on different stories
Version Control	Track changes at story level
Performance	Smaller stories load faster
Testing	Test individual planning steps independently

Implementation Guidelines

1. Create one story per planning phase or major step
2. Use consistent naming with numeric prefixes for ordering
3. Share data sources across stories using the same model
4. Implement consistent navigation patterns across all stories

---

Story Navigation via Scripting

Use scripting instead of standard hyperlinks for cross-story navigation with URL parameters.

Full Navigation Script

Add this script to a Script Object for reuse across your entry point:

/**
 * Opens a target story with specified display mode and page
 * @param {string} arg_StoryIdPageIndex - Format: "storyId|pageIndex"
 * @param {string} arg_displayMode - "view" or "edit"
 */
function navigateToStory(arg_StoryIdPageIndex, arg_displayMode) {
    var delimiter_storyIdPageIndex = "|";
    
    // Extract story ID and page index from the combination provided
    var storyId = arg_StoryIdPageIndex.substring(
        0, 
        arg_StoryIdPageIndex.indexOf(delimiter_storyIdPageIndex)
    );
    var pageIndex = arg_StoryIdPageIndex.substring(
        arg_StoryIdPageIndex.indexOf(delimiter_storyIdPageIndex) + 1
    );
    
    // Create and fill array of URL parameters
    var urlParameters = ArrayUtils.create(Type.UrlParameter);
    urlParameters.push(UrlParameter.create("mode", arg_displayMode));
    urlParameters.push(UrlParameter.create("page", pageIndex));
    
    // Optional: Add custom URL parameters
    // urlParameters.push(UrlParameter.create("p_myParam", "value"));
    
    // Open the target story
    NavigationUtils.openStory(storyId, "", urlParameters, false);
}

Usage in onClick Event

// onClick of txt_navigate_to_workforce
// Story ID from the target story's URL, page index 0-based
ScriptObject_Navigation.navigateToStory("STORY123ABC|0", "view");

Storing Story IDs

Create a Script Object to store story IDs for easy maintenance:

// ScriptObject_StoryRegistry
var STORIES = {
    CONFIGURATION: "ABC123DEF|0",
    WORKFORCE_PLAN: "GHI456JKL|0",
    COST_PLAN: "MNO789PQR|0",
    SUMMARY_REPORT: "STU012VWX|1",
    DETAIL_REPORT: "YZA345BCD|0"
};

function getStoryReference(storyName) {
    return STORIES[storyName];
}

---

User Assistance Patterns

Implement consistent help features across all planning stories.

Sidebar Structure

Include a sidebar on every story (except entry page) with:

┌──────────────────────┐
│  FILTERS             │
│  ├─ Year: [2024 ▼]   │
│  ├─ Region: [All ▼]  │
│  └─ [Apply Filters]  │
├──────────────────────┤
│  NAVIGATION          │
│  ├─ ← Back to Entry  │
│  ├─ → Next Step      │
│  └─ ↺ Home           │
├──────────────────────┤
│  INSTRUCTIONS        │
│  Step 1: Select...   │
│  Step 2: Enter...    │
│  Step 3: Save...     │
├──────────────────────┤
│  EXTERNAL LINKS      │
│  ├─ 📖 Documentation │
│  ├─ ❓ Ask Question  │
│  └─ ℹ️ Process Info  │
└──────────────────────┘

Step-by-Step Instructions

Provide clear instructions directly in the sidebar:

INSTRUCTIONS
────────────────────
Step 1: Select the planning version
        from the dropdown above

Step 2: Enter FTE values in the table
        for each cost center

Step 3: Review the calculated costs
        in the summary section

Step 4: Click "Save" to store your
        changes

Step 5: Click "Submit" when ready
        for approval

Benefits

• Ensures consistent user experience across all stories
• Reduces support requests with inline help
• Enables occasional users to complete planning correctly

---

Guided Process Implementation

Implement a "Guide Me!" button that opens a focused popup with step-by-step guidance.

Popup Design

┌─────────────────────────────────────┐
│  ✨ Planning Guide                 X│
├─────────────────────────────────────┤
│                                     │
│  Welcome to Workforce Planning!     │
│                                     │
│  Follow these steps:                │
│                                     │
│  ☐ 1. Select your cost center       │
│  ☐ 2. Choose the planning period    │
│  ☐ 3. Enter FTE values              │
│  ☐ 4. Review calculated costs       │
│  ☐ 5. Submit for approval           │
│                                     │
│  ┌─────────┐  ┌─────────────────┐   │
│  │ Close   │  │ Start Planning  │   │
│  └─────────┘  └─────────────────┘   │
│                                     │
└─────────────────────────────────────┘

Implementation

1. Create a Popup widget with header enabled
2. Add text widgets with step instructions
3. Add navigation buttons
4. Trigger popup from "Guide Me!" button:

// onClick of btn_guide_me
Popup_Guide.open();

Dynamic Step Highlighting (Advanced)

// Track current step in global variable
// GlobalVar_currentStep (Integer)

function highlightCurrentStep() {
    // Reset all step indicators
    txt_step1.setStyle("opacity", "0.5");
    txt_step2.setStyle("opacity", "0.5");
    txt_step3.setStyle("opacity", "0.5");
    
    // Highlight current step
    switch (GlobalVar_currentStep) {
        case 1:
            txt_step1.setStyle("opacity", "1.0");
            break;
        case 2:
            txt_step2.setStyle("opacity", "1.0");
            break;
        case 3:
            txt_step3.setStyle("opacity", "1.0");
            break;
    }
}

---

Button Design Guidelines

Use color coding to make button functions immediately clear to users.

Color Conventions

Color	Usage	Examples
Green	Positive/Confirm actions	Save, Submit, Approve, Publish
Red	Negative/Destructive actions	Delete, Reject, Revert, Cancel
Blue	Navigation/Neutral actions	Next, Back, View, Export
Gray	Secondary/Disabled actions	Reset, Clear, Close

Button Layout Example

┌─────────────────────────────────────────────┐
│  ACTION BUTTONS                             │
│                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ 🔴 Reset │  │ 🔵 Export │  │ 🟢 Save  │  │
│  └──────────┘  └──────────┘  └──────────┘  │
│                                             │
└─────────────────────────────────────────────┘

Implementation Tips

1. Use consistent button sizing across the application
2. Group related buttons together
3. Place primary action (usually green) on the right
4. Add confirmation dialogs for destructive actions:

// onClick of btn_delete
var confirmed = Application.showConfirmDialog(
    "Confirm Delete",
    "Are you sure you want to delete this version?",
    "Delete",
    "Cancel"
);

if (confirmed) {
    // Perform delete operation
    planning.getPrivateVersion("draft").delete();
}

---

Summary

Best Practice	Key Takeaway
Entry Point	Single overview page with KPIs and organized navigation
Multi-Story	Separate stories per planning phase, stored in folders
Navigation	Use scripting with NavigationUtils.openStory()
User Assistance	Consistent sidebar with filters, instructions, links
Guided Process	"Guide Me!" popup with step-by-step workflow
Buttons	Color-coded: Green=positive, Red=negative, Blue=neutral

---

License: GPL-3.0
Last Updated: 2025-11-22
Repository: https://github.com/secondsky/sap-skills