IBM Project4i
Logical Project Management for IBM i
Organize source members and IFS stream files from multiple libraries into cohesive, team-friendly project groups — directly inside VS Code.
Why IBM Project4i?
Traditional IBM i development ties application logic to physical library structures.
IBM Project4i introduces a logical project layer on top of Code for IBM i, letting you:
- Group related sources from any library into a single project view.
- Track the original location of each member (audit trail).
- Run customizable CL commands for checkout, promote, release and custom actions.
- Share project definitions across team members via the IBM i IFS.
- Attach documentation (URLs, PDF, Word, Excel) directly to the project.
- Import / Export full configuration snapshots as JSON.
Think of it as a lightweight, IBM i–native SCM bridge — built for developers who live in VS Code.
Table of Contents
Features at a Glance
| Area |
Capability |
| Developer Kanban Board |
Manage project members visually through Dev → Ready → Test → Done lifecycle stages. Track Test Passed / Failed items instantly. |
| Activity Log |
Complete, filterable audit trail for every action (promotes, member changes, renames, state updates). Syncs across teams via IFS. |
| Project Tree View |
Dedicated Activity Bar panel with rich icons — projects (purple), members (color-coded by type), stream files (yellow), documentation (blue). |
| Hybrid Content |
Mix native source members (QSYS) and IFS stream files in the same project. |
| Shared Projects |
Store project metadata and activity logs on the IFS — multiple developers share the same project and audit trails in real time. |
| Contributor Permissions |
16 granular permission flags per contributor — owner controls exactly what each team member can do. |
| Shared Project Browser |
Unified webview panel listing all local, shared, and archived projects across connections with rich table UI, filters, and one-click actions. |
| Archive / Remove |
Archive a project (read-only) or remove it from your workspace without deleting team data. |
| Copy Project As New |
Duplicate any active project (local or shared) from the workspace tree — copies members, config, actions, and permissions. |
| Re-open / Copy Archived |
Restore archived projects via the Project Browser — re-open in place or create a new copy with selective member checkout. |
| Member Locking |
Pessimistic lock system — members track the IBM i user editing them (checkedOutBy), disabling concurrent edits. Run/Promote actions are fully usable on locked items. |
| Force Unlock |
Project owner can force-release a lock held by another user. |
| Conflict Detection |
Cross-project conflict flagging — members present in more than one project are flagged ⚠ and blocked from promotion until resolved. |
| Orphaned Member Detection |
Automatic health check verifies all members still exist on IBM i; orphaned references are marked with a warning icon. |
| Documentation Hub |
Virtual "📚 Documentation" folder per project — add external URLs and local files (PDF, Word, Excel). |
| Add to Project |
Smart checkout: copies a member from a source library to the project's workspace library, with configurable CL override and conflict detection. |
| Remove from Project |
Logical removal with optional physical delete (RMVM), or custom CL release command. |
| Promote Member |
Deploy a single member using a fully customizable CL command template. Blocked for conflicted members. |
| Promote All Members |
Batch deploy all project members sequentially, with Run / Skip / Run All / Cancel All controls. Conflicted members auto-skipped. |
| Promote IFS Stream File |
Deploy IFS files with a dedicated CL template and IFS-specific variables. |
| Move Member |
Atomic move of a member between two projects, with pre-flight validation. |
| Create Member |
Create a new source member directly inside a project's workspace library. |
| Rename Member |
Rename a member in-place. |
| Browse (Read-Only) |
Open a member in read-only mode for review. |
| Run Action |
Proxy to Code for IBM i's action system — compile, bind, etc. directly from the project tree. |
| Run Project Action |
Execute project-specific custom CL actions with full variable substitution. |
| CL Interactive Prompting |
Prefix any command with ? to open a visual CL parameter form before execution. |
| Default Settings |
Global configuration panel — set defaults for libraries, developer info, workflow commands, and custom actions that seed every new project. |
| Require Ticket ID |
Enforce a Ticket / Change Reason before promoting, ensuring audit compliance. |
| Two-Column Settings UI |
VS Code Settings–style panels with left sidebar navigation, category headers, and spacious per-command editing panes. |
| Multi-Connection Support |
Per-server project storage — each IBM i connection has its own project namespace with automatic migration. |
| Project Chronicle |
Chronological log of lifecycle events (created, archived, reopened, copied) with user and timestamp. |
| Getting Started Walkthrough |
Built-in 6-step wizard that opens on startup (optionally) to guide new users. Dismiss with a single click. |
| Import / Export |
Full configuration snapshots (projects + global settings) as JSON. |
| VS Code Theming |
Full support for Dark and Light themes with custom SVG icons. |
Getting Started
Prerequisites
| Requirement |
Version |
| Visual Studio Code |
≥ 1.85.0 |
| Code for IBM i |
Latest |
| Active IBM i connection |
— |
Quick Start (5 minutes)
- Install the extension from the VS Code Marketplace (or side-load the
.vsix).
- Connect to your IBM i system via Code for IBM i.
- Create a project — click the
+ button in the IBM Project4i Activity Bar.
- Add a member — right-click a source member in the Object Browser → "Add to Project".
- Configure deploy — open project Properties (⚙️) and set the Promote Command template.
That's it. You now have a fully functioning project workspace.
Project Lifecycle
| Action |
How |
Description |
| Create |
+ button or Command Palette |
Provide a name, optional description, and target library. |
| Rename |
Right-click → Rename Project |
Change the display name. |
| Copy as New |
Right-click → Copy as New Project |
Duplicate the project with all members, config, and permissions. |
| Archive |
Right-click → Archive Project |
Lock the project read-only with a reason (Deployed / Obsolete). Snapshots in-progress edits. |
| Remove from Workspace |
Right-click → Remove from Workspace |
Hide the project from your view without deleting shared data. |
| Delete |
Right-click → Delete Project |
Permanently remove the project and all its metadata. |
| Re-open |
Project Browser → Re-open |
Restore an archived project to active state with selective member checkout. |
| Copy Archived |
Project Browser → Copy |
Create a new project from an archived one, selecting which members to include. |
Project Chronicle
Every lifecycle event is recorded in a chronological log attached to the project:
| Event |
Tracked Data |
| Created |
User, date |
| Archived |
User, date, reason (Deployed / Obsolete), snapshot of locked members |
| Re-opened |
User, date, number of members re-added |
| Copied |
User, date, source project name, members selected |
| Removed |
User, date |
Member & Stream File Management
Adding Members
- From Object Browser: Right-click any member → Add to Project → select the target project. The member is copied (via
CPYSRCF or your custom checkout command) to the project's workspace library.
- From IFS Browser: Right-click any stream file → Add to Project. IFS files are referenced by path (no physical copy).
Creating Members
Right-click a project → Create New Member to create a new source member directly inside that project's workspace library.
Opening Members
- Double-click a member in the tree to open it in the editor.
- Browse (Read-Only): Right-click → Browse for a non-editable preview.
Moving Members
Right-click a member → Move to Project… to atomically transfer it to another project (pre-flight validation ensures no conflicts).
Removing Members
- Right-click → Remove from Project: removes the tracking reference. Optionally runs
RMVM or your custom release command.
- IFS stream files: removes the reference only (no physical delete).
Member Locking
IBM Project4i implements a pessimistic lock system to prevent concurrent edits on the same member in shared projects.
How It Works
| Concept |
Description |
| Check Out |
When a member is opened for editing, it is locked to the current IBM i user (checkedOutBy field). |
| Lock Indicator |
Locked members display a 🔒 icon with the lock owner's username in the tree view. |
| Session Tracking |
Each VS Code window has a unique session ID — locks are tracked per session and auto-released on window deactivation. |
| Release Lock |
Right-click a locked member → Release Lock to manually unlock it. The member file must be closed first. |
| Force Unlock |
Project owner only — right-click a member locked by someone else → Force Unlock to break the lock. A warning is shown about potential data loss. |
Tree View Indicators
| State |
Icon |
Badge |
contextValue |
| Normal |
Color-coded by type |
M |
member |
| Locked (your lock) |
🔒 Lock (red) |
🔒 |
memberLocked |
| Locked (owner view) |
🔒 Lock (red) |
🔒 |
memberLockedOwner |
| Missing / Orphaned |
❌ Error (red) |
! |
memberMissing |
| In Conflict |
⚠️ Warning (yellow) |
⚠ |
memberConflict |
Conflict Detection & Resolution
When adding a member to a project, IBM Project4i checks whether that member already exists in another project. If a cross-project conflict is detected, the member is flagged as In Conflict — a soft lock that blocks deployment but does not prevent adding.
Conflict Flow
- Add Member →
findMemberInOtherProjects() detects the member in another project.
- A modal warning informs the user: "Member 'X' is already managed by project 'Y'. The member will be flagged as In Conflict."
- User can Proceed Anyway (member is added with
inConflict: true) or Cancel.
- The member appears in the tree with a ⚠️ warning icon and yellow badge.
- Promote is blocked — both single and batch promote skip conflicted members.
- Resolve Conflict — right-click the conflicted member → Resolve Conflict to clear the flag and re-enable promotion.
Conflict Detection Points
Conflict detection runs automatically when:
- Adding a member to a project (from Object Browser)
- Re-opening an archived project (per-member pre-flight check)
- Copying an archived project (per-member pre-flight check)
- Copying an active project as new (
copyProjectAsNew)
Permissions
The Resolve Conflict action requires the canResolveConflicts permission (default: false). Project owners always have this permission.
Orphaned Member Management
Members can become orphaned when their physical source is deleted from IBM i while the project reference remains.
Health Check
An automatic health check runs:
- On IBM i connection established (with 3-second delay)
- After syncing a shared project from IFS
- On manual tree refresh
The check uses batch SQL queries (grouped by library/file) for efficiency. Orphaned members are immediately flagged in the tree view with a ❌ icon and ! badge.
Cleanup
| Action |
How |
| Remove Single |
Right-click an orphaned member → Remove from Project |
| Remove All |
Toolbar → Remove All Orphaned Members — bulk removes all orphaned references across all non-archived projects |
Clicking an orphaned member shows an informative message with the last known location instead of attempting to open it.
Copy Project As New
Duplicate any active (non-archived) project directly from the workspace tree — available for both local and shared projects.
What Gets Copied
| Item |
Copied? |
| Member references |
✅ (reference only — no physical copy) |
| Stream file references |
✅ |
| Documentation entries |
✅ (with new unique IDs) |
| Promote configuration |
✅ |
| Custom actions |
✅ |
| Contributor permissions |
✅ |
| Project type (local/shared) |
✅ (shared projects created on IFS) |
How To Use
- Right-click any project in the tree → Copy as New Project (or use the inline 📋 copy icon).
- Enter a unique name for the new project.
- The new project is created with all references and configuration from the source.
Note: Members that exist in other projects are automatically flagged as In Conflict in the new copy.
Workflow Commands
Each workflow step can be customized with a CL command template. Templates support variable substitution (see Variable Reference).
Deploys a single member (or all members in batch) from the workspace to test/production.
CALL PGM(MYUTILS/PROMOTE) PARM('&OBJECT_NAME' '&TEST_LIB_SRC' '&TICKET_REASON')
Checkout / Add-to-Project Command
Overrides the built-in CPYSRCF logic when adding a member to a project.
CPYSRCF FROMFILE(&SRC_LIB/&SRC_FILE) TOFILE(&TGT_LIB/&TGT_FILE) FROMMBR(&SRC_MBR) TOMBR(&TGT_MBR) MBROPT(*REPLACE)
Additional variables: &SRC_LIB, &SRC_FILE, &SRC_MBR, &TGT_LIB, &TGT_FILE, &TGT_MBR.
Release / Remove-from-Project Command
Overrides the built-in removal logic.
CALL PGM(MYUTILS/RELEASE) PARM('&TGT_MBR' '&TGT_LIB')
Additional variables: &TGT_MBR, &TGT_LIB, &TGT_FILE.
Dedicated template for deploying IFS stream files.
CALL PGM(MYUTILS/DEPLOYIFS) PARM('&IFS_PATH' '&FILE_NAME')
Additional variables: &IFS_PATH, &FILE_NAME / &OBJECT_NAME, &FILE_EXT / &MEMBER_TYPE.
Tip: Prefix any command with ? to open the CL Interactive Prompter before execution.
Custom Project Actions
Define reusable CL command templates attached to a project. Run them on any member via right-click → Run Project Action….
Actions are configured in the Project Properties panel (⚡ Custom Actions section) and support the full set of variable placeholders.
Default actions can be pre-configured in Manage Default Settings so every new project is seeded with your team's standard commands.
CL Interactive Prompting
Prefix any CL command template with a ? character to invoke the CL Prompter — a visual form that renders each positional / keyword parameter as a labelled field.
?CRTBNDRPG PGM(&TEST_LIB_OBJ/&OBJECT_NAME) SRCFILE(&TEST_LIB_SRC/&TEST_FILE_SRC) SRCMBR(&OBJECT_NAME)
The prompter lets you review and modify parameters before execution, which is especially useful for complex CRTBNDRPG / CRTSQLRPGI calls.
Activity Log & Kanban Board
Activity Log
The Activity Log (accessible via the History icon on any project) provides an enterprise-grade audit trail:
- Tracks
PROJECT_CREATED, PROMOTED, MEMBER_ADDED, state changes, moving files, renames, and errors.
- Displays Time, User, Action Badge, Targeted Object, Flow (
Source -> Target), Status (Success/Failed), and Ticket ID.
- Shared Projects: Stored on the IFS (
activity_log.json) making it available to the entire team in real-time.
Developer Kanban Board
The Developer Kanban Board (accessible from the Activity Bar Toolbar icon) offers a modern UI for lifecycle management natively inside VS Code:
- See all project members in
Dev → Ready → Test → Done visual columns (Swimlanes per logical project).
- One-click transitions (
Mark Ready ▶, ⚡ Promote Now, ✔ Test Passed, ✖ Test Failed).
- Failing a test marks a card as
REWORK and tracks it visibly back to development column.
- Integrated variable resolution for full custom promote commands inside Kanban interactions.
Shared (Team) Projects
Shared projects store their metadata as JSON files on the IBM i IFS, enabling real-time collaboration across team members.
Setup
- Open Manage Default Settings → Shared Projects tab.
- Set the IFS Root Path (e.g.
/home/shared/project4i_data/).
- Create a project — it will automatically be saved to the IFS.
Collaboration
- Open Shared Project Browser: toolbar cloud button in the Activity Bar — browse the IFS folder and join existing projects across all connections, history, and workspace.
- Sync: right-click → Sync Shared Project to pull the latest changes from the IFS.
- Contributors: project owner manages team access via the Permissions tab in Properties.
Security Model
| Role |
Icon |
Can edit |
Can manage contributors |
Can delete/archive |
| Owner |
☁ Cloud (purple) |
✅ |
✅ |
✅ |
| Contributor |
☁ Cloud (purple) |
✅ (per-permission) |
❌ (can leave) |
❌ (unless permitted) |
| Viewer |
👁 Eye (yellow) |
❌ |
❌ |
❌ |
Shared Project Browser
The Shared Project Browser is a unified webview panel accessible from the Activity Bar toolbar. It displays all projects in a rich table interface:
| Source |
Description |
| Local workspace |
Active projects in the current connection's workspace |
| Archived / History |
Projects that were archived or removed from workspace |
| Shared (IFS) |
Projects discovered on the IFS root path |
Features
- Filter by type: Local, Shared, or All
- Search: filter by project name
- Actions per row: Load to Workspace, Re-open, Copy as New, View Properties
- Diagnostic logging: detailed output channel (
Project4i Shared Browser) for troubleshooting
- Fallback handling: gracefully degrades when
iproj.json is unreadable (uses IFS registry entry)
Contributor Permissions
Each contributor in a shared project has individually configurable permissions. The project owner can set these in the Permissions tab of Project Properties.
| Permission |
Default |
Description |
addMember |
✅ |
Add existing members to the project |
createMember |
✅ |
Create new source members |
promoteMember |
✅ |
Promote members to test/production |
runAction |
✅ |
Run custom CL actions |
addDocumentation |
✅ |
Add documentation links/files |
syncProject |
✅ |
Sync shared project from IFS |
removeFromWorkspace |
✅ |
Remove project from local workspace |
openProperties |
❌ |
View/edit project properties |
renameProject |
❌ |
Rename the project |
deleteProject |
❌ |
Delete or archive the project |
removeMember |
❌ |
Remove members from the project |
removeStreamFile |
❌ |
Remove stream file references |
moveMember |
❌ |
Move members between projects |
editDocumentation |
❌ |
Edit or remove documentation entries |
canReopen |
❌ |
Re-open archived projects |
canResolveConflicts |
❌ |
Resolve cross-project member conflicts |
Note: The project Owner always has all permissions regardless of this table.
Default Settings Panel
Manage Default Settings (⚙️ button in the toolbar) opens a two-column webview panel with left sidebar navigation.
| Tab |
Content |
| Developer |
Default AS400 user and email applied to new projects. |
| Ticket / Reason |
Default ticket reference or change reason. |
| Test (under ENVIRONMENTS) |
Test object library, source library, source file. |
| Production (under ENVIRONMENTS) |
Production object library, source library, source file. |
| Shared Projects |
IFS root path for shared project metadata. |
| Promote (under WORKFLOW COMMANDS) |
CL template for promoting members. |
| Checkout / Add (under WORKFLOW COMMANDS) |
CL template for add-to-project checkout. |
| Release / Remove (under WORKFLOW COMMANDS) |
CL template for release/archive. |
| Promote IFS File (under WORKFLOW COMMANDS) |
CL template for IFS stream file promotion. |
| Custom Actions |
Default project action templates seeded into every new project. |
| Variables Reference |
Full table of all available placeholder variables. |
Each Workflow Command tab includes a context-specific mini-reference of the variables valid for that command.
Project Properties Panel
Properties (⚙️ icon on a project) opens a per-project two-column webview.
| Tab |
Content |
| General |
Project name, target library, description. |
| Test (under ENVIRONMENTS) |
Test object library, source library, source file. |
| Production (under ENVIRONMENTS) |
Production object library, source library, source file. |
| Developer |
AS400 user, email. |
| Ticket / Reason |
Ticket number or change reason. |
| Custom Actions |
Project-specific CL action templates. |
| Permissions (shared projects only) |
Owner, contributors list, add/remove access. |
| Variables Reference |
Complete variable documentation. |
A Load Defaults button populates all empty fields from the global defaults.
Documentation Hub
Each project has a virtual 📚 Documentation folder in the tree view. Add references to:
- URLs — opens in the system browser.
- Local files — PDF, Word, Excel, or any other file type — opens with the OS default application.
Manage entries via right-click → Add Documentation… / Edit… / Remove.
Import / Export
Full configuration snapshots include all projects and global settings.
| Action |
How |
| Export |
Toolbar → ☁ Export Configuration Snapshot → choose save location. |
| Import |
Toolbar → ☁ Import Configuration Snapshot → browse a previously exported JSON file. |
Snapshots are portable JSON files that can be versioned in Git or shared via email.
Multi-Connection Support
IBM Project4i supports working with multiple IBM i systems simultaneously.
| Feature |
Description |
| Connection-scoped storage |
Projects are namespaced per IBM i connection name (project4i-projects.{connectionName}). |
| Automatic migration |
Legacy un-namespaced keys are migrated on first use. |
| Connection change events |
The tree view and health check refresh automatically when switching servers. |
| Unified browser |
The Shared Project Browser can display projects from all connections. |
Getting Started Walkthrough
A built-in 6-step walkthrough introduces the extension's key features:
- What is IBM Project4i? — overview and concept.
- Create a Project — hands-on project creation.
- Add IBM i Source Members — adding members and IFS files.
- Promote Source Members — CL template configuration and deployment.
- Collaborate with Shared Projects — IFS-based team sharing.
- Disable Startup Notification — how to suppress the walkthrough on startup.
Startup Behavior
| Setting |
Default |
Description |
project4i.showWalkthroughOnStartup |
true |
Shows a notification with a "Don't show on startup" button on every activation. Set to false to suppress. |
The walkthrough can always be opened manually via the 📖 button in the Activity Bar toolbar.
Extension Commands Reference
Project Management
| Command |
Description |
project4i.createProject |
Create a new project |
project4i.renameProject |
Rename an existing project |
project4i.deleteProject |
Delete a project permanently |
project4i.archiveProject |
Archive a project (read-only lock with reason) |
project4i.removeProject |
Remove project from workspace (non-destructive) |
project4i.copyProjectAsNew |
Copy an active project as a new project |
project4i.openProperties |
Open project properties panel |
project4i.refreshProjects |
Refresh the project tree |
Member Operations
| Command |
Description |
project4i.addMemberToProject |
Add a source member from the Object Browser |
project4i.removeMemberFromProject |
Remove a member from a project |
project4i.openMember |
Open / edit a source member |
project4i.browse |
Open a member in read-only mode |
project4i.createMember |
Create a new source member in the project library |
project4i.renameMember |
Rename a member |
project4i.moveMember |
Move a member to another project |
project4i.memberProperties |
View member properties (origin, add date, etc.) |
Monitoring & Auditing
| Command |
Description |
project4i.viewActivityLog |
Open project Audit Trail |
project4i.openKanbanBoard |
Open Visual Developer Lifecycle |
Member Locking & Conflicts
| Command |
Description |
project4i.releaseMemberLock |
Release your own lock on a member |
project4i.forceUnlock |
Force-release a lock held by another user (owner only) |
project4i.resolveConflict |
Clear the conflict flag on a member |
project4i.removeOrphanedMembers |
Remove all orphaned member references from all projects |
project4i.openMissingMember |
Show details about an orphaned member |
IFS Stream Files
| Command |
Description |
project4i.addStreamFileToProject |
Add an IFS stream file from the IFS Browser |
project4i.removeStreamFileFromProject |
Remove a stream file reference from a project |
project4i.openStreamFile |
Open an IFS stream file in the editor |
Deployment
| Command |
Description |
project4i.promoteMember |
Promote a single member using the CL template |
project4i.promoteProject |
Promote all project members sequentially |
project4i.runAction |
Proxy to Code for IBM i action system (compile, bind) |
project4i.runProjectAction |
Execute a project-specific custom CL action |
Documentation
| Command |
Description |
project4i.addDoc |
Add a URL or local file to the Documentation folder |
project4i.editDoc |
Edit a documentation entry |
project4i.removeDoc |
Remove a documentation entry |
project4i.openDoc |
Open a documentation entry |
Configuration & Sharing
| Command |
Description |
project4i.manageDefaults |
Open the Manage Default Settings panel |
project4i.applyDefaultsToAll |
Push default custom actions to all existing projects |
project4i.exportProjects |
Export full configuration snapshot to JSON |
project4i.importProjects |
Import configuration snapshot from JSON |
project4i.openSharedProject |
Browse and join a shared project from the IFS |
project4i.syncSharedProject |
Sync shared project data from the IFS |
project4i.openWalkthrough |
Open the Getting Started walkthrough |
Variable Reference
All CL command templates support the following placeholder variables:
Standard Variables (all commands)
| Variable |
Description |
&OBJECT_NAME |
Member name |
&MEMBER_TYPE / &TYPE |
Member extension / type |
&TEST_LIB_OBJ |
Test object library |
&TEST_LIB_SRC |
Test source library |
&TEST_FILE_SRC |
Test source file |
&PROD_LIB_OBJ |
Production object library |
&PROD_LIB_SRC |
Production source library |
&PROD_FILE_SRC |
Production source file |
&TICKET_REASON |
Ticket or change reason |
&DEVELOPER_USER |
AS400 developer user |
&DEVELOPER_MAIL |
Developer email address |
Checkout / Add-to-Project Variables
| Variable |
Description |
&SRC_LIB |
Source library |
&SRC_FILE |
Source physical file |
&SRC_MBR |
Source member name |
&TGT_LIB |
Project workspace library |
&TGT_FILE |
Target source file |
&TGT_MBR |
Target member name |
Release / Remove-from-Project Variables
| Variable |
Description |
&TGT_MBR / &OBJECT_NAME |
Member name |
&TGT_LIB |
Project workspace library |
&TGT_FILE |
Source physical file |
IFS Stream File Variables
| Variable |
Description |
&IFS_PATH |
Full absolute IFS path |
&FILE_NAME / &OBJECT_NAME |
Basename without extension |
&FILE_EXT / &MEMBER_TYPE |
Extension without dot |
Extension Settings
Settings are under project4i.* in VS Code (File → Preferences → Settings → IBM Project4i).
| Setting |
Type |
Default |
Description |
project4i.showWalkthroughOnStartup |
boolean |
true |
Show the Getting Started notification on every activation |
project4i.defaults.requireTicketId |
boolean |
false |
Enforce Ticket / Change Reason before promoting |
project4i.defaults.testLibraryObject |
string |
"" |
Default test object library |
project4i.defaults.testLibrarySource |
string |
"" |
Default test source library |
project4i.defaults.testFileSource |
string |
"" |
Default test source file |
project4i.defaults.prodLibraryObject |
string |
"" |
Default production object library |
project4i.defaults.prodLibrarySource |
string |
"" |
Default production source library |
project4i.defaults.prodFileSource |
string |
"" |
Default production source file |
project4i.defaults.developerMail |
string |
"" |
Default developer email |
project4i.defaults.promoteCommand |
string |
"" |
Default promote CL command template |
project4i.defaults.promoteStreamFileCommand |
string |
"" |
Default IFS promote CL template |
project4i.defaultProjectActions |
array |
[] |
Default custom CL actions seeded into new projects |
Tip: Prefix any command template with ? to open the interactive CL parameter prompter before execution.
Note: Additional defaults (checkout command, release command, shared projects root path, ticket reason, developer user) are managed in the Manage Default Settings webview panel and stored in VS Code GlobalState rather than settings.json.
Project Data Model
Projects are stored in VS Code's GlobalState (namespaced per IBM i connection) and persist across sessions.
Project Fields
| Field |
Description |
| name |
Display name |
| description |
Optional description |
| targetLibrary |
IBM i library where members are physically copied |
| type |
local or shared |
| members |
List of source members (see Member Fields below) |
| streamFiles |
IFS stream file paths referenced by the project |
| docs |
Attached documentation entries (URLs, local files) |
| promoteConfig |
Test/production libraries, workflow command templates, developer info, ticket reason |
| customActions |
Project-specific CL command templates |
| owner |
Shared project owner (IBM i user) |
| contributors |
List of authorized IBM i user IDs (shared projects) |
| contributorPermissions |
Per-contributor permission overrides (16 granular flags) |
| ifsPath |
IFS path for shared project metadata |
| isArchived |
Whether the project is archived (read-only) |
| archiveReason |
Reason for archiving (Deployed / Obsolete) |
| archiveDate |
ISO timestamp of when the project was archived |
| archivedEditSnapshot |
Members being edited at the moment of archiving |
| removedFromWorkspace |
Whether the project was removed from workspace (kept as history) |
| lockedBy |
User currently holding the project edit lock (shared projects) |
| readOnly |
Prevents all modifications (set on archive) |
| chronicle |
Chronological log of lifecycle events |
| createdDate / modifiedDate |
ISO timestamps for auditing |
Member Fields
| Field |
Description |
| library |
Library containing the source file |
| file |
Source physical file name |
| name |
Member name (without extension) |
| extension |
Member type (RPGLE, CLLE, etc.) |
| asp |
Optional ASP for iASP environments |
| addedDate |
ISO timestamp when added to the project |
| originalLocation |
Original library/file before copy (audit trail) |
| checkedOutBy |
IBM i user currently editing this member (empty = unlocked) |
| inConflict |
true when the member exists in another project (blocks promote) |
Development
Architecture
src/
├── extension.ts # Activation, walkthrough, command registration
├── code4i.ts # Code for IBM i API integration
├── commands/
│ └── commands.ts # All command handler registrations
├── services/
│ ├── clPrompterService.ts # CL Interactive Prompter (? prefix)
│ ├── connectionManager.ts # IBM i connection utilities & events
│ ├── ifsService.ts # IFS read/write with optimistic locking
│ ├── memberLockService.ts # Pessimistic member lock tracking
│ ├── promoteService.ts # Promote logic and variable substitution
│ └── sharedProjectService.ts # Shared project IFS operations
├── storage/
│ └── projectStorage.ts # Data model, GlobalState persistence, import/export
└── views/
├── projectsTreeProvider.ts # TreeView data provider
├── treeDecorationProvider.ts # File decoration (badges & coloring)
├── projectDefaultsPanel.ts # Manage Default Settings webview
├── projectPropertiesPanel.ts # Project Properties webview
├── commandPrompterPanel.ts # CL Prompter webview panel
└── sharedProjectBrowserPanel.ts # Unified project browser webview
Building
npm install
npm run compile # One-shot compilation
npm run watch # Watch mode
Running in Development
Press F5 to launch the Extension Development Host with the extension loaded.
Packaging
node __build-vsix.js # Compiles + creates .vsix
Known Issues
- Members must be added one at a time from the Object Browser (batch add not yet supported).
- Project sorting is alphabetical only.
- Force Unlock does not notify the user whose lock was broken (no push notification mechanism).
Release Notes
0.2.0
Member Locking & Conflict Resolution
- Pessimistic Member Locking — members track the IBM i user currently editing them (
checkedOutBy); locked members display 🔒 icon with username.
- Release Lock — manually release your own lock on a member (right-click → Release Lock).
- Force Unlock — project owner can force-release locks held by other users.
- MemberLockService — per-session lock tracking with auto-release on window deactivation.
- Cross-Project Conflict Detection — members added to a project that already exist in another project are flagged as In Conflict (⚠️ icon, yellow badge).
- Promote Blocked for Conflicts — both single and batch promote skip conflicted members with clear messaging.
- Resolve Conflict Command — clears the
inConflict flag (permission-gated: canResolveConflicts).
Orphaned Member Management
- Health Check — automatic batch verification of member existence on IBM i (on connect, sync, refresh).
- Remove All Orphaned Members — bulk cleanup of all orphaned references across projects.
- Orphaned Member UX — orphaned members show ❌ icon,
! badge, and a helpful click message.
Project Lifecycle Enhancements
- Copy Project As New — duplicate any active project from the workspace tree (copies members, config, actions, permissions, docs, stream files).
- Re-open / Copy Archived Projects — via the Shared Project Browser with selective member checkout.
- Project Chronicle — chronological audit log of lifecycle events (created, archived, reopened, copied, removed) with user and timestamp.
- Archive with Reason — choose "Deployed" or "Obsolete" when archiving; snapshot of in-progress edits stored.
- Remove from Workspace — separate from archive; keeps the project as a historical record.
Shared Projects & Permissions
- Shared Project Browser — unified webview panel listing all local, shared, and archived projects with rich table UI and filters.
- 16 Granular Contributor Permissions —
addMember, createMember, promoteMember, runAction, addDocumentation, syncProject, removeFromWorkspace, openProperties, renameProject, deleteProject, removeMember, removeStreamFile, moveMember, editDocumentation, canReopen, canResolveConflicts.
- Per-Contributor Permission UI — toggle individual permissions for each contributor in the Properties panel.
- Viewer Role — non-contributors see shared projects as read-only (👁 icon).
Multi-Connection Support
- Connection-Scoped Storage — project data namespaced per IBM i connection.
- Automatic Migration — legacy un-namespaced keys migrated on first use.
- Connection Change Events — tree and health check refresh automatically when switching servers.
Configuration
- Require Ticket ID — new setting (
project4i.defaults.requireTicketId) enforces a Ticket / Change Reason before promoting.
Walkthrough
- 6-Step Getting Started — new step for disabling the startup notification.
- Dismiss Notification — startup notification includes a "Don't show on startup" button.
- English Translation — all walkthrough content translated to English.
0.1.0
- Two-Column Settings UI — both Manage Default Settings and Project Properties now use a VS Code Settings–style two-column layout with left sidebar navigation and category headers.
- Granular sidebar navigation — Environments split into Test / Production; Workflow Commands split into Promote, Checkout, Release, Promote IFS; Ticket / Reason separated into its own tab.
- Per-command mini-reference — each Workflow Command tab shows only the variables valid for that specific command.
- Shared (Team) Projects — store project metadata on the IFS; owner/contributor security model with Permissions tab.
- Archive / Remove from Workspace — archive projects read-only or remove them without deleting shared data.
- Create New Member — create source members directly inside a project's workspace library.
- Rename Member — rename members in-place from the project tree.
- Browse (Read-Only) — open members for review without editing.
- Getting Started Walkthrough — built-in 5-step wizard with configurable startup behavior (
project4i.showWalkthroughOnStartup).
- Promote IFS Stream File — dedicated CL template with IFS-specific variables (
&IFS_PATH, &FILE_NAME, &FILE_EXT).
- Apply Defaults to All — push default custom actions to all existing projects.
- Sync Shared Project — pull latest changes from IFS.
0.0.5
- README updated with comprehensive documentation.
- VSIX packaging fix for restricted group policy environments.
0.0.4
- Promote All Members with Run / Skip / Run All / Cancel All controls.
- Move Member between projects with pre-flight validation.
- Run Project Action with project-specific custom CL actions.
- CL Interactive Prompting: prefix any command with
? for a visual parameter form.
- Custom checkout (
addToProjectCommand) and release (removeFromProjectCommand) command overrides.
- Manage Default Settings panel for global project defaults.
0.0.3
- IFS stream file support: add/open/remove stream files from the IFS Browser.
- Documentation Hub: attach URLs and local files (PDF, Word, Excel) to each project.
- Tree decoration provider for richer icon coloring.
0.0.2
- Promote Member with configurable CL command template and variable substitution.
- Project Properties panel (test/production library configuration, developer info).
- Run Action proxy to Code for IBM i's compile/bind action system.
0.0.1
Initial release:
- Create, rename, and delete logical projects.
- Add/remove source members to projects.
- Context menu integration with Code for IBM i Object Browser.
- Import/export projects as JSON.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
MIT
Acknowledgments
This extension is designed to work alongside the excellent Code for IBM i extension by the Code for i team.
