User Defined Functions

Enneo allows for custom programming in the form of "User Defined Functions". These functions can be utilized in various areas, such as in the business logic of rule based AI agents, in webhooks, or in event implementations. In other words, anywhere where proprietary code or SDKs are applied.

Management of User Defined Functions

The management of user defined functions is located in the Integration of External Systems section of the settings. A limitless number of custom functions can be created here.

Tip

Functions are saved as code fragments that implement specific application logic and can be accessed in various integration scenarios.

Possible Applications

User Defined Functions offer a wide range of applications, for instance:

Interface calls for external systems: For example, ERP, task management, or archival systems.
Connection to output management systems: Such as for the sending of notifications.
Outsourcing of complex procedures: In the form of reusable components.

With these functionalities, Enneo enhances adaptability and enables the integration of specific company logic into AI-based customer support.

Calling User Defined Functions

Enneo can store and use custom functions. The following instances are possible, shown here using the example of a user-defined-function named 'my-udf': Within Enneo using the Python SDK:

sdk.ApiEnneo.executeUdf('my-udf', {"parameter1": "value1", "parameter2": "value2"}, 'serviceWorker')

Within Enneo using the PHP SDK:

\EnneoSDK\ApiEnneo::executeUdf('my-udf', ['parameter1' => 'value1', 'parameter2' => 'value2'],'serviceWorker');

Through external web request:

    POST https://your-subdomain.enneo.ai/api/mind/executor/execute/my-udf
    Payload: '{"parameter1": "value1", "parameter2": "value2"}'

Storage Object for User Defined Functions

Any JSON object can be used as an internal storage object for user defined functions within Enneo. This enables the saving and retrieving of data via the Enneo SDK.

\EnneoSDK\Setting::set('udfStorage', ['my' => 'data']);
$storedData = \EnneoSDK\Setting::get('udfStorage');

Example: Calling the API of a third-party system

Initially, the necessary data is defined in the storage object for user defined functions:

{
  "thirdParty": {
    "oauth": {
      "clientId": "123456789",
      "grantType": "client_credentials",
      "clientSecret": "abcdefg.....hijklmnop",
      "tokenEndpoint": "https://token-url/oauth2/token",
      "baseUrl": "https://third-party-url/api"
    }
  }
}

In the second step, a user defined function named fetch-thirdparty-token can be implemented to access the credentials. This procedure is particularly advisable if the access to the credentials can be reused in several other procedures.

<?php

// Load enneo SDK
require(getenv()['SDK']);

// Load the storage object for user defined functions
$udfStorage = \EnneoSDK\Setting::get('udfStorage');

// Access token
$clientId = $udfStorage->thirdParty->oauth->clientId;
$clientSecret = $udfStorage->thirdParty->oauth->clientSecret;

$result = \EnneoSDK\Api::call(
    method: 'POST',
    url: $udfStorage->thirdParty->oauth->tokenEndpoint,
    headers: [
        'Authorization: Basic ' . base64_encode($clientId . ':' . $clientSecret),
        'Content-Type: application/x-www-form-urlencoded',
        'Accept: application/json'
    ],
    params: http_build_query(['grant_type' => $udfStorage->thirdParty->oauth->grantType ?? 'client_credentials',
        'scope' => $udfStorage->thirdParty->oauth->scope ?? null])
);

// The output is in JSON format and can be used in the corresponding code after call
echo json_encode(['accessToken' => $result->access_token,
    'accessTokenExpiresAt' => date("Y-m-d H:i:s T", time() + $result->expires_in),
    "baseUrl" => $udfStorage->thirdParty->baseUrl,
    "headers" => $udfStorage->thirdParty->headers ?? [],
    "apiName" => $udfStorage->thirdParty->apiName ?? "Client-API",
]);

Subsequently, the implementation of the function third-party-api-call for the actual API call can be executed:

<?php
<?php

// Load SDK
require(getenv()['SDK']);

// Load token using the previously defined "fetch-thirdparty-token" function
$credentials = \EnneoSDK\ApiEnneo::executeUdf('fetch-thirdparty-token', []);

// Load input parameters
$in = \EnneoSDK\Input::load();

// Prepare header for the third-party-API request
$headers = [
    'Authorization: Bearer '. $credentials->accessToken,
    'Accept: application/json'
];
foreach (($cred->headers ?? []) as $key => $val) {
    $headers[] = "$key: $val";
}

// API call and output
$res = \EnneoSDK\Api::call(
    method: $in->method,
    url: $credentials->baseUrl.'/'.$in->api,
    headers: $headers,
    params: $in->params
);

// Output result
echo json_encode($res);

This structure allows for a flexible usage and integration of user-defined codes within Enneo, embodying specific business logic or seamlessly integrating external systems.

Invoking Custom Functions

Custom functions are invoked in the code using executeUdf:

<?php

// Load Enneo SDK
require(getenv()['SDK']);

// Prepare payload for the API call of the third-party system
$payload = [
    'ticket-id' => 123,
    'key' => 'value'
];

// Invocation of the custom function "third-party-api-call"
// this function receives an object as an input parameter:
// [
//      'method' => 'POST',
//      'api' => 'item',
//      'params' => [
//          'ticket-id' => 123,
//           'key' => 'value'
//      ]
// ]
EnneoSDK\ApiEnneo::executeUdf(
    'third-party-api-call',
    ['method' => 'POST', 'api' => 'item', 'params' => $payload]
);