Rules

[info] Beta release

This is a beta release of rule based auto-creation and auto-completion of actions.

Rules to autocreate actions

If you want to autocreate actions, create a rule using POST on /actions/autocreate/ and pass an autocreate_rule JSON parameter.

This API works exactly the same way as POST on /actions/ except that:

  • It returns a rule instead of an action. An action is created later on successful execution of the rule
  • It takes additional compulsory parameter autocreate_rule
  • user_id is not compulsory and group_id is an additional optional parameter. You can create a rule to autocreate actions for a user or group or all users of your account. If no user_id or group_id is passed, by default the rule applies to all users. Note that you cannot pass both params.
HTTP Request

POST https://api.hypertrack.com/api/v2/actions/autocreate/

Parameters
Parameter Type Optional
user_id OR user_unique_id OR group_id UUID String/String/UUID String Optional
autocreate_rule JSON Required
autocomplete_rule JSON Optional
autocancel_after Integer Optional
unique_id String Optional. Send it only if the rule will create only one action
collection_id String Optional
type String Optional
metadata JSON Optional
expected_place OR expected_place_id JSON/UUID String Optional. Required if autocomplete_rule is of type geofence
expected_at ISO datetime string Optional. Required if autocomplete_rule is of type timefence with no at_label OR if autocreate_rule is of type timefence with no at_label

Actions may be autocreated:

  • At a set time, optionally with a recurring schedule
  • At a fixed duration before it is expected to complete
  • Upon entering/exiting a place, optionally from a list of places

At a set time, optionally with a recurring schedule

Use crontab type when you want to autocreate action(s) at a set time, optionally with a recurring schedule.

Parameters

Within the autocreate_rule parameter, send the following parameters.

Parameter Type Optional Description
type String Required Has to be crontab
crontab String Required Time & frequency at which the action(s) should be created. Learn more about crontab format here
Examples
  1. Auto-create a TRACK_THROUGH_THE_DAY action at 1pm everyday for a given user

    "type": "TRACK_THROUGH_THE_DAY",
    "user_id": "a78b19a4-0d01-4cb1-92a5-3e0e1017d960",
    "autocreate_rule": {
     "type": "crontab",
     "crontab": "0 13 * * * *"
    }
    
  2. Auto-create a visit action at 1pm tomorrow for all users

    "type": "VISIT",
    "autocreate_rule": {
     "type": "crontab",
     "crontab": "0 13 21 3 * 2018"
    }
    
  3. Auto-create a meetup action at 1pm on weekdays for a given group

    "type": "MEETUP",
    "group_id": "a78b19a4-0d01-4cb1-92a5-3e0e1017d960",
    "autocreate_rule": {
     "type": "crontab",
     "crontab": "0 13 * * 1-5 *"
    }
    

At a fixed duration before it is expected to complete

Use timefence type when you want to autocreate action(s) at a fixed duration before it is expected to complete.

Parameters

Within the autocreate_rule parameter, send the following parameters.

Parameter Type Optional Description
type String Required Has to be timefence
before Integer Optional Time (in seconds) before which you want to auto-create an action from expected_at time. Defaults to zero seconds
Examples
  1. Auto-create a visit action at expected_at time

    "type": "visit",
    "expected_at": "2018-02-20T08:00Z",
    "expected_place": {
     "address": "Folsom street, SF"
    },
    "autocreate_rule": {
     "type": "timefence",
    }
    
  2. Auto-create a delivery action 1 hour before its expected_at time

    "type": "delivery",
    "expected_at": "2018-02-20T08:00Z",
    "expected_place": {
     "address": "Folsom street, SF"
    },
    "autocreate_rule": {
     "type": "timefence",
     "before": 3600
    }
    

Upon entering/exiting a place, optionally from a list of places

Use geofence type when you want to autocreate action(s) upon your user(s) entering/exiting a place, optionally from a list of places.

Parameters

Within the autocreate_rule parameter, send the following parameters.

Parameter Type Optional Description
type String Required Has to be geofence
geofence JSON Required Array of geofence objects (object reference below)

Geofence objects have following parameters:

