ObjMethod

You can use the ObjMethod function to apply a system method to an object during workflows, copy methods, symbol scripts, or equations. The function provides programmatic access to Optiva's built-in object operations and calculations.

When to use

You can use this function to:

  • Execute an action or operation on an object.
  • Perform complex internal calculations in Optiva.
  • Transform or restructure data.

Syntax

object ObjMethod(string objSymbol, string objkey, string method, params object[] @params);

Parameters

Parameter Type Required Description
objSymbol string Yes

The symbol of the object.

Note: You can use empty quotation marks ("") for the current workflow symbol.
objKey string Yes

The key of the object.

Note: You can use empty quotation marks ("") for the current workflow symbol.
method string Yes The system method names to execute.

SeeAvailable methods by Category
@params paramsobject[] Yes The variable number of parameters required by the specific method.

Return Value

  • The application returns an object containing the method result.
  • The return type varies depending on the method.
  • Cast the returned value to the appropriate type based on the method.

Examples

Example 1
Controlling Workflow Start Time with CurrentExternalCalculateDates.
Purpose

The CurrentExternalCalculateDates method allows you to programmatically set the start time of a currently running Optiva workflow. This is useful when you want the workflow to use a specific date or time (like a projects effective date) rather than the default current timestamp.

Key characteristics
  • This function only affects the currently running WIP ID (Work In Progress workflow instance).
  • Requires only a DateTime value for the start time.
  • This function does not need a DataSet parameter.
public long wf_set_start_date()
{
    // Step 1: Get the project's effective start date
    object sStartDate = ObjProperty("EFF_START_DATE", "", "");
    
    // Step 2: Validate that the date exists
    if (IsBlank(sStartDate) == 1)
    {
        MessageList("The project start date has not been set. Therefore the workflow cannot be started.");
        return 9111;  // Return error code to halt workflow
    }
    
    // Step 3: Convert to DateTime type
    DateTime startDate = Convert.ToDateTime(sStartDate);
    
    // Step 4: Set the workflow start time to this date
    ObjMethod("", "", "CurrentExternalCalculateDates", startDate);
    
    // Step 5: Reassign workflow to FRADMIN user
    Reassign("FRADMIN", "", "");
    
    return 0;  // Success
}
Description

This example sets a workflows start time to match a projects effective start date instead of using the current timestamp, then reassigns the workflow to the FRADMIN user. It validates that the effective start date exists before applying it, returning an error code (9111) if the date is not set.

Example 2
Calling ObjectMethod from ObjMethod.
Purpose
The ObjectMethod is a generic wrapper method that can be called through ObjMethod to execute various object-specific operations. It acts as a gateway to multiple methods depending on the object type and parameters provided.

This function is useful for dynamic, configurable code and secured scripting scenarios. For known operations, direct ObjMethod calls are clearer, but ObjectMethod provides flexibility when you need a generic interface to multiple operations.

Key characteristics
The ObjectMethod is a meta-method or generic method handler that:
  • Acts as a single entry point for multiple operations.
  • Routes to specific methods based on parameters.
DataSet results = (DataSet)ObjMethod("", "", "ObjectMethod", "CLEARRESULTS", null);
Description
All results are removed from an analysis object. 
object scaleResult = ObjMethod("", "", "ObjectMethod", "Scale", "newyield=50; newuom=GM;rsmode=1");
Description

Rescale a formula to a new yield and/or unit of measure

  • This example scales a formula from 1000 KG to a 50 gram sample.
  • The argument rsmode =1 changes ingredient UOMs to “newUOM”.
  • The argument rsmode=0 does not change ingredient UOMs.
Example 3
Conversion factors for Formulation using UomStrConv.
Purpose

The UOMSTRCONV method creates a conversion factor between two units of measure, specifically for use in formula workflows. It calculates the multiplier needed to convert from one UOM to another.

object oUom = ObjProperty("UOMCODE", "", "");
object oFactor = ObjMethod("", "", "UOMSTRCONV", oUom, "KG");
object oYield = Convert.ToDouble(ObjProperty("YIELD", "", "")) * Convert.ToDouble(oFactor);
object oMethod = ObjMethod("XGMITEM", oItemkey, "setdefaults", oFormula, oVersion, oYield, oProcessYield);
Description
  1. Get Current Unit of Measure
    • Retrieves the formulas current unit of measure code. For example: "LB", "GM", "L"
    • UOMCODE is the property containing the UOM.
  2. Calculate Conversion Factor
    • First parameter (currentUom): Source unit (what you are converting from).
    • Second parameter ("KG"): Target unit (what you are converting to).
    • Returns: Numeric factor to multiply by

    Example conversions:

    • LB → KG: factor ≈ 0.453592
    • GM → KG: factor = 0.001
    • OZ → KG: factor ≈ 0.0283495
  3. Convert Yield Value
    • Multiply original yield by conversion factor
    • Result is yield in target unit (kilograms)

    Example calculation:

    • Original: 100 LB
    • Factor: 0.453592 (LB to KG)
    • Result: 100 × 0.453592 = 45.3592 KG
  4. Use Converted Value
