Valence — IBM i Modernization & AI

Quick Start

Valence Tools connects VS Code to your Valence server, giving you full access to your NAB applications, AI-assisted development, legacy code conversion, and automated regression testing — all in one place.

Connection & Server

The connection manager lives at the top of the Valence sidebar. It stores multiple server profiles and handles authentication, including two-factor verification.

Adding a Connection

1. Click + Add in the connection manager, or run Valence: Add Connection from the Command Palette.
2. Enter a name, server URL, and username.
3. Your password is requested when you connect and stored securely in your operating system's credential manager.

Connecting & Switching

Click Connect on any saved connection card. If your server uses two-factor authentication, you will be prompted for a code after entering your password.

To switch servers, click the Switch button (arrow-swap icon) in the connected toolbar, or run Valence: Switch Connection.

Connected Toolbar

When connected, the toolbar provides quick actions:

Auto-Connect

Enable Auto Connect in settings to automatically reconnect to your last active server when VS Code starts. The extension validates your session silently — no prompts appear unless re-authentication is needed.

Server Version & Feature Availability

Some features need a newer Valence server. If you connect to an instance older than 6.4.20260623, the features listed below won't be available until your Valence server is upgraded. Everyday work — browsing apps, viewing SQL, and the App Map — works on any supported server.

Browsing & Exploring

Once connected, the sidebar shows your NAB applications and data sources in navigable tree views.

NAB Applications Tree

Applications are organized by category. Expand any app to see its full structure:

• Widgets — Grids, forms, charts, KPIs, maps, and more. Expand a widget to inspect its data source, editable fields, columns, properties, and tabs.
• Popups — App-level popup widgets.
• Variables — App variables with default values, expression indicators, and backend-pass flags.
• Listeners — Event listeners with public/private status.
• RPG Calls — Backend program calls with source locations and prompt fields.

Supported widget types include Grid, Edit Grid, Form, Chart (Bar, Column, Pie, Line, Area, Gauge), Tree, Timeline, Tiles, Calendar, Pivot Grid, Map, Single KPI, Tab Container, Vertical Container, and Data Chat.

App Right-Click Actions

Right-click any app in the NAB Applications tree for quick actions:

• Launch App — Open the live, running application in your browser (when the server supports deep links).
• Update App with AI — Open AI Chat in Update App mode with the app loaded (see AI Commands).
• Open App Map — Open the visual structure-and-flow map (see App Map).
• Compare with Environment — Structural diff of the app against the same app on another Valence server: what was added, removed, or changed across widgets, popups, variables, listeners, RPG calls, and section order. Great for verifying a dev→prod promotion. (For a behavioral + visual comparison that actually runs the app, use Regression Testing → "Compare against another connection".)
• Regression Test — Run structural / visual tests (see Regression Testing).
• Copy / Save App Structure — Export the full app structure as JSON, or add it to AI Chat as context.

Widget Label Mode

Click the Tag icon in the NAB Applications toolbar to toggle between:

• In-App Name — The name the developer gave the widget inside the app (falls back to the component name if not set)
• Component Name — The widget's underlying NAB component name

Search & Filter

Click the Search icon or run Valence: Search Apps to filter by name or ID. Use Filter by Tag to narrow by app tags. Both trees (Applications and Data Sources) support independent search and tag filtering.

Data Sources & Widgets Panel

The Data Sources panel lists all data sources on the server. Expand any data source to see which widgets use it. Right-click to open in the NAB Editor or view/copy the SQL.

SQL Viewer

Right-click any widget's data source and select View SQL to open the full SQL statement in a formatted, syntax-highlighted read-only tab.

App Map & Analysis

The App Map provides a visual overview of an application's structure, user flows, and internal dependencies in a dedicated editor tab.

Visual Layout

The map displays sections in authored order, each containing widget cards that show type, name, ID, data source info, column/field counts, and interactions. Tab containers render with nested tab groups. Click any widget card to open it in the NAB Editor.

Flow Visualization

