Extend Skedulo functionality with custom functions

Overview

The configuration variables feature allows you to store variables as key-value pairs in Skedulo. These values can then be referenced by developers in certain artifacts so that variables are not hard-coded.

To learn more about configuration variables, please refer to the documentation.

This article will teach you how to use configuration variables within a function that you develop using the Skedulo CLI.

Prerequisites

This documentation assumes that you have already developed a function using the Skedulo CLI.

Add configuration variables to a function

Before you can use a configuration variable in your functions code, first declare the configuration variable within the sked.proj.json file within your function source code.

To add a configuration variable to a function, do the following steps:

1. Open your function source code in VS Code.
2. Open the sked.proj.json file.
3. Add the following JSON to the object in the settings property, and then save the file:

"configVars": [
  {
    "name": "HELLO_RESPONSE",
    "configType": "plain-text",
    "description": "What would you like the function to respond with."
  }
]

Your sked.proj.json should now look something like this:

{
  "type": "function",
  "version": "2",
  "name": "my-first-function",
  "description": "Test function to help me learn about the CLI and functions!",
  "runtime": "nodejs18.x",
  "settings": {
    "configVars": [
      {
        "name": "HELLO_RESPONSE",
        "configType": "plain-text",
        "description": "What would you like the function to respond with."
      }
    ]
  }
}

4. Create a new file called .env The sked function dev local server will use this to mimic the platform supplying a configuration variable value to your function.

5. Add the following content to the file:

HELLO_RESPONSE='Hello world! - from .env'

Reference a configuration variable in your code

The previous section described how to declare a configuration variable, but that variable needs to be referenced in your code for it to be useful.

The code generated by the sked function generate command includes a dependency on the npm package @skedulo/function-utilities. This package includes helpers that make authoring functions easier.

You can see the const skedContext = createSkedContext(headers); call in the handler.ts file, which is in turn passed to the FunctionRoute we created in the previous section.

We are going to use this code fragment:

const helloResponse = skedContext?.configVars?.getVariableValue("HELLO_RESPONSE");

to obtain the configuration variable value defined by the name HELLO_RESPONSE, which we declared in the sked.proj.json and the .env file.

1. Open the routes.ts file in VS Code.

2. Add the following FunctionRoute to the getRoutes() method, and then save the file:

{
  method: "get",
  path: "/hello",
  handler: async (__, headers, method, path, skedContext) => {
    const helloResponse = skedContext?.configVars?.getVariableValue("HELLO_RESPONSE");
    return {
      status: 200,
      body: { result: helloResponse }
    };
  },
}

The complete routes.ts file should look like this:

/**
 * Describe the entry-point into the "skedulo-function" by updating the
 * array returned by the `getRoutes` method with additional routes
 */
import * as pathToRegExp from "path-to-regexp";
import { FunctionRoute } from "@skedulo/sdk-utilities";
// tslint:disable-next-line:no-empty-interface
interface RequestPayload {}
export function getCompiledRoutes() {
  return getRoutes().map((route) => {
    const regex = pathToRegExp(route.path);
    return {
      regex,
      method: route.method,
      handler: route.handler,
    };
  });
}
function getRoutes(): FunctionRoute[] {
  return [
    {
      method: "get",
      path: "/hello",
      handler: async (__, headers, method, path, skedContext) => {
        const helloResponse = skedContext?.configVars?.getVariableValue("HELLO_RESPONSE");
        return {
          status: 200,
          body: { result: helloResponse }
        };
      },
    }
  ];
}

3. Open a new terminal window, and compile your code using: yarn compile

4. Start the local development server using the command: sked function dev . -p 3000

5. Open a second terminal window and test your local function with the following curl command:

curl --location 'http://127.0.0.1:3000/hello' --header 'Authorization: Bearer <Your Tenant API Token>'

If your function is working correctly you should see:

{"result":"Hello world! - from .env"}

Set a default value for a configuration variable

Defaults are an important to help minimise the number of settings an administrator needs to manage. If the default behaviour of a function is fit for purpose, then there is no need to configure a variable in the web app.

To add a default value to configVars in the sked.proj.json file, do the following:

1. Open the sked.proj.json file and locate the configVars item.

2. Modify the variable (HELLO_RESPONSE in our example above) to add a default property with a value of, for example: "Hello world! - from sked.proj.json"

"configVars": [
  {
    "name": "HELLO_RESPONSE",
    "configType": "plain-text",
    "description": "What would you like the function to respond with.",
    "default": "Hello world! - from sked.proj.json"
  }
]

Your sked.proj.json should look something like this:

{
  "type": "function",
  "version": "2",
  "name": "my-first-function",
  "description": "Test function to help me learn about the CLI and functions!",
  "runtime": "nodejs18.x",
  "settings": {
    "configVars": [
      {
        "name": "HELLO_RESPONSE",
        "configType": "plain-text",
        "description": "What would you like the function to respond with.",
        "default": "Hello world! - from sked.proj.json"
      }
    ]
  }
}

Deploy and test your function in a team

After creating a function, adding a configuration variable to it, supplying a default value for it, and testing it locally, you can deploy it to a team (tenant).

To deploy your function to the server, do the following:

• Run the command: sked artifacts function upsert -f state.json

To test your function once deployed, so the following:

• Use the curl command: curl --location '<Your baseUrl>/ping' --header 'Authorization: Bearer <Your Tenant API Token>'

The response from the function deployed to the tenant should be:

Hello world! - from sked.proj.json

We haven’t created a configuration variable in the tenant, so the system will use the default value passed from the file.

The .env file is only used to simulate configuration variables in the development server, it is not used when the function is deployed to a tenant.

Override a function’s default configuration variable in a team

As an administrator, I may not be happy with the default message that the /hello method of the function returns. Luckily, this configurable and can be changed by simply creating a configuration variable in the team’s web app with the same name and the function response that better fits the need.

The instructions below describe how to do this using the example function above, but more information about the configuration variables can be found in the user guide.

To change the value of a function’s default configuration variable, do the following steps:

1. Log into the team using a web browser.

2. Navigate to Settings > Developer tools > Configuration variables.

3. Click Create variable.

4. Supply the following values:

   a. Name = “HELLO_RESPONSE”.

   b. Check the Plain text radio button.

   c. Value = “Hello world! - from tenant configuration variable“.

   d. Description = “Override the default variable for my-first-function/hello endpoint”.

5. Click Create.

Go back to your terminal window, and test the function with the curl command again.

The response should be:

Hello world! - from tenant configuration variable

as the variable defined in the platform takes precedence over the default supplied in the function.

Feedback

Was this page helpful?