Custom Value Calculator

Sepasoft MES Module Suite

Custom Value Calculator

You can register and unregister custom value sources and calculators on the fly. This enables critical use cases, such as loading production-line-specific calculations or integrating data from a new piece of equipment, without necessitating a gateway restart. This dynamic capability is central to creating a flexible and responsive manufacturing execution system. At the heart of these custom calculations is a fundamental component known as the Custom Value Calculator.

A Custom Value Calculator is an object used within the OEE Downtime module to define custom items and their associated calculations, making them available to the analysis engine. Its primary purpose is to encapsulate the business logic required to compute metrics that are specific to an organization's internal processes or reporting standards.

For instance, a manufacturer may need to track a proprietary metric like an "Operational Productivity Metric" (OPM) for internal reporting. The formula and mathematical logic required to calculate this OPM would be defined within a Custom Value Calculator. This allows the MES to be tailored precisely to business needs. The first step in leveraging this capability is to create the calculator object itself.

Instantiating a Custom Value Calculator Object

Before any custom logic can be implemented or the calculator's lifecycle managed within the MES Analysis Engine, an object instance must first be created. The primary scripting function provided for this purpose is system.mes.analysis.createCustomValueCalculator. Once this function has been called and the calculator object is instantiated, the next step is to define the specific calculation logic it will perform.

Implementing Custom Calculation Logic

The core functionality of a Custom Value Calculator is defined by implementing specific methods on the object. These methods are where the actual computations, data manipulations, and business logic reside, allowing the calculator to process data rows and produce results for the analysis engine. The key methods for this purpose are calculateRow and calculateFinalRow.

Beside the common MESAbstractObject methods, the following methods exist for the Custom Value Calculator object.

calculateRow

This method is called for each row of the analysis results.
  • Syntax: calculateRow(valueItem, date, row, results)

  • Parameters:
  • ValueItem valueItem
  • Date date
  • List row
  • BaseAnalysisDataset results
  • Returns: boolean

  • Scope: All

calculateFinalRow

This method is called once for the final results row.
  • Syntax: calculateFinalRow(valueItem, date, row, results)
  • Parameters:

  • ValueItem valueItem
  • Date date
  • List row
  • BaseAnalysisDataset results

    • Returns: boolean
    • Scope: All

    With the calculator's logic defined through these methods, the final stage involves deploying and managing its lifecycle within the live MES Analysis Engine.

    Managing the Lifecycle of Custom Components

    Effective MES analysis requires programmatic lifecycle management for custom components. The update functions provide a consolidated interface for registering new components and unregistering obsolete ones in a single, atomic operation. This approach is the recommended best practice, superseding the older, individual system.mes.analysis.register... and system.mes.analysis.unregister... functions.

    Using the consolidated update functions ensures configuration integrity, simplifies script development, and aligns with the critical best practice of performing bulk atomic operations,

    The system.mes.analysis.updateCustomValueCalculators Function
    system.mes.analysis.updateCustomValueCalculators(Collection registerValueCalculators, Collection unregisterValueCalculatorNames)
    This function registers a collection of new calculator objects and unregisters a collection of existing calculators by name in a single call. The configuration lock on the analysis engine is only obtained once for all arguments.
    Parameter
    Description
    registerValueCalculators
    A collection of custom value-calculator objects to register with the MES Analysis Engine.
    unregisterValueCalculatorNames
    A collection of custom value-calculator names to unregister from the MES Analysis Engine.

    The system.mes.analysis.updateCustomValueSources Function
    A parallel function exists to manage the custom value sources that provide the raw data used by the calculators.
    system.mes.analysis.updateCustomValueSources(Collection registerValueSources, Collection unregisterValueSourceNames)
    Parameter
    Description
    registerValueSources
    A collection of custom value-source objects to register with the MES Analysis Engine.
    unregisterValueSourceNames
    A collection of custom value-source names to unregister from the MES Analysis Engine.

    Effective use of these management functions depends on adhering to several critical implementation rules.

    Critical Implementation Best Practices

    To build robust, stable, and high-performance MES analysis solutions, it is essential to understand the operational context and design principles of these scripting functions. Adhering to the following best practices is crucial for avoiding common pitfalls and maximizing system performance.

    Gateway Scope Exclusivity

    • Gateway startup scripts for initial registration
    • Message handlers to react to system events (e.g., a new production line being configured)
    • Scheduled scripts for periodic updates

    Efficient Bulk Operations

    Each call to an update function acquires and releases a configuration lock on the MES Analysis Engine, an operation that carries performance overhead. The functions are designed to minimize this overhead by processing all registrations and unregistrations in a single, atomic operation. Therefore, the most efficient implementation is to batch all desired changes into a single call rather than making multiple sequential calls.

    Recommended: Call once with all changes

    # Recommended: Call once with all changes system.mes.analysis.updateCustomValueSources(all_new_sources, all_old_source_names)

    Avoid: Calling inside a loop for each individual item

    # Avoid: Calling inside a loop for each individual item for source in all_new_sources:     system.mes.analysis.updateCustomValueSources([source], []) # Inefficient
    Adhering to the principles of gateway scope execution and bulk operations is fundamental to building stable and high-performance MES analysis solutions.


    Sepasoft MES Module Suite