Epicor Rest Helper for Node (npm) V2.0

Epicor ERP 10
,
20

EpicorRestNode v1.3.0 Release Notes

:rocket: New Features

Session Management Methods

Added comprehensive session management methods to control Epicor session context after establishing a connection.

public async SetEmployee(employeeID: string): Promise<boolean>
public async SetPlant(newSite: string): Promise<boolean>
public async SetWorkstation(newWorkstationID: string): Promise<boolean>
public async SetClientData(
  clientUserName: string,
  clientComputerName: string,
  clientDateFormat?: string,
  appserver?: string,
  clientTerminalID?: number
): Promise<boolean>
public async GetSessionInfo(): Promise<any>
public async GetThemeInfo(): Promise<any>

Important: All session management methods require an active session created with CreateSession(). They will throw an error if called without a valid session.

EFX Staging Retry Flag

Added a new development-only flag to automatically retry Epicor Function calls with the staging endpoint when encountering 404 errors.

EpicorRest.EfxAttemptStagingRetry = true; // Development mode only

Endpoint Pattern:

  • Standard: https://{host}/{instance}/api/v2/efx/{company}/{library}/{function}
  • Staging: https://{host}/{instance}/api/v2/efx/staging/{company}/{library}/{function}

:clipboard: What’s New

Advanced Session Control

  • Employee Context: Switch to a different employee for labor tracking or permissions
  • Plant Management: Change the manufacturing site context for operations
  • Workstation Control: Set the workstation for production or quality operations
  • Client Synchronization: Sync client machine information with the server session
  • Session Information: Retrieve current session state, user info, and Epicor version
  • Theme Preferences: Get user preferences and theme settings for UI customization

Development Workflow Enhancement

  • Staging Retry: Automatically retry EFX function calls with staging endpoint on 404
  • Seamless Testing: Test functions in staging before publishing to production
  • Smart Fallback: Only retries when initial call returns 404 status

Method Standardization

  • Deprecated Createsession(): Use CreateSession() (capital ‘S’) instead
  • Consistent Naming: All methods now follow proper PascalCase conventions
  • Backward Compatible: Deprecated method still works but will be removed in future versions

Comprehensive Test Coverage

  • Added automated tests for all new session management methods
  • Test validates SetEmployee, SetPlant, SetWorkstation, and SetClientData functionality
  • Integrated EfxAttemptStagingRetry testing with detailed output
  • GetSessionInfo and GetThemeInfo validation included

:bullseye: Use Cases

The new session management methods enable:

  • Multi-User Scenarios: Switch employee context for labor tracking without creating new sessions
  • Multi-Site Operations: Change plant context for cross-facility workflows
  • Production Tracking: Set workstation context for manufacturing operations
  • Session Diagnostics: Retrieve session information for debugging and auditing
  • UI Customization: Adapt interfaces based on user theme preferences
  • Client Integration: Synchronize client machine details with Epicor server

The EfxAttemptStagingRetry flag enables:

  • Function Development: Test new EFX functions in staging before production deployment
  • Rapid Iteration: Automatically fall back to staging during development
  • Seamless Workflow: Reduce manual endpoint switching during testing

:open_book: Usage Examples

Session Management

import { EpicorRestService, EpicorError } from 'epicor-rest-node';

const epicorService = new EpicorRestService();
// ... configure service properties ...

// Create a session first
const sessionCreated = await epicorService.CreateSession();

if (sessionCreated) {
  try {
    // Switch employee context
    const employeeSet = await epicorService.SetEmployee('EMP123');
    if (employeeSet) {
      console.log('Employee context updated');
    }

    // Change plant/site
    const plantSet = await epicorService.SetPlant('MfgSys');
    if (plantSet) {
      console.log('Plant context updated');
    }

    // Set workstation
    const workstationSet = await epicorService.SetWorkstation('WKST001');
    if (workstationSet) {
      console.log('Workstation context updated');
    }

    // Synchronize client data
    const clientDataSet = await epicorService.SetClientData(
      'john.doe',
      'DESKTOP-ABC123',
      'M/d/yyyy'
    );
    if (clientDataSet) {
      console.log('Client data synchronized');
    }

    // Get session information
    const sessionInfo = await epicorService.GetSessionInfo();
    console.log('Current User:', sessionInfo.UserID);
    console.log('Company:', sessionInfo.CompanyID);
    console.log('Plant:', sessionInfo.PlantID);

    // Get theme information
    const themeInfo = await epicorService.GetThemeInfo();
    console.log('User Theme:', themeInfo.Theme);

  } finally {
    await epicorService.DestroySession();
  }
}

EFX Staging Retry (Development Only)

import { EpicorRestService } from 'epicor-rest-node';

const epicorService = new EpicorRestService();
// ... configure service properties ...

// Enable staging retry for development
epicorService.EfxAttemptStagingRetry = true;

// Call EFX function - will automatically retry with staging endpoint on 404
const result = await epicorService.EfxPost(
  'MyLibrary',
  'MyNewFunction',
  { param1: 'value1' }
);

// Remember to disable for production!
epicorService.EfxAttemptStagingRetry = false;

:wrench: Technical Details

Session Management

  • Session Required: All Set* methods require an active session or will throw an error
  • Type Safety: Fully typed with boolean return values for success/failure
  • Error Handling: Consistent error handling using EpicorError class
  • Session Info: Returns detailed user, company, plant, and version information
  • Theme Info: Returns user preferences and shell layout options

EFX Staging Retry

  • Development Only: Should only be enabled during development/testing
  • Smart Retry: Only retries when initial call returns 404 status
  • Transparent: Works seamlessly with existing EfxPost calls
  • Configurable: Simple boolean flag to enable/disable

Breaking Changes

  • None: All changes are backward compatible
  • Deprecation: Createsession() deprecated in favor of CreateSession()

:test_tube: Testing

  • New Test Methods:

    • testSetEmployee() - Validates employee context switching
    • testSetPlant() - Validates plant context switching
    • testSetWorkstation() - Validates workstation context switching
    • testSetClientData() - Validates client data synchronization
    • testGetSessionInfo() - Validates session information retrieval
    • testGetThemeInfo() - Validates theme information retrieval
    • testEfxAttemptStagingRetry() - Validates staging retry functionality

  • Full Integration: Tests validate real-world session management scenarios

  • Detailed Output: Tests provide comprehensive feedback on session state changes

  • CI/CD Ready: Integrated with existing test automation

  • Optional Configuration: Tests skip gracefully if optional parameters not configured

:building_construction: Backward Compatibility

This release is fully backward compatible. All existing functionality remains unchanged, and the new session management methods are additive enhancements. The deprecated Createsession() method continues to work but will be removed in a future major version.

:warning: Important Notes

  • Session Management: All Set* methods require an active session created with CreateSession()
  • Staging Retry: The EfxAttemptStagingRetry flag should only be used during development
  • Deprecation Warning: Update Createsession() calls to CreateSession() to prepare for future versions
  • Production Use: Disable EfxAttemptStagingRetry in production environments
3 Likes