Developer Portal
Developer Portal
Defining an Assistant

Defining an Assistant

Defining an Assistant

Extension Packs

An Extension Pack is a basic container and a metadata file, the metadata file represents a definition of both the extension itself and all the “services” or components that are held within this extension pack.

All components (like project templates, stores, etc) are really just metadata, but two of them will reference runnable code that is held within the extension pack. These are “Assistant Definitions” and “Actions”. The assistant definition is basically the structure of the assistant, its metadata and any specific components within the assistant.

All components within Kodexa when defined in metadata will have the following basic parts:

---
name: The User Displayed Name of the Component
slug: the slug to reference the component (no spaces, special chars)
description: A user displayed description
type: the type of the component i.e. extensionPack, assistant, action

This is common to all component metadata, and must be present. For an extension pack, we also include two other parts:

source:
  type: docker
  location: kodexa://extension-core:{version}

services:
  - ...

The source defines where the platform will find the container that we are building and deploying, typically this is an ECR repository. If you use kodexa:// then we will be picking up from the defined Kodexa repository for your implementation. The second is the services, a list of other components.

- slug: sftp-bulk-publisher
  metadataTag:
    - tag: Assistant
    - tag: Publishing
  description: Publish extracted data to an SFTP server on a schedule in bulk
  name: SFTP Bulk Publishing Assistant
  type: assistant
  template: true
  assistant:
    package: kodexa_core
    class: SFTPBulkPublishingAssistant
  schedulable: true
  reactive: false
  options:
    - name: host_name
      label: SFTP Hostname
      required: true
      type: string
      description: The hostname of the server

In the example above because we are defining an assistant we also have all the settings available to configure that assistant. For example, we define if the assistant can be scheduled, any options for assistant and if the assistant can react. These settings are used by the platform to do two things:

  • Determine which events should be able to trigger the assistant
  • Determine what to present to the user for configuration of the assistant
    • If not reactive don’t show the user the reactive tab in assistant configuration
    • If not schedulable don’t show the user the schedule tab in assistant configuration
    • If options are defined then show these options to allow the user to configure assistant

The other key information for the Assistant component metadata is that we have the assistant package and class.

  assistant:
    package: kodexa_core
    class: SFTPBulkPublishingAssistant

This tells the platform how to call the Python class that will implement the assistant. Let’s look at an example of the metadata, and then an example of the python class for an assistant.

- slug: example-assistant
  imageUrl: <https://images.kodexa.com/aws_200.png>
  schedulable: false
  metadataTag:
    - tag: Example
  description: '
  Example Assistant
  '
  name: Example Assistant
  type: assistant
  reactive: true
  assistant:
    package: my_package
    class: MyAssistant
  publicAccess: true
  template: true
  options:
    - name: message
      label: An example option
      required: false
      type: string
      default: ""
      description: This is just an example

The python class would need to match both the package and class name, and also include an init constructor that handles all the options that have been defined.