Invoke functions

After you create and deploy a function, you can use the invoke command to invoke it synchronously or asynchronously. You can also create event bindings that automatically invoke the function in response to Stedi events.

​

Sync vs async

There are two fundamental ways to invoke a function, synchronously or asynchronously.

Synchronous invocations will wait for the execution to complete, and return the result of the function right away - similar to calling a remote API. If the function execution fails or takes too long to finish, you also get an indication of the error as part of the response. The synchronous mode is useful for callers that require an answer before they can proceed. Another common use is testing your functions. Functions that take a long time to finish may not be best suited to synchronous invocations, as this also causes the caller to have to wait for a response.

Async invocations work quite differently. Asynchronous requests are added to a queue of items to be processed by the function. Stedi Functions pulls requests from this queue and invokes the function - if there is a large backlog, multiple copies of the function will be started to process the queued work in parallel. Any response from the function that is not an error is considered a success and will cause the request payload to be removed from the input queue. The return value from such successful function invocations is discarded. By default, any errors will be retried for 3 attempts in total, before being moved to a dedicated error queue. You can configure the number of retries for async requests for each Stedi function you create.

The benefit of async invocations is handling spikes in load. If you had a function that took a while to run (say it made several external API calls), and you synchronously invoked it 10k times in 5 minutes, some requests are likely to start failing. But if those were async invocations, they’d just be added to the queue and worked through over time.

​

Invoke functions

You can invoke functions manually through the UI or CLI and automatically with event bindings, function schedules, and the Functions SDK.

​

UI

To manually invoke functions in the Functions UI:

1. Open the function and click invoke.
2. Select the invocation type and supply an arbitrary request payload if needed. This is mostly useful for one-off testing.

​

Event bindings

You can invoke your function automatically in response to Stedi events with an event binding. For example, you could run a function when Stedi successfully processes an EDI transaction from a specific trading partner. Invocations triggered from event bindings are always asynchronous.

Visit Event bindings for more details.

​

Functions SDK

We recommend invoking functions with the SDK when you need to integrate Stedi Functions into an existing JavaScript codebase. You can invoke synchronously or asynchronously with the SDK.

Install the Stedi Functions SDK. The following command specifies that npm should download a package from Stedi Functions versions 0.2.x or later.

npm install @stedi/sdk-client-functions@^0.2 --save

Create a new file called invoke.js with the following contents.

import {
  FunctionsClient,
  InvokeFunctionCommand,
} from '@stedi/sdk-client-functions';

async function invoke() {
  // The client gives us access to Stedi Functions.
  const functionsClient = new FunctionsClient({
    region: 'us',
    apiKey: process.env.STEDI_API_KEY, // Read API key from environment variable.
  });

  // Invoke the function.
  const requestPayload = {}; // The payload is passed into the function as the event parameter of our handler

  const invokeFunctionCommand = new InvokeFunctionCommand({
    functionName: 'stedi-function',
    payload: requestPayload, // The payload object will be converted to JSON and passed to our function
    invocationType: 'Synchronous', // Optional, defaults to sync. "Synchronous" or "Asynchronous".
  });
  const invokeFunctionResult = await functionsClient.send(
    invokeFunctionCommand,
  );

  console.info('Invocation result:', invokeFunctionResult.payload);

  // The result includes the first couple of lines of the function log. It’s base64-encoded, so we
  // need to decode it first. In this example the log is small enough that it’s included in full.
  console.info('\nFunction log output:\n');
  console.info(invokeFunctionResult.logTail);
}

invoke();

Execute the code using Node.js, which will invoke the function deployed in your Stedi account.

node invoke.js

SDK Reference

​

CLI

You can invoke events on the command line with the Stedi CLI. You can only invoke synchronously with the CLI. For example, the following command invokes a function called stedi-function.

npx stedi functions invoke-function \
    --function-name stedi-function \
    --payload file://event.json

Stedi returns JSON output similar to the following example.

{
  "functionName": "stedi-function",
  "payload": {
    "message": "Hello, world!"
  },
  "logTail": ["..."],
  "invocationId": "<RANDOM_REQUEST_ID>"
}

The output contains the following properties:

• payload: Contains the output of the function
• logTail: Contains the last 4KB of logs from the function execution
• invocationId: Contains a unique identifier for this invocation. You can use this identifier to find a complete trace of this invocation in the Function Logs UI.

CLI Documentation

​

HTTP Invoke Function API

You can also invoke Functions directly over HTTP. The Stedi SDK provides convenient support for encoding the response, adding the necessary headers, and retrying common transient errors. However, we recognize that it is not always possible to use it with the platform of your choice.

If you have defined an environment variable called STEDI_API_KEY containing a valid Stedi API key, a function in your account called stedi-function, and a local file containing valid JSON called request.json, you can invoke the function from the command line using curl as follows:

curl \
  --request POST \
  --header "Authorization: ${STEDI_API_KEY}" \
  --data @request.json' \
  "https://edi-platform/functions.cloud.us.stedi.com/2021-11-16/edi-platform/functions/stedi-function/invocations"

The response body will be the function’s output in base64-encoded form. You can decode the response body by sending the output to the base64 utility as seen in the following example:

% curl \
  --request POST \
  --header "Authorization: ${STEDI_API_KEY}" \
  --data '{"message":"Hello, world!"}' \
  --silent \
  "https://edi-platform/functions.cloud.us.stedi.com/2021-11-16/edi-platform/functions/stedi-function/invocations" \
  | base64 -d

{"event":{"message":"Hello, world!"}}

​

Additional response information

The HTTP response will contain some additional information that may be useful for diagnostic purposes.

​

Errors

Example unhandled error:

{
  "errorType": "Error",
  "errorMessage": "Error: d8920684-d2c0-4268-b301-edb24a1c4163",
  "trace": [
    "Error: Error: d8920684-d2c0-4268-b301-edb24a1c4163",
    "    at exports.handler (/var/task/index.js:4:9)",
    "    at Runtime.handleOnceNonStreaming (file:///var/runtime/index.mjs:1086:29)"
  ]
}

Example function timeout:

{
  "errorMessage": "2023-07-11T20:49:13.880Z b1c7a119-4797-4333-92fe-fcad90e58d14 Task timed out after 3.01 seconds"
}