App Map discovers user flows by traversing action chains — widget clicks, buttons, listeners, and startup programs — and renders them as interactive flowcharts. Click any node in the diagram to navigate to that widget.

Analysis Tools

• Dead Asset Detection — Finds unreachable sections, orphan widgets, and unused listeners.
• Heatmap — Colors widget cards by activity level, highlighting the busiest parts of your application.
• Impact Analysis — Shows per-variable and per-widget impact data to assess the blast radius of changes.
• Variable Index — Lists every variable with its writers, readers, and SQL references.
• Reverse Trace — Traces where data comes from for any widget or variable.
• RPG Dependency Map — Groups RPG calls by program and action for a backend dependency view.

App Map Chat

Ask questions about the application directly within the App Map panel. The assistant has full context about the app's structure, flows, and variables.

AI Chat

The AI Chat panel is your assistant for code questions, app planning, legacy conversion, and documentation generation. It appears in the sidebar after connecting to a Valence server that supports it.

Asking Questions

Type any question and press Enter. The assistant handles general code questions (SQL, RPG, TypeScript, JavaScript), IBM i topics, application structure analysis, and suggestions for improvements.

Referencing Files with @

Type @ in the chat input to see files open in your editor. Select one or more to attach them — the assistant reads their full contents and can suggest changes. Referenced files appear as tags below the input.

Attaching Images

Attach screenshots, diagrams, or mockups for the assistant to analyze alongside your question.

Code Lens Actions

When you open IBM i source files, clickable actions appear at the top of the file. The same actions are available by right-clicking the file and choosing the Valence submenu. Each one opens AI Chat with the file attached and the matching mode already selected — you just add any details and send.

Choosing a Mode

A mode menu sits at the bottom-left of the chat input. It tells the assistant what you're working on. There are two base modes, plus task-specific modes that appear when they apply.

• NAB Agent (default) — Full NAB capabilities: search and inspect applications, create widgets and data sources, and build complete apps. Use this for anything involving NAB.
• Agent — General IBM i, RPG, and SQL help with no NAB tooling. Use this for plain work — "add a procedure to this RPG", "what tables relate to customers?", "write a SQL join" — so answers aren't framed around NAB.

The menu also lists task modes — Plan, Convert to NAB, Update App, and Document — when your current context supports them (for example, Convert to NAB unlocks once a DSPF and an RPG file are attached). Selecting one is equivalent to typing its slash command; if you prefer typing, the slash commands still work. The NAB task modes are hidden while you're in plain Agent mode.

Think Harder

Beside the mode menu is a Think Harder toggle (the sparkle icon). Turn it on for genuinely hard tasks — intricate business logic, a tricky conversion, a delicate code edit — and the assistant puts in extra effort, reasoning the problem through more carefully before it answers. It trades a little speed for more thorough work, so for everyday questions and quick edits you can leave it off.

