CODEA File Opening - Sharedo Widgets (POC)

Proof of Concept widgets for automating the CODEA Matter onboarding workflow in Sharedo

Overview

This repository contains Sharedo widgets that automate tab navigation and workflow management for the CODEA Matter File Opening process. The primary widget, TabToPhase, automatically navigates users to the correct tab based on the current work item phase, eliminating manual navigation and improving workflow efficiency.

Key Features

• Automatic Phase-Based Navigation: Opens the correct tab when loading a work item
• Real-Time Phase Monitoring: Polls the Sharedo API every 5 seconds to detect phase changes
• Intelligent Redirect: Automatically redirects to the appropriate tab when phase changes
• Backend-Driven: Uses Sharedo API as the source of truth for phase data
• Configurable Mappings: Easy-to-configure phase-to-tab mappings
• Session-Aware: Respects user manual navigation while maintaining automation

Repository Structure

TabToPhase/
├── README.md                           # This file - main entry point
├── claude.md                           # Comprehensive project guide and learnings
│
├── Widget Files (Runtime)
├── TabToPhase.js                       # Main widget logic (1400+ lines)
├── TabToPhase.html                     # Widget template
├── TabToPhase.css                      # Widget styles
├── TabToPhase.widget.json              # Widget manifest
├── TabToPhaseMenu.html                 # Widget menu template
│
├── Designer Files
├── designer/
│   ├── TabToPhaseDesigner.js           # Designer widget
│   ├── TabToPhaseDesigner.html         # Designer template
│   ├── TabToPhaseDesigner.css          # Designer styles
│   └── TabToPhaseDesigner.widget.json  # Designer manifest
│
├── Configuration
├── phase-page-mapping.json             # Phase-to-tab mapping configuration
│
└── Documentation
    ├── USAGE.md                        # Quick start and usage guide
    ├── IMPLEMENTATION-SUMMARY.md       # Technical implementation details
    ├── PHASE-MONITORING-GUIDE.md       # Phase monitoring documentation
    ├── PHASE-WORKFLOW.md               # Matter workflow documentation
    ├── DETECTION-METHODS.md            # Phase detection reference
    ├── URL-NAVIGATION.md               # URL navigation details
    ├── URL-NAVIGATION-QUICK-REF.md     # Quick reference for URLs
    ├── TROUBLESHOOTING.md              # Common issues and solutions
    └── READY-FOR-TESTING.md            # Testing checklist

Quick Start

Installation

1. Deploy to Sharedo IDE:

   • Upload all TabToPhase.* files to Sharedo IDE
   • Upload the designer/ folder for configuration UI

2. Add to Blade:

   • Add Prototypes.TabToPhase widget to your matter details blade
   • Configure phase-to-tab mappings (or use defaults)

3. Configure Phase Mappings:

   {
     "phasePageMapping": {
       "Draft": "draft",
       "Client": "client",
       "Partner Review": "partner review",
       "Accounts Review": "accounts review",
       "Approved": "approved"
     },
     "enablePhasePolling": true,
     "pollingInterval": 5000
   }

Basic Usage

Once installed, the widget works automatically:

1. Open a work item → Widget detects phase and navigates to correct tab
2. Phase changes → Widget detects change via API and redirects to new tab
3. Manual navigation → Widget respects your choice and doesn't override

CODEA Matter Workflow

The widget supports the complete CODEA Matter onboarding workflow:

Draft → Client → Matter Details → Conflicts and Review →
  Provisioning → Partner Review → Accounts Review → Approved

Alternative paths:

• Skip Matter Details: Draft → Client → Conflicts and Review
• Provisioning Error: Provisioning → Provisioning Error → Provisioning
• Deletion: Any phase → Deleted

See PHASE-WORKFLOW.md for detailed workflow documentation.

How It Works

On Page Load

1. Widget detects work item ID from $ui.pageContext.sharedoId()
2. Fetches current phase from API: /api/v1/public/workItem/{id}/phase
3. Maps phase to tab name using configuration
4. Redirects to correct tab if on default page

During Monitoring

1. Polls phase API every 5 seconds
2. Compares API phase with local cached phase
3. When phase changes:
   • Updates local phase
   • Builds target URL for new phase tab
   • Immediately redirects to new URL

Phase Detection

• Source of Truth: Sharedo API (/api/v1/public/workItem/{id}/phase)
• Response: { systemName, name, iconClass, isOpen, availableTransitions }
• System Name: kebab-case identifier (e.g., cod-file-opening-plan-partner-review)
• Display Name: User-friendly name (e.g., Partner Review)

See DETECTION-METHODS.md for technical details.

Configuration

Minimal Configuration

{
  "debug": true
}

Widget auto-detects work item ID and phase from page context.

Full Configuration

{
  "workItemId": "{{workItemId}}",
  "currentPhase": "{{phaseSystemName}}",

  "phasePageMapping": {
    "Draft": "draft",
    "Client": "client",
    "Matter Details": "matter details",
    "Conflicts and Review": "conflicts and review",
    "Provisioning": "provisioning",
    "Provisioning Error": "provisioning error",
    "Partner Review": "partner review",
    "Accounts Review": "accounts review",
    "Approved": "approved",
    "Deleted": "deleted"
  },

  "defaultPage": "draft",
  "enablePhasePolling": true,
  "pollingInterval": 5000,
  "debug": false
}

