Quickstart: Run Your First Workflow

To create a secret using the CLI, use the following CLI command:

admyral secret set secret_name --value key1=value1 --value key2=value2

For our quickstart, navigate in your terminal to your admyral repository and enter the following but replacing your_copied_virus_total_api_key with your copied API key:

admyral secret set virus_total --value api_key=your_copied_virus_total_api_key

We recommend to setup a Github project for managing your workflows. You can check out our Quickstart Github Repo (opens in a new tab). Feel free to clone it and use it for your setup or simply just get inspired.

Open your project with your favorite IDE and create a new Python file named virus_total_workflow.py for the workflow. Within this newly created file, your new workflow automation is being created using Python code.

Let's start with building your first workflow function. This function has the @workflow decorator and defines the the control flow of our workflow automation.

from admyral.workflow import workflow
from admyral.typings import JsonValue
 
@workflow
def virus_total_workflow(payload: dict[str, JsonValue]):
    # will be completed soon

The workflow function must always have the parameter payload: dict[str, JsonValue] defined. No other parameters for the workflow function are allowed.

The function name virus_total_workflow, also called workflow name, is used as an identifier for your workflow and must be unique across all your workflows.

Additionally, we need the corresponding imports. In this case, it is from admyral.workflow import workflow for the workflow decorator as well as from admyral.actions import virus_total_analyze_url for the integration action. For the latter, we are using the pre-built integration to analyze a URL which takes a URL as a string such as www.example.org and returns a JSON. The return value is the regular return value you'd receive from the VirusTotal Scan URL API (opens in a new tab). With this knowledge, we can now create the workflow using plain Python:

from admyral.workflow import workflow
from admyral.typings import JsonValue
from admyral.actions import virus_total_analyze_url
 
@workflow
def virus_total_workflow(payload: dict[str, JsonValue]):
    virus_total_analyze_url(payload["url"])

To use our previously stored secret for VirusTotal, we add the secret mapping secrets={"TOOL_SECRET": "secret_name"} as the last argument of an integration. In our case, it would look like the following:

from admyral.workflow import workflow
from admyral.typings import JsonValue
from admyral.actions import virus_total_analyze_url
 
@workflow()
def virus_total_workflow(payload: dict[str, JsonValue]):
    virus_total_analyze_url(
        url=payload["url"],
        secrets={"VIRUS_TOTAL_SECRET": "virus_total"}
    )

Performing the access payload["url"] implies that we always expect a JSON body which contains a field called url be sent to the webhook. For example:

{
    "url": "www.example.org"
}

For more information about secrets, please refer to Secrets Management.

Now, we add a trigger and a description (optional) to the workflow automation. Admyral supports event-based triggers (webhook) as well as scheduled triggers. Either has to be imported from admyral.workflow import Webhook for event-based execution or from admyral.workflow import Schedule for a scheduled workflow execution. You can also omit defining a trigger since you can always execute your workflows using manual execution via the CLI (admyral workflow trigger ...) or in the Admyral UI. In this quickstart, we opt to create a webhook:

from admyral.workflow import workflow, Webhook
from admyral.typings import JsonValue
from admyral.actions import virus_total_analyze_url
 
@workflow(
    description="Analyze a URL using VirusTotal",
    triggers=[Webhook()]
)
def virus_total_workflow(payload: dict[str, JsonValue]):
    virus_total_analyze_url(
        url=payload["url"],
        secrets={"VIRUS_TOTAL_SECRET": "virus_total"}
    )

Now, you have created the workflow. The last step is to push the workflow to the Admyral infrastructure. We use the following push command from the CLI to push the workflow:

admyral workflow push workflow_name -f path_to_your_workflow_file.py

If you saved your workflow in workflows/virus_total_workflow.py, the command is:

admyral workflow push virus_total_workflow -f workflows/virus_total_workflow.py

You can open the Admyral UI by visiting http://localhost:3000 (opens in a new tab) in your browser. If a custom port was defined using ADMYRAL_WEB_PORT, use the defined port number instead of 3000. There, you should find the workflow and can inspect the workflow inside the No-Code editor.

Activate the workflow

To activate a workflow type in the CLI:

admyral workflow activate your_workflow_name

As we called the workflow function virus_total_workflow, use the following command:

admyral workflow activate virus_total_workflow

Execute the workflow

Upon activation, the workflow can be executed. The CLI command to trigger a workflow is:

admyral workflow trigger your_workflow_name

So similar to above, the command to use is:

admyral workflow trigger virus_total_workflow --payload '{
    "url": "www.example.org"
}'