Parameter Type Optional Description
place GeoJSON Optional This can either be a point or a polygon. Use this in case the place for which you need a geofence is not already created. Read more
place_id UUID Optional This is the reference to a place which you have previously created, and now want to use to create a geofence.
radius Integer Optional Radius (in meters) of the geofence around the place mentioned above. Only applicable if place type is Point. Defaults to 100 meters.
transition String Optional Type of transition at which you want the geofence rule to trigger. Could be either enter or exit. Defaults to enter.
Examples
  1. Auto-create an action if any of your users reaches any of these places

    "autocreate_rule": {
     "type": "geofence",
     "geofence": [
         {
             "place_id" : "a78b19a4-0d01-4cb1-92a5-3e0e1017d960"
         },
         {
             "place_id" : "ededyga4-0d01-4cb1-92a5-3e0eduehdsy3",
             "radius" : 200
         },
         {
             "place_id" : "8debdee4-0d01-4cb1-92a5-3e0eeudhedh8",
             "radius" : 600
         }
     ]
    }
    
  2. Auto-create an action if any of your users exits/enter from any of these places

    "autocreate_rule": {
     "type": "geofence",
     "geofence": [
         {
             "place_id": "a78b19a4-0d01-4cb1-92a5-3e0e1017d960",
             "transition": "exit"
         },
         {
             "place_id": "ededyga4-0d01-4cb1-92a5-3e0eduehdsy3",
             "radius": 200,
             "transition": "enter"
         },
         {
             "place_id": "8debdee4-0d01-4cb1-92a5-3e0eeudhedh8",
             "radius": 600,
             "transition": "exit"
         }
     ]
    }
    
  3. Auto-create an action with place-object. (Thing to note here is, the creation of geofence depends upon place being geocoded. In case of failure, you might need to send the entire request body again, with rectified address, or place_id)

"autocreate_rule": {
    "type": "geofence",
    "geofence": [
        {
            “place”: {
                "location": {
                    "type": "Point",
                    "coordinates": [-122.40661, 37.78739]
                    }
                },
            "radius": 400,
            "transition": "exit"
        },
        {
            “place”: {
                "location": {
                    "type": "Polygon",
                    "coordinates": [[[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]]]
                    }
                },
            "transition": "exit"
        }
    ],
}

APIs to GET autocreate rules

Similar to all HyperTrack APIs, you can do a GET and DELETE on existing rules.

  • Get rule with a specific id GET https://api.hypertrack.com/api/v2/actions/autocreate/<id>/
  • Get all rules. Returns a list of rule objects GET https://api.hypertrack.com/api/v2/actions/autocreate/
  • Delete a rule. Tell us if you need this API, we will prioritise its development DELETE https://api.hypertrack.com/api/v2/actions/autocreate/<id>/

An action rule object (returned in above APIs) has following properties:

Property Type Description
user JSON Object of user for whom autocreate rule has been created. It is null if user_id parameter is not passed when creating the rule
group JSON Object of group for whom autocreate rule has been created. It is null if group_id parameter is not passed when creating the rule
id UUID String Unique identifier for the rule object set by hypertrack
created_at ISO datetime string Time when rule was created
autocreate_rule JSON As passed at creation
autocomplete_rule JSON Empty JSON if not passed at creation
autocancel_after Integer 180000 if not passed at creation
unique_id String Empty string if not passed at creation
collection_id String Null if not passed at creation
type String "task" if not passed at creation
metadata JSON Empty JSON if not passed at creation
expected_place JSON Object of place passed when creating action. null if not passed at creation
expected_at ISO datetime string null if not passed at creation

Rules to autocomplete actions

If you want to autocomplete actions, pass an additional autocomplete_rule JSON parameter when creating an action or when creating a rule to autocreate actions.

HTTP Request

POST https://api.hypertrack.com/api/v2/actions/

Actions may be autocompleted:

  • Immediately upon creation
  • At a set time
  • At a fixed duration after it is created or expected to complete
  • Upon entering/exiting a place

Immediately upon creation

Use timefence type when you want to autocomplete the action immediately after creation.

Parameters

See the parameters for create Action API. In addition to the standard parameters, you need to pass an additional compulsory parameter autocomplete_rule with following parameters inside the JSON.

Parameter Type Optional Description
type String Required Has to be timefence
at_label String Optional Has to be either created_at or expected_at. Defaults to expected_at
after Integer Optional Time (in seconds) after which you want to autocomplete the action from created_at or expected_at. Defaults to zero seconds
Examples
  1. Create action that completes at the time of creation
    "user_id": "a78b19a4-0d01-4cb1-92a5-3e0e1017d960",
    "autocomplete_rule": {
     "type": "timefence",
     "at_label": "created_at"
    }
    

At a set time

Use timestamp type when you want to autocomplete the action at a set time.

Parameters

See the parameters for create Action API. In addition to the standard parameters, you need to pass an additional compulsory parameter autocomplete_rule with following parameters inside the JSON.

Parameter Type Optional Description
type String Required Has to be timestamp
timestamp ISO datetime string Required Time at which the action should be completed
Examples
  1. Create delivery action that completes at 8am today
    "user_id": "a78b19a4-0d01-4cb1-92a5-3e0e1017d960",
    "type": "delivery",
    "autocomplete_rule": {
       "type": "timestamp",
       "timestamp": "2018-02-20T08:00Z"
    }
    

At a fixed duration after it is created or expected to complete

Use timefence type when you want to autocomplete the action immediately after creation of at a fixed duration after it is created or expected to complete.

Parameters

See the parameters for create Action API. In addition to the standard parameters, you need to pass an additional compulsory parameter autocomplete_rule with following parameters inside the JSON.