See phase-page-mapping.json for complete mapping structure.

API Reference

Sharedo API Endpoint

GET /api/v1/public/workItem/{workItemId}/phase

Response:

{
  "systemName": "cod-file-opening-plan-partner-review",
  "name": "Partner Review",
  "iconClass": "fa-user-check",
  "isOpen": false,
  "isRemoved": false,
  "isStart": false,
  "availableTransitions": [
    {
      "systemName": "cod-file-opening-plan-partner-review-to-accounts-review",
      "toPhaseSystemName": "cod-file-opening-plan-accounts-review",
      "name": "Approve",
      "isOptimumPath": true,
      "isUserDriven": true
    }
  ]
}

Sharedo Observables

// Get work item ID
var workItemId = $ui.pageContext.sharedoId();

// Get current phase
var phase = $ui.pageContext.sharedoPhase();

// Check if observable
var value = ko.isObservable(property) ? property() : property;

URL Navigation

https://domain/sharedo/{workItemId}                  # Default page
https://domain/sharedo/{workItemId}/partner%20review # Specific tab

See URL-NAVIGATION.md for details.

Documentation

Getting Started

• USAGE.md - Quick start guide and basic usage
• READY-FOR-TESTING.md - Testing checklist

Technical Documentation

• claude.md - Comprehensive project guide (recommended reading)
• IMPLEMENTATION-SUMMARY.md - Technical implementation
• PHASE-MONITORING-GUIDE.md - Phase monitoring system
• DETECTION-METHODS.md - Phase detection methods

Workflow & Configuration

• PHASE-WORKFLOW.md - CODEA Matter workflow
• URL-NAVIGATION.md - URL-based navigation
• URL-NAVIGATION-QUICK-REF.md - Quick reference

Support

• TROUBLESHOOTING.md - Common issues and solutions

Key Technical Concepts

Sharedo Widget Architecture

• Uses KnockoutJS for data binding
• Follows Sharedo widget patterns (namespace, lifecycle methods)
• Implements loadAndBind() and onDestroy() lifecycle hooks

API Integration

• Uses $ajax wrapper (not $.ajax) for authenticated requests
• Promise-based API calls (.then(), .catch(), .always())
• Proper error handling and retry logic

Observable Pattern

// Create observables
self.model = {
  currentPhase: ko.observable(''),
  isMonitoring: ko.observable(false)
};

// Access observables
var phase = self.model.currentPhase();      // Get
self.model.currentPhase('NewPhase');        // Set

Resource Management

• Stores timer IDs for cleanup
• Unsubscribes from events in onDestroy()
• Clears intervals and timeouts properly

Testing Checklist

• Widget deployed to Sharedo IDE
• Work item ID detected correctly
• Phase detected from API
• Tab navigation works for all phases
• Phase monitoring starts automatically
• Phase changes detected within 5 seconds
• Redirects to correct tab on phase change
• Manual tab navigation respected
• Widget cleanup on destroy

See READY-FOR-TESTING.md for comprehensive testing guide.

Browser Console Debugging

Check Sharedo Context

// View page context
console.log('Work Item ID:', $ui.pageContext.sharedoId());
console.log('Phase:', $ui.pageContext.sharedoPhase());

Test API Manually

$ajax.get('/api/v1/public/workItem/12345/phase').then(function(data) {
  console.log('Phase:', data.systemName);
  console.log('Display Name:', data.name);
});

Enable Debug Mode

Add to widget configuration:

{ "debug": true }

Known Issues & Limitations

Current Behavior

• Immediate Redirect: Phase changes trigger immediate redirect (no notification)
• Unsaved Data: Redirects may occur while user has unsaved form data
• Polling Only: No webhook/push notification support

Potential Enhancements

• Add confirmation dialog before redirect with unsaved changes
• Implement smart polling (reduce frequency when inactive)
• Add visual notification before redirect
• Support for phase transition validation
• Configurable tab visibility based on phase

See TROUBLESHOOTING.md for solutions to common issues.

Development

Prerequisites

• Sharedo platform access
• IDE access for widget deployment
• Node.js (for local development/testing)
• Git

Coding Standards

• Follow Sharedo widget patterns
• Use $ajax for API calls (not $.ajax)
• Always check ko.isObservable() before accessing
• Clean up resources in onDestroy()
• Comprehensive logging with emoji icons
• Structured error handling

See claude.md section "Sharedo Widget Coding Rules" for detailed standards.

Contributing

This is a proof of concept project. Contributions are welcome:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly in Sharedo environment
5. Submit a pull request

License

Copyright © 2026 Alterspective IO

This is a proof of concept project. License terms to be determined.

Credits

Project: CODEA Matter File Opening Automation Platform: Sharedo Framework: KnockoutJS Created: January 2026 Organization: Alterspective IO

Support

For issues, questions, or feature requests:

• Create an issue in this repository
• Refer to TROUBLESHOOTING.md
• Check claude.md for comprehensive documentation

---

Note: This is a proof of concept widget developed for the CODEA Matter onboarding workflow. It demonstrates automated phase-based navigation and workflow management in Sharedo.