It applies to the current chat only and stays on until you switch it off — starting a New Chat resets it. The toggle appears only when it can actually make a difference (any task mode, or plain Agent once you've attached a file to work on) and lights up while it's active.

Which Mode Should I Use?

Reach for the mode that matches your goal. When in doubt, stay in NAB Agent and just ask — it handles most things and will guide you.

Rule of thumb: Plan builds something new, Convert to NAB migrates a green screen, Update App edits a live app, and Document describes code. Everything else — questions, one-off edits, exploration — is just NAB Agent or Agent.

When a task needs more than one table to choose from, the assistant shows quick selection cards so you can pick the right one (or Not needed — skip a category you don't want). Data sources are always shown for your approval before they're created.

Transparency & What's Sent

Nothing is sent unless you actively use the chat. When you do, a file's contents are included only when you attach it yourself with @ (or select code and choose Ask AI about this file) — the extension never reads or sends files you haven't referenced, and never scans your workspace on its own. The assistant may also fetch supporting details it needs for a task — such as a table's schema or server-side source — from your connected Valence server.

Click the Log in the chat header to see exactly what data was sent to the AI — your messages, prefetched context, tool calls and results, and assistant responses.

AI Commands

Dedicated AI workflows. Pick one from the mode menu at the bottom-left of the chat input, or type the matching slash command directly — both do the same thing.

/plan — Design a New App

Design a new NAB application from a natural language description. Best for larger apps with multiple widgets and data sources where you want to review a structured blueprint before building. The plan is a starting point to review and refine — tweak it in chat until it's right, then build.

How to Use

1. Open AI Chat (NAB Agent mode is selected by default)
2. Choose Plan from the mode menu (or type /plan) followed by a description of the app you want to build
3. The assistant researches your database, checks for reusable data sources, and generates a complete plan
4. The plan opens in a dedicated tab with Build Plan and Discard Plan buttons
5. Request revisions in the chat — the plan tab updates in place
6. Click Build Plan to create all data sources, widgets, and the app automatically

/document — Generate Documentation

Generate structured technical documentation from any source files you have open. Works with RPG, SQLRPGLE, DSPF, CL, SQL, TypeScript, and more. The output is a strong first draft to review and refine — the AI describes what the source makes clear, so add any business context it couldn't infer.

How to Use

1. Open the source file(s) in VS Code
2. Open AI Chat and type @ to reference the file(s) (up to 6)
3. Type /document and send
4. A styled preview opens in a new tab with a theme switcher and Save as PDF button

Themes & Branding

Six built-in themes: Professional, Modern, Classic, Corporate, Technical, and Light. The Custom theme derives a full color palette from a single hex color you provide. Configure a logo and footer text in Settings for branded documentation.

/convertToNAB — Legacy App ConversionBeta

Convert a DSPF display file and RPG program into a modern NAB web application. Preserves master-detail relationships, row selection behavior, navigation patterns, and field-level logic.

A jump-start, not a one-click finish. Convert to NAB does the tedious structural work for you — building the data sources, widgets, master-detail wiring, and navigation from your DSPF/RPG — to get you roughly 80% of the way there in minutes instead of days. Treat the result as a strong first draft to review and refine, not a finished app. The more straightforward the screen, the closer to done; complex programs need more polish. It exists to save you the manual build, not to replace your judgment.

What You Need

• The DSPF source file defining the legacy screen layout
• The RPG source file driving the business logic
• Optionally, a service RPG program for Save/Delete/Add operations

How to Use

1. Open your DSPF and RPG source files in VS Code
2. Open AI Chat (NAB Agent mode is selected automatically)
3. Attach both files with @, choose Convert to NAB from the mode menu (or type /convertToNAB), and send
4. Optionally provide a service RPG program when prompted
5. Review the conversion plan in a dedicated tab
6. Each data source is presented for individual approval
7. Click Build Plan to create the complete NAB application

Reviewing AI-Suggested Changes

When the AI suggests code changes, they appear in a Proposed Changes tab with a unified diff view. Each change block has its own Accept and Reject buttons, and the toolbar provides Apply All and Dismiss All for the entire file.

Regression Testing

Automated testing for NAB applications with structural validation, interaction testing, and visual screenshot comparison across environments.

Single-App Test

Right-click any app in the NAB Applications tree and select Regression Test. Choose:

• This connection only — Validates the app loads, checks its structure, and exercises interactions.
• Compare against another connection — Tests on both servers and compares results side by side.

What Gets Checked

Visual Comparison

Full-page screenshots are taken at key points and compared pixel-by-pixel. Differences are classified as Match (<0.5%), Minor (0.5–15%), or Significant (>15%).

Test Modes

• Safe only — Exercises filters, section navigation, show/hide. Skips RPG program calls.
• Include RPG calls — Exercises all interactions including backend RPG triggers.

Test Suites

Batch-test multiple apps together. Create a suite from the Test Suites panel, select a target connection and apps, then run in headless or watch mode. The batch report shows pass/fail status, visual diff summaries, and per-app duration.

Glossary

Keyboard Shortcuts

Settings

Open VS Code Settings and search for Valence to configure the extension.

Help & Support

Have a question or hit a problem? Reach the Valence team and community through the VS Code Extension forums. Links open in your browser.