Parameter Type Optional Description
type String Required Has to be timefence
at_label String Optional Has to be either created_at or expected_at. Defaults to expected_at
after Integer Optional Time (in seconds) after which you want to autocomplete the action from created_at or expected_at. Defaults to zero seconds
Examples
  1. Create action that completes at expected_at time

    "user_id": "a78b19a4-0d01-4cb1-92a5-3e0e1017d960",
    "expected_at": "2018-02-20T08:00Z",
    "autocomplete_rule": {
     "type": "timefence"
    }
    
  2. Create action that completes 2 hours after action got created

    "user_id": "a78b19a4-0d01-4cb1-92a5-3e0e1017d960",
    "autocomplete_rule": {
     "type": "timefence",
     "at_label": "created_at",
     "after": 7200
    }
    

Upon entering/exiting a place

Use geofence type when you want to autocomplete the action upon your user entering/exiting a place, optionally from a list of places.

Parameters

See the parameters for create Action API. In addition to the standard parameters, you need to pass an additional compulsory parameter autocomplete_rule with following parameters inside the JSON.

Parameter Type Optional Description
type String Required Has to be geofence
place_label String Optional Has to be either created_place or expected_place. Defaults to expected_place
radius Integer Optional Radius (in meters) of the geofence around the expected_place. Defaults to 100 meters
transition String Optional Type of transition at which you want the geofence rule to trigger. Could be either enter or exit. Defaults to enter
Examples
  1. Create action that completes when user enters expected_place

    "user_id": "a78b19a4-0d01-4cb1-92a5-3e0e1017d960",
    "expected_place": {
     "address": "Folsom street, SF"
    },
    "autocomplete_rule": {
     "type": "geofence"
    }
    
  2. Create action that completes if user comes within 500 meters of the expected_place

    "user_id": "a78b19a4-0d01-4cb1-92a5-3e0e1017d960",
    "expected_place": {
     "address": "Folsom street, SF"
    },
    "autocomplete_rule": {
     "type": "geofence",
     "radius": 500
    }
    
  3. Create action that completes when user exits expected_place

    "user_id": "a78b19a4-0d01-4cb1-92a5-3e0e1017d960",
    "expected_place": {
     "address": "Folsom street, SF"
    },
    "autocomplete_rule": {
     "type": "geofence",
     "transition": "exit",
    }
    

Rules to autocreate & autocomplete actions

These are example of how you can pass JSON parameters autocomplete_rule and autocreate_rule while creating an action rule.

HTTP Request

POST https://api.hypertrack.com/api/v2/actions/autocreate/

Examples
  1. Auto-create a TRACK_THROUGH_THE_DAY action at 1pm for all of your users and complete that action at 9pm

    "type": "TRACK_THROUGH_THE_DAY",
    "autocreate_rule": {
     "type": "crontab",
     "crontab": "0 13 * * * *"
    },
    "autocomplete_rule": {
     "type": "timefence",
     "at_label": "created_at",
     "after": 28800
    }
    
  2. Auto-create an action when user enters this places and auto-complete the action upon exit.

    "autocreate_rule": {
     "type": "geofence",
     "geofence" : [
         {
             "place_id" : "a78b19a4-0d01-4cb1-92a5-3e0e1017d960",
             "radius" : 300
         }
     ]
    },
    "autocomplete_rule": {
     "type": "geofence",
     "place_label":"created_place",
     "transition": "exit"
    }
    
  3. Auto-create an action when any user in a group enters any place in the list, and auto-complete the action upon exit. Uses place_ids.

    "group_id": "a78b19a4-0d01-4cb1-92a5-3e0e1017d960",
    "autocreate_rule": {
     "type": "geofence",
     "geofence": [
         {
             "place_id": "a78b19a4-0d01-4cb1-92a5-3e0e1017d960",
             "radius": 300
         },
         {
             "place_id": "ededyga4-0d01-4cb1-92a5-3e0eduehdsy3",
         },
         {
             "place_id": "8debdee4-0d01-4cb1-92a5-3e0eeudhedh8",
             "transition": "exit"
         }
     ]
    },
    "autocomplete_rule": {
     "type": "geofence",
     "place_label":"created_place",
     "transition": "exit"
    }
    
  4. Auto-create an actions for multiple place objects, with multiple types (Point and polygon)

    “group_id”: “a78b19a4-0d01-4cb1-92a5-3e0e1017d960”,
    "autocreate_rule": {
     "type": "geofence",
     "geofence": [
         {
             “place”: {
                 "location": {
                     "type": "Point",
                     "coordinates" : [-122.40661, 37.78739]
                 }
             },
             "radius": 400,
             "transition": "exit"
         },
         {
             “place”: {
                 "location": {
                     "type": "Polygon",
                     "coordinates": [[[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]]]
                 }
             },
             "transition": "exit"
         }
     ]
    },
    "autocomplete_rule": {
     "type": "timefence",
     "at": "created_at",
     "after": 7200
    }
    

results matching ""

    No results matching ""