Example 4
Finding the lowest status for a formula or formula ingredients.
Purpose
The INGRLOWESTSTATUS method compares the status of each item in a formula and returns the lowest status value found among all ingredients.This is useful for validation workflows to ensure all ingredients meet minimum status requirements before approving or releasing a formula. 
object oLowStatus = ObjMethod("", "", "INGRLOWESTSTATUS");
Description
Gets the lowest status among all formula ingredients of the current formula.
Return Value
  • Returns an object containing the lowest status code (integer).
  • Typically status codes like: 100 (Draft), 200 (In Review), 300 (Approved), 400 (Released), etc.
Example 5
Calculating a Formula with ObjectMethod.
Purpose
The CALC method performs formula calculations using ObjectMethod. It recalculates ingredient quantities, costs, parameters, and other formula values based on specified calculation modes and flags. 
object calcResult = ObjMethod("FORMULA", "", "ObjectMethod", "CALC", "mode=0;calcflags=0");
CalcFlags Parameter
Flag Name Description When to use
0 As Necessary Conditional calculation - only recalculates if ingredients or parameters are changed. Default, most efficient.
1 CostOnly Roll up costs only (first-level). When only cost recalculation needed.
2 ForceAll Unconditional calculation - always recalculates regardless of thechanges. Force full recalculation.
4 CalcAll All-level calculation - calculates all sub-formulas before main formula. Multi-level formulas with constituents.
Note: The user running the script must have write access to all sub-formulas in the structure, and that the sub-formulas (if edited) need to be modified through the tree view.
Example 6
Obtaining a Parent Code.
Purpose

The ParentCode method retrieves the parent objects key for objects like formulas or projects. It returns a string array containing the parents code and optionally the version.

Purpose 
object parentCodeArray = ObjMethod("", "", "ParentCode");
public long wf_get_parent_code()
{
    try
    {
        // Get parent code as string array
        object parentCodeObj = ObjMethod("", "", "ParentCode");
        
        // Check if parent exists
        if (parentCodeObj == null)
        {
            MessageList("No parent object exists for this object");
            return 0;
        }
        
        // Cast to string array
        string[] parentCodeArray = (string[])parentCodeObj;
        
        // Join array components with backslash separator
        // Result will be "Code" or "Code\Version"
        string parentCode = string.Join("\\", parentCodeArray);
        
        MessageList("Parent object code:", parentCode);
        
        // Use the parent code for further processing
        // Example: Load parent object properties
        object parentDescription = ObjProperty("DESCRIPTION", "FORMULA", parentCode);
        MessageList("Parent description:", parentDescription?.ToString());
        
        return 0;
    }
    catch (Exception ex)
    {
        MessageList("Error retrieving parent code:", ex.Message);
        return -1;
    }
}
Return Value
  • Returns a string array with parent key components.
  • Format: ["Code"] or ["Code", "Version"].
  • Returns null if no parent exists.
Example 7
Changing the filter to retrieve parameters using FILTERCHANGE.
Purpose
The FILTERCHANGE method switches the parameter filter to retrieve parameter values in an alternate unit of measure. This is useful when you need to view parameters using a different UOM than the default.

Must call ObjectXML first to load parameters, then apply the filter with format"detailCode;filterName", and retrieve the updated XML with alternate UOM values. If your workflow is already retrieving parameter values, then you may not require that step.

Usage

This method copies all item parameters and cannot run during the calc cycle. You can use this method only in:

  • Post-save hook scripts
  • Workflows
Scenario 1
Post-Save Hook Script. 
using System;
using System.Data;
using System.Diagnostics;

class HookScript : FcProcFuncSetEventHook
{
    public long postsave()
    {
        // Roll up constituent formula parameters to raw material item
        object oRollup = ObjMethod("", "", "ObjectMethod", "ConstituentRollup", "");
        
        return 1;
    }
}
Description
The script runs when a constituent formula is saved after being created or updated. The Save event occurs after the formula is calculated and its parameter values are updated by the standard rollup process. This example adds “ObjectMethod” as the third argument.
Scenario 2

Workflow on Current Constituent Formula.

This object method can also be invoked from a workflow. If a workflow is running on the constituent formula,then the syntax is: 
object rc = ObjMethod("", "", "ObjectMethod", "CONSTITUENTROLLUP", "");
If the workflow is running on another object, then the symbol is the first argument. The key is the second. The rest of the arguments are always the same. 
object rc = ObjMethod("FORMULA", formulaKey, "ObjectMethod", "CONSTITUENTROLLUP", "");
Parameter Level Update Rules
Level Before Rollup Level Value Description Update
Pending 0 Overwrite item value with constituent formula value. Yes
Manual Override 1 Do not change - user manually set. No
Calculated 2 Do not change - subsequent Save/Calc will update based on parameter definitions. No
Derived from Constituents 3 Update item value with constituent formula value. Yes

