Functions - Keep

The Functions in Keep Workflow Engine are utilities that can be used to manipulate data, check conditions, or perform transformations within workflows. This document provides a brief overview and usage examples for each available function.

Mathematical Functions

`add`

Description: Adds all provided numbers together. All arguments are converted to integers. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.add(1, 2, 3) # Output: 6
        message2: keep.add(10, 20, 30) # Output: 60

`sub`

Description: Subtracts all subsequent numbers from the first number. All arguments are converted to integers. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.sub(10, 2, 3) # Output: 5
        message2: keep.sub(100, 20, 30) # Output: 50

`mul`

Description: Multiplies all provided numbers together. All arguments are converted to integers. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.mul(2, 3, 4) # Output: 24
        message2: keep.mul(5, 6, 7) # Output: 210

`div`

Description: Divides the first number by all subsequent numbers. All arguments are converted to integers. Returns an integer if the division result is whole, otherwise returns a floating-point number. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.div(10, 2) # Output: 5
        message2: keep.div(10, 3) # Output: 3.3333333333333335
        message3: keep.div(100, 2, 5) # Output: 10

`mod`

Description: Calculates the remainder of dividing the first number by all subsequent numbers sequentially. All arguments are converted to integers. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.mod(10, 3) # Output: 1
        message2: keep.mod(100, 30, 7) # Output: 2

`exp`

Description: Raises the first number to the power equal to the product of all subsequent numbers. All arguments are converted to integers. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.exp(2, 3) # Output: 8
        message2: keep.exp(2, 3, 2) # Output: 64

`fdiv`

Description: Performs integer division of the first number by all subsequent numbers sequentially. All arguments are converted to integers. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.fdiv(10, 3) # Output: 3
        message2: keep.fdiv(100, 3, 2) # Output: 16

`eq`

Description: Checks if two values are equal. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.eq(5, 5) # Output: true
        message2: keep.eq("hello", "world") # Output: false
        message3: keep.eq([1, 2, 3], [1, 2, 3]) # Output: true

String Functions

`uppercase`

Description: Converts a string to uppercase. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: "keep.uppercase('hello world')" # Output: "HELLO WORLD"

`lowercase`

Description: Converts a string to lowercase. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: "keep.lowercase('HELLO WORLD')" # Output: "hello world"

`capitalize`

Description: Capitalizes the first character of a string. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.capitalize("hello world") # Output: "Hello world"

`title`

Description: Converts a string to title case (capitalizes each word). Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.title("hello world") # Output: "Hello World"

`split`

Description: Splits a string into a list using a delimiter. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: "keep.split('a,b,c', ',')" # Output: ["a", "b", "c"]

`strip`

Description: Removes leading and trailing whitespace from a string. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.strip("  hello world  ") # Output: "hello world"

`replace`

Description: Replaces occurrences of a substring with another string. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.replace("hello world", "world", "Keep") # Output: "hello Keep"

`remove_newlines`

Description: Removes all newline and tab characters from a string. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.remove_newlines("hello\nworld\t!") # Output: "helloworld!"

`encode`

Description: URL-encodes a string. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.encode("hello world") # Output: "hello%20world"

`slice`

Description: Extracts a portion of a string based on start and end indices. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.slice("hello world", 0, 5) # Output: "hello"

List and Dictionary Functions

`first`

Description: Retrieves the first element from a list. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.first([1, 2, 3]) # Output: 1

`last`

Description: Retrieves the last element from a list. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.last([1, 2, 3]) # Output: 3

`index`

Description: Retrieves an element at a specific index from a list. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.index(["a", "b", "c"], 1) # Output: "b"

`join`

Description: Joins a list of elements into a string using a delimiter. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.join(["a", "b", "c"], ",") # Output: "a,b,c"

`len`

Description: Returns the length of a list. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.len([1, 2, 3]) # Output: 3

`dict_to_key_value_list`

Description: Converts a dictionary into a list of key-value pairs. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.dict_to_key_value_list({"a": 1, "b": 2}) # Output: ["a:1", "b:2"]

`dict_pop`

Description: Removes specified keys from a dictionary. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.dict_pop({"a": 1, "b": 2, "c": 3}, "a", "b") # Output: {"c": 3}

`dict_pop_prefix`

Description: Removes all keys that start with a specified prefix from a dictionary. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.dict_pop_prefix({"a_1": 1, "a_2": 2, "b_1": 3}, "a_") # Output: {"b_1": 3}

`dict_filter_by_prefix`

