Trigger
  • Dark
    Light
  • PDF

Trigger

  • 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 Events - Resource

Events of which entities to listen to?
Resources are entities in Dataloop system: Item, Annotation, Dataset, Task, etc. Each resource is associated with an action to define a specific event for the trigger.
Once an event trigger occurs, the resource object is delivered as an input for the execution created. 

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 EnumAPI ValueDataloop EntityAvailable Actions (*) 
dl.TriggerResource.ITEMItemPlatform itemCreated,Updated,Deleted,Clone
dl.TriggerResource.DATASETDatasetPlatform datasetCreated,Updated,Deleted
dl.TriggerResource.ANNOTATIONAnnotationitem's annotationCreated,Updated,Deleted
dl.TriggerResource.ITEM_STATUSItemStatusItem's status
Updated**, taskAssigned
dl.TriggerResource.TASKTaskPlatform task
Created,Updated,Deleted,statusChanged
dl.TriggerResource.ASSIGNMENT
Assignment
Platform assignment
Created,Updated,Deleted,statusChanged


(*) Your function can be triggered by the following actions when taken over a resource (a specific resource must be set!):

  1. Created: run your function over any newly created resource.
  2. Update: run your function over any updated resource. See (**) for more details regarding "itemStatus.Updated".
  3. Deleted: run your function over any deleted resource.
  4. Clone: run your function over every cloned item.
  5. taskAssigned: once an item is assigned to a task, run the function over this item. To use this event, set the following trigger: "ItemStatus.TaskAssigned".
  6. statusChanged: once a task/assignment status is changed, run the function over this task/assignment (task 'completed', assignment 'done').


(**) Use the trigger "itemStatus.Updated" to run your function over items once their status is changed within a task context ('approved', 'discard', etc.).


Trigger Events - Action

What event action types are available?

Actions are the events that will trigger the function .
For further explanation regarding the actions, read the explanations above (*).


dl EnumAPI ValueAvailable Modes
1dl.TriggerAction.CREATEDCreatedOnce
2dl.TriggerAction.UPDATEDUpdatedOnce, Always
3dl.TriggerAction.DELETEDDeletedOnce
4dl.TriggerAction.CLONECloneOnce
5dl.TriggerAction.STATUS_CHANGEDstatusChangedOnce, Always
6dl.TriggerAction.TASK_ASSIGNEDtaskAssignedOnce, Always


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 Enumdl.TriggerExecutionMode.ONCE
dl.TriggerExecutionMode.ONCEOnce
dl.TriggerExecutionMode.ALWAYSAlways

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

  • Creating a function that adds items to a folder, while an event trigger "item.created" is set for this function.
  • Creating a function that updates items, while an event trigger "item.updated" with execution_mode='always' is set for this function. 
The function will be triggered again and again when implementing the above functions.


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