You can use ConstituentRollup in post-save hook scripts or workflows to automatically update raw material item parameters from constituent formula values.

Note: You must not use in equations as it cannot run during the calc cycle.
Example 9
Calculating and clearing analysis results.
Purpose
The CALC and CLEARRESULTS methods are used with Analysis objects to calculate/populate results or clear all result values. Use CALC with "ANALYSIS.RESULT" object symbol to calculate analysis results, and CLEARRESULTS to remove all result values. Can be used in workflows, custom buttons, or hook scripts.
Scenario 1
CALC - Calculate and populate the results section of an analysis object. 
ObjMethod("ANALYSIS.RESULT", key, "ObjectMethod", "CALC", null);
Scenario 2

The CLEARRESULTS method of the ObjMethod function can be used to clear all values from the results section of an analysis.

In this example, the CLEARRESULTS method is applied to an analysis to clear all results values.

DataSet oResults = (DataSet)ObjMethod("", "", "ObjectMethod", "CLEARRESULTS", null);
Example 10
Calling Global Calc from ObjMethod.
Purpose
The EXECFORMULACALC method executes a Global Calc workflow or job to perform batch calculations on multiple formulas.
Scenario 1
Execute on Current Global Calc Object. 
object result = ObjMethod("", "", "Method", "EXECFORMULACALC", "", null);
Scenario 2
Execute Specific Global Calc Job. 
object result = ObjMethod("GLOBALCALC", jobName, "Method", "EXECFORMULACALC", "", null);

The method performs batch formula calculations based on the Global Calc configuration.

Example 11
Applying an ingredient statement rule.
Purpose
Applying an ingredient statement rule. 
object result = ObjMethod("LABEL", labelKey, "ObjectMethod", "GENERATE", "");
Example 12
Updating the preview in an ingredient statement.
Purpose
The PREVIEW method applies edits from the Ingredient Statement > Ingredients tab > Preview tab, updating the preview text with any manual ingredient changes. 
object result = ObjMethod("LABEL", labelKey, "ObjectMethod", "PREVIEW");
Example 13
Updating the label content.
Purpose
The UPDATELABELTEXT method updates the label ingredient statements in the Label Content form, equivalent to selecting the Update option on the form.
Scenario 1
This example demonstrates how to execute the Update and Refresh options in the Label Content form. 
object updateText = ObjMethod("LABELCONTENT", objectKey, "ObjectMethod", "UPDATELABELTEXT", null);
Scenario 2

This example executes the REFRESH on the Parameters tab of the Label Content object.

public long wf_refresh_parameters()
{
 object lcmTP = ObjMethod("LABELCONTENT", _OBJECTKEY, "ObjectMethod", "LOADSOURCETP", null);
    MessageList("Refresh Complete");
    return 111;
}
Example 14
Recalling (Cancel) a workflow.
Purpose
The RECALL method cancels a workflow after it has been launched.
What RECALL does:
  1. Changes the workflow status to 3-Canceled.
  2. Sets each WIP step status to 2-Closed.
  3. Marks the queue status as Closed.
  4. Terminates the workflow processing.
Scenario 1
Workflow Recall from Views Tab.
This workflow cancels the selected workflow from the Views tab of a formula. 
MessageList("Recalling workflow:", _ObjectKey);
ObjMethod("", "", "ObjectMethod", "RECALL", "");
MessageList("Recall complete");

The RECALL performs the same steps that the Workflow Maintenance form performs when the workflow status is 3-Canceled. Each WIP step is given a status of 2-Closed.

You can send email to notify the user that the formula approval has been recalled. See Notify

Set up a view for workflows to see the workflows that have been launched against an object. You can launch any workflow for a selected workflow-in-progress. For example, use this query for a formula view.

SELECT DISTINCT 
    W.ActionWIP_ID, 
    A.ActionSet_Code, 
    A.Description, 
    S.Due_date 
FROM 
    FsActionWIP W, 
    FsActionWIPSteps S, 
    FsActionSet A, 
    fsFormula F 
WHERE 
    S.ActionWIP_ID = W.ActionWIP_ID 
    AND W.ActionSet_code = A.ActionSet_code 
    AND F.Formula_id = [%1] 
    AND S.TARGET_OBJECT_KEY = F.Formula_code + '\' + F.Version
Setup Process
  1. Add the SQL query above to a formula view.
  2. Shows all workflows launched against the formula.
  3. User selects a workflow-in-progress from the view.
  4. Click Launch Workflow option.
  5. Choose the recall workflow action set.
  6. Recall workflow runs and cancels the target workflow.
What This Query Returns:
  • The workflow in-progress ID.
  • The workflow action set code.
  • The workflow description.
  • The step due date.

You can launch a Recall workflow for a workflow-in-progress instead of an object from the Reports tab.

  1. Select a workflow.
  2. Select the Launch Workflow option. The Launch Workflow form is opened.
  3. Select a Recall Workflow action set.
  4. After the Recall workflow has run on WIP ID 5330, the status of the workflow is Cancelled.
Related topics