ExecuteFunctionAsync

Executes a custom business‑logic function (a “base type function”) on a specific record. This is the main entry point for running server‑side operations that are defined in the Maestro framework, such as calculations, validations, or workflow actions.

The function executes a function on the same base type or another basetype, depending on the function's configuration. The base type is identified by the record’s table (e.g., "Customers") or Guid and the record ID. The function to execute is identified by its name or Guid.

the record id is used to retrieve the latest data for that record from the server, ensuring that the function operates on up‑to‑date information. This is crucial for maintaining data integrity and consistency, especially in multi‑user environments where records may be modified concurrently.

The method retrieves the latest model of the record (the “base type data”), packages it together with the function and record identifiers, and sends the request to the server. It returns the result as a dictionary of field → value pairs, or null if the record does not exist.

The function can be specified by its Guid or by its name, and the target table can likewise be identified by Guid or name. The four overloads cover the possible combinations.

⭐ Recommended Overload

ExecuteFunctionAsync(Guid functionId, Guid baseTypeId, string recordId)

Why? Using Guids for both the function and the base type avoids an extra table‑name lookup (Tables[baseTypeName]) and eliminates any risk of name ambiguity. This overload is the most direct and efficient. Prefer it whenever you have the Guids available.

Overload 1 (All Guids)

public async Task<Dictionary<string, object>> ExecuteFunctionAsync(
    Guid functionId,
    Guid baseTypeId,
    string recordId
)

Parameters

NameTypeDescription
functionIdGuidThe unique identifier of the function to execute.
baseTypeIdGuidThe GUID of the table (base type) on which the function operates.
recordIdstringThe unique identifier of the record.

Exceptions

  • FunctionNotFoundException – if functionId is empty.
  • BaseTypeNotFoundException – if baseTypeId is empty.

Returns

Dictionary<string, object> containing the function's output fields, or null if the record does not exist.

Overload 2 (All Names)

public async Task<Dictionary<string, object>> ExecuteFunctionAsync(
    string functionName,
    string baseTypeName,
    string recordId
)

Parameters

NameTypeDescription
functionNamestringThe name of the function to execute.
baseTypeNamestringThe name of the table (e.g., "Customers").
recordIdstringThe unique record identifier.

Exceptions

  • FunctionNotFoundException – if functionName is null or empty.
  • BaseTypeNotFoundException – if baseTypeName is null/empty.

Returns

Dictionary of results, or null if the record is missing.

Note: This overload internally looks up the table using Tables[baseTypeName]. Use it when you only know the human‑readable table name and function name.

Overload 3 (Function Guid, Base Type Name)

public async Task<Dictionary<string, object>> ExecuteFunctionAsync(
    Guid functionId,
    string baseTypeName,
    string recordId
)

Parameters

NameTypeDescription
functionIdGuidThe function's Guid.
baseTypeNamestringThe table name.
recordIdstringRecord identifier.

Exceptions

  • FunctionNotFoundException – if functionId is empty.
  • BaseTypeNotFoundException – if baseTypeName is null/empty.

Returns

Dictionary of results, or null.

Note: The table is resolved via its name. If you already have the function Guid but only the table name, this overload is appropriate.

Overload 4 (Function Name, Base Type Guid)

public async Task<Dictionary<string, object>> ExecuteFunctionAsync(
    string functionName,
    Guid baseTypeId,
    string recordId
)

Parameters

NameTypeDescription
functionNamestringThe function name.
baseTypeIdGuidThe table Guid.
recordIdstringRecord identifier.

Exceptions

  • FunctionNotFoundException – if functionName is null/empty.
  • BaseTypeNotFoundException – if baseTypeId is empty.

Returns

Dictionary of results, or null.

Example (Recommended Overload)

// Known Guids (obtained from configuration or another service)
Guid myFunctionId = Guid.Parse("a1b2c3d4-...");
Guid customersTableId = Guid.Parse("e5f6a7b8-...");
string recordId = "00000000-0000-0000-0000-000000000000";

// Recommended: use the all‑Guid overload
Dictionary<string, object> result = await QSAppContext.ExecuteFunctionAsync(myFunctionId, customersTableId, recordId);

if (result != null)
{
    foreach (var kvp in result)
    {
        Console.WriteLine($"{kvp.Key} = {kvp.Value}");
    }
}