Description: Returns only the dictionary entries whose keys start with a specified prefix. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.dict_filter_by_prefix({"a_1": 1, "a_2": 2, "b_1": 3}, "a_") # Output: {"a_1": 1, "a_2": 2}

`dictget`

Description: Gets a value from a dictionary with a default fallback. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.dictget({"a": 1, "b": 2}, "c", "default") # Output: "default"

Date and Time Functions

`from_timestamp`

Description: Converts unix timestamp int, float or string to datetime object, with optional timezone option. Example:

steps:
  - name: example-step
    provider:
      type: console
      with:
        message: keep.from_timestamp(1717244449.0) # will print "2024-06-01 12:20:49+00:00"
        # or with timezone
        # message: keep.from_timestamp(1717244449.0, "Europe/Berlin") # will print "2024-06-01 14:20:49+02:00"

`utcnow`

Description: Returns the current UTC datetime. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.utcnow()

`utcnowtimestamp`

Description: Returns the current UTC datetime as a Unix timestamp (seconds since epoch). Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.utcnowtimestamp() # Output: 1704067200

`utcnowiso`

Description: Returns the current UTC datetime in ISO format. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.utcnowiso()

`to_utc`

Description: Converts a datetime string or object to UTC. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.to_utc("2024-01-01T00:00:00")

`to_timestamp`

Description: Converts a datetime object or string into a Unix timestamp. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.to_timestamp("2024-01-01T00:00:00")

`datetime_compare`

Description: Compares two datetime objects and returns the difference in hours. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.datetime_compare("2024-01-01T10:00:00", "2024-01-01T00:00:00") # Output: 10.0

`is_business_hours`

Description: Checks whether a given time falls within business hours. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.is_business_hours(
          time_to_check="2024-01-01T14:00:00Z",
          start_hour=8,
          end_hour=20,
          business_days=[0,1,2,3,4],
          timezone="America/New_York"
        )

JSON Functions

`json_dumps`

Description: Converts a dictionary or string into a formatted JSON string. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.json_dumps({"key": "value"})

`json_loads`

Description: Parses a JSON string into a dictionary. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.json_loads('{"key": "value"}')

Utility Functions

`get_firing_time`

Description: Calculates the firing duration of an alert in specified time units. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.get_firing_time(alert, "m", tenant_id="tenant-id") # Output: "15.0"

`add_time_to_date`

Description: Adds time to a date string based on specified time units. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.add_time_to_date("2024-01-01", "%Y-%m-%d", "1w 2d") # Output: "2024-01-10"

`timestamp_delta`

Description: Adds or subtracts a time delta to/from a datetime. Use negative values to subtract time. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        # Add 2 hours to the current time
        add_hours: keep.timestamp_delta(keep.utcnow(), 2, "hours")

        # Subtract 30 minutes from a specific datetime
        subtract_minutes: keep.timestamp_delta("2024-01-01T12:00:00Z", -30, "minutes") # Output: 2024-01-01T11:30:00Z

        # Add 1 week to a datetime
        add_week: keep.timestamp_delta("2024-01-01T00:00:00Z", 1, "weeks") # Output: 2024-01-08T00:00:00Z

`is_first_time`

Description: Checks if an alert with a given fingerprint is firing for the first time or first time within a specified period. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        # Check if this is the first time the alert is firing
        first_time: keep.is_first_time(alert.fingerprint, tenant_id="tenant-id")

        # Check if this is the first time the alert is firing in the last 24 hours
        first_time_24h: keep.is_first_time(alert.fingerprint, "24h", tenant_id="tenant-id")

`all`

Description: Checks if all elements in an iterable are identical. Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.all([1, 1, 1]) # Output: true

`diff`

Description: Checks if any elements in an iterable are different (opposite of all). Example:

steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.diff([1, 2, 1]) # Output: true

​Mathematical Functions

​add

​sub

​mul

​div

​mod

​exp

​fdiv

​eq

​String Functions

​uppercase

​lowercase

​capitalize

​title

​split

​strip

​replace

​remove_newlines

​encode

​slice

​List and Dictionary Functions

​first

​last

​index

​join

​len

​dict_to_key_value_list

​dict_pop

​dict_pop_prefix

​dict_filter_by_prefix

​dictget

​Date and Time Functions

​from_timestamp

​utcnow

​utcnowtimestamp

​utcnowiso

​to_utc

​to_timestamp

​datetime_compare

​is_business_hours

​JSON Functions

​json_dumps

​json_loads

​Utility Functions

​get_firing_time

​add_time_to_date

​timestamp_delta

​is_first_time

​all

​diff