Skip to content

Custom Actions

Custom Action Messages

You can use Custom Actions to enable communication between two Applications on either the same cluster or across different clusters.

The Applications that can use this feature can be Kelvin SmartApps™, Docker Apps, Import or Export Connections.

Note

To understand the purpose of Custom Actions or view the overall structure of how they work, check out the documentation in the overview page here.

Produce Custom Action

Declarations

To ensure the Custom Action being sent is handled properly, the app.yaml outputs needs to be declared:

Note

You can choose any name for the type.

This is how the Custom Action Manager chooses which Consumer Application (Executor) will receive the Custom Action object.

app.yaml Example
1
2
3
custom_actions:
  outputs:
    - type: custom-action-name

The Custom Action Object supports the following attributes :

Attribute Required Default Value Description
resource required N/A The KRNAsset that this Custom Action is meant for.
type required N/A The name of Custom Action.
title required N/A Title of the Custom Action
description required N/A Description details of the Custom Action
expiration_date required N/A Absolute datetime or a timedelta (from now) when the Control Change will expire.
payload required N/A The custom information of the Custom Action that will be required by the Consumer Application
trace_id optional N/A A custom id for tracking the Custom Action status

Example

In this example we will create a Producer Application that will;

  1. Package the email details into a Custom Action Object
  2. Send the Custom Action object directly to the Consumer Application (Executor) for processing.
  3. Package the Custom Action object in a Recommendation and publish the "Recommendation with Custom Action" to the Kelvin UI for approval. (Typically, you would choose either direct sending or publishing with a Recommendation—not both.)

app.yaml

app.yaml Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
spec_version: 5.0.0
type: importer            # Any app type can handle and/or publish custom actions.

name: hello-app
title: Hello App
description: Lorem ipsum dolor sit amet, consectetur adipiscing elit
version: 1.0.0

custom_actions:
  outputs:
    - type: email

  ...

Publisher Application

main.py Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
import asyncio
from datetime import timedelta, datetime

from kelvin.application import KelvinApp
from kelvin.krn import KRNAsset
from kelvin.message import Recommendation, CustomAction

asset = KRNAsset("air-conditioner-1")

app = KelvinApp()

async def main() -> None:
    asset = KRNAsset("air-conditioner-1")

    ###
    # Directly
    #
    action = CustomAction(resource=asset,
    type="email",
    title="Recommendation to reduce speed",
    description="It is recommended that the speed is reduced",
    expiration_date=datetime.now() + timedelta(hours=1),
    payload={
        "recipient": "operations@example.com",
        "subject": "Recommendation to reduce speed",
        "body": "This is the email body",
    })
    app.publish(action)

    ###
    # Or embedded the Custom Action into a Recommendation   
    #

    rec = Recommendation(resource=asset,
    type="Reduce speed",
    actions=[action],
    )
    app.publish(rec)

if __name__ == "__main__":
    asyncio.run(main())

Consume Custom Action

This is usually a Kelvin SmartApp™ and not an Import or Export Application.

You can find full documentation for creating a Custom Action Executor (Consumer) Application in the Develop SmartApps section under Consume.