runWfFunction() — Workflow Service

General Description

The runWfFunction operation executes a specific workflow function directly without needing to start or run a complete workflow.

Detailed Description

The runWfFunction operation allows you to execute a specific GSB serverless function by its ID or name. This is useful for:

• Executing utility functions from other functions
• Testing function behavior in isolation
• Building modular function architectures where complex operations are broken into smaller, reusable functions
• Implementing function-to-function communication patterns

When calling a function using runWfFunction, you can pass:

• An entity context
• Custom parameters via the prms object
• Other execution context information

Input Parameters

The runWfFunction operation accepts a request object with the following structure:

{
  "function": {
    // Either use ID
    "id": "function-uuid-here",
    // OR use name (one of these is required)
    "name": "Function Name Here"
  },
  "instance": {
    // The entity to pass to the function (optional)
    "entity": {
      // Entity data
    },
    // Additional parameters to pass (optional)
    "prms": {
      "param1": "value1",
      "param2": "value2"
    }
  }
}

Response

The response from runWfFunction contains:

1. A response field with whatever was set in the called function using:
   • _instance.response = {...}

• _runtime.success(result, response, action)
• _runtime.end(statusCode, message, result, response, action)

2. Status information and execution results from the function

Non-2xx responses reject with GsbHttpError. Core callers can inspect status, message, code, issues, details, logId, and systemLogId. Business error fields are present when the backend returns the structured response envelope. MCP and CLI callers receive the equivalent failure result.

Example response structure:

{
  "response": {
    // Whatever was set by the function
    "success": true,
    "data": { "id": "123", "status": "completed" }
  },
  "status": 200,
  "message": "Operation completed successfully"
}

Example Usage

Example 1: Basic Function Call

// Define the function request
let functionRequest = {
  function: {
    name: "Calculate Order Total"
  },
  instance: {
    entity: myOrder,
    prms: {
      applyDiscounts: true
    }
  }
};

// Call the function
let entityService = new GsbEntityService(_runtime);
let result = await entityService.runWfFunction(functionRequest);

// Access the response
if (result.response && result.response.success) {
  let calculatedTotal = result.response.totalPrice;
  // Continue processing...
}

Example 2: Function Chain

async function processOrder() {
  try {
    // Step 1: Validate order
    let validateResult = await entityService.runWfFunction({
      function: { name: "Validate Order" },
      instance: { entity: _instance.entity }
    });
    
    if (!validateResult.response.isValid) {
      _runtime.error(validateResult.response.validationErrors.join(", "));
      return;
    }
    
    // Step 2: Calculate totals
    let totalsResult = await entityService.runWfFunction({
      function: { name: "Calculate Order Totals" },
      instance: { entity: _instance.entity }
    });
    
    // Step 3: Process payment
    let paymentResult = await entityService.runWfFunction({
      function: { name: "Process Payment" },
      instance: { 
        entity: _instance.entity,
        prms: { calculatedTotals: totalsResult.response.totals }
      }
    });
    
    _runtime.success("Order processed successfully", paymentResult.response);
  } catch (error) {
    _runtime.error(error);
  }
}

Additional Information

Best Practices

1. Error Handling: Always implement proper error handling when calling functions:

   try {
     let result = await entityService.runWfFunction(request);
    // Non-2xx function responses reject with GsbHttpError.
   } catch (error) {
    if (error instanceof GsbHttpError) {
      // Use error.status, error.code, error.issues, and error.details.
    }
   }

2. Data Passing: Be consistent in how you structure function responses to make function chains more maintainable.

3. Function Isolation: Design functions to be self-contained units that can be tested and executed independently.

4. Performance: Be mindful of function call overhead in high-volume scenarios. Consider consolidating multiple small function calls if performance becomes an issue.

Security Considerations

Functions called via runWfFunction execute with the permissions of the calling context. Ensure that sensitive operations have appropriate authorization checks within the called function itself.