Trigger

Print
Share
Dark

Light
PDF

The Dataloop FaaS enables you to register Functions to events in the system.
Use the Triggers entity for the registration.
A Trigger contains a project on which it monitors events, a resource type, the action that happened to the resource, a DQL (The Data Query Engine) filter that checks whether or not to invoke the operation based on the resource JSON, and an operation.

Currently, the only supported operation is the creation of an execution.

Trigger Resource

Events of which entities to listen to?
Resources are any entity in our system: Item, Annotation, Dataset, etc.
The resource object will also be the execution input.

Note that you can only have one resource per trigger.
If you wish to have more than one, use a manual execution from a new function.

dl Enum	API Value	Dataloop Entity	Available Actions
dl.TriggerResource.ITEM	Item	Platform item	Created,Updated,Deleted
dl.TriggerResource.DATASET	Dataset	Platform dataset	Created,Updated,Deleted
dl.TriggerResource.ANNOTATION	Annotation	item's annotation	Created,Updated,Deleted
dl.TriggerResource.ITEM_STATUS	ItemStatus	item status change on a task (completed, discarded...)	Updated
dl.TriggerResource.TASK	Task	Task creation	Created

Trigger Action

What event type?

Actions are the events that will trigger the function. An “Update” will run on every resource update. “Created” will run on every creation of resources. In addition, “Deleted” and “ItemStatus” are also available.

dl Enum	API Value	Available Modes
dl.TriggerAction.CREATED	Created	Once
dl.TriggerAction.UPDATED	Updated	Once,Always
dl.TriggerAction.DELETED	Deleted	Once

Trigger Execution Mode

Some events, such as item updates, can happen more than once on the same entity. Trigger execution mode defines those repeating events that will trigger the service every time they happen, or only on the first time they happen.

Once - the function will only run once when triggered. For instance, for an "item" resource and an "Updated" action, the function will only work on the first updated item.
Always - the function will run each time when triggered. For instance, for an "item" resource and an "Updated" action, the function will run for every updated item.

dl Enum	dl.TriggerExecutionMode.ONCE
dl.TriggerExecutionMode.ONCE	Once
dl.TriggerExecutionMode.ALWAYS	Always

Be careful not to loop a trigger event.
Known examples:

Functions that will add an item to a folder that has item.created trigger.
When you create a trigger item.updated action and execution_mode='always',
and then update the item inside the service, it will be triggered again and again.

trigger

Trigger JSON

{
  "name": "service-name",  
  "packageName": "default_package",  
  "packageRevision": "latest",  
  "runtime": {
    "gpu": false,           
    "replicas": 1,            
    "concurrency": 6,      
    "runnerImage": "" 
  },
    "triggers": [
      {
        "name": "trigger-name",
        "filter": {
          '$and': [{'dir': '/train'}, {'hidden': False}, {'type': 'file'}]},
        "resource": "Item",
        "actions": [
          "Created"
        ],
        "active": true,
        "function": "run",
        "executionMode": "Once"
      }
    ],               
    "initParams": {},                     
    "moduleName": "default_module"    
}

Trigger at Specified Time Patterns

Dataloop FaaS enables you to run functions at specified time patterns with constant input using the Cron syntax.

In the Cron trigger specification, you specify when you want the trigger to start, when you want it to end, the Cron spec specifying when it should run, and the input that should be sent to the action.

Cron: Cron spec specifying when it should run, more information at https://en.wikipedia.org/wiki/Cron.

# start_at: iso format date string to start activating the cron trigger 
# end_at: iso format date string to end the cron activation 
# inputs: dictionary "name":"val" of inputs to the function 
import datetime
up_cron_trigger = service.triggers.create(function_name='my_function',
                                          trigger_type=dl.TriggerType.CRON,
                                          name='cron-trigger-name',
                                          start_at=datetime.datetime(2020, 8, 23).isoformat(),
                                          end_at=datetime.datetime(2024, 8, 23).isoformat(),
                                          cron="0 5 * * *")

Triggers Examples

Trigger for Items Uploaded to Directory /Input

filters = dl.Filters(field='dir', values='/input')
trigger = service.triggers.create(function_name='run',
                                  resource=dl.TriggerResource.ITEM,
                                  actions=dl.TriggerAction.CREATED,
                                  name='items-created-trigger',
                                  filters=filters)

Trigger for Items Updated in Project

trigger = service.triggers.create(function_name='run',
                                  resource=dl.TriggerResource.ITEM,
                                  actions=dl.TriggerAction.UPDATED,
                                  name='items-updated-trigger')

Trigger for Annotated Video Items that are Being Updated

filters = dl.Filters(field='annotated', values=True)
filters.add(field='metadata.system.mimetype', values='video/*')
trigger = service.triggers.create(function_name='run',
                                  resource=dl.TriggerResource.ITEM,
                                  actions=dl.TriggerAction.UPDATED,
                                  name='items-updated-trigger',
                                  filters=filters)

Trigger for Datasets that are Being Updated

trigger = service.triggers.create(function_name='run',
                                  resource=dl.TriggerResource.DATASET,
                                  actions=dl.TriggerAction.UPDATED,
                                  name='dataset-updated-trigger')

Trigger for Annotations Created from Box Type

filters = dl.Filters(field='type', values='box', resource=dl.FiltersResource.ANNOTATION)
trigger = service.triggers.create(function_name='run',
                                  resource=dl.TriggerResource.ANNOTATION,
                                  actions=dl.TriggerAction.CREATED,
                                  name='annotation-created-trigger',
                                  filters=filters)

Trigger for Annotations Updates of Label "DOG"

filters = dl.Filters(field='label', values='DOG',resource=dl.FiltersResource.ANNOTATION)
trigger = service.triggers.create(function_name='run',
                                  resource=dl.TriggerResource.ANNOTATION,
                                  actions=dl.TriggerAction.CREATED,
                                  name='annotation-created-trigger',
                                  filters=filters)

Trigger for Status Change on a Task(completed/approved/discarded)

trigger = service.triggers.create(function_name='run',
                                  execution_mode=dl.TriggerExecutionMode.ALWAYS,
                                  resource=dl.TriggerResource.ITEM_STATUS,
                                  actions=[dl.TriggerAction.UPDATED],
                                  name='item-updated-status')

Adding a trigger to a service will add that trigger to all of the project's datasets.
If you wish to use a trigger on a specific dataset, add filters when creating the trigger:

filters = dl.Filters(field='datasetId', values='your-dataset-id')
trigger = service.triggers.create(function_name='your-function-name',
                                  resource=dl.TriggerResource.ITEM, #as an example
                                  actions=dl.TriggerAction.CREATED, #as an example
                                  name='your-trigger-name',
                                  filters=filters)

What's Next

Table Of Contents

Trigger Resource
Trigger Action
Trigger Execution Mode
Trigger JSON
Trigger at Specified Time Patterns
Triggers Examples