Rules

Use rules to autocreate and/or autocomplete actions.

API 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 Description
user_id OR user_unique_id OR group_id UUID String/String/UUID String Optional id or unique_id of an existing user, or group
autocreate_rule JSON Required The only required parameter to autocreate the action rule
autocomplete_rule JSON Optional Rules to autocomplete action based on time or place.
autocancel_after Integer Optional Action will automatically cancel after those many hours if not completed prior. Use this to automatically clean up actions. Defaults to 24 hours after expected_at if available; else 24 hours after eta_at_creation if you had set expected_place; else 24 hours after created_at.
unique_id String Optional Send it only if the rule will create only one action
collection_id String Optional Identifier for the collection of actions in your system
type String Optional Type of action, e.g., meetup, pickup, delivery, dropoff, visit, sos, stopover, task or any other custom type
metadata JSON Optional Custom key-values pairs in your system that you want to associate with the action. E.g. Customer - John Smith
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:

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.
    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

Sample JSON to autocreate

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. (Note that 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"
        }
    ],
}

API to create an action that autocompletes

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:

Sample JSON to autocomplete

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",
    }
    

API to autocreate actions that autocomplete

Its the same API as the one used to autocreate an action. You need to pass the JSON parameters autocomplete_rule and autocreate_rule while creating the action rule.

HTTP Request

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

Sample JSON to autocreate and autocomplete

Track through the day

You can track a user through your work day by autocreating at a specific time every day and autocompleting at a specific time on that day. The specified timestamps are in UTC. You can create such an action through the dashboard settings too.

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

    "type": "TRACK_THROUGH_THE_DAY",
    "autocreate_rule": {
     "type": "crontab",
     "crontab": "0 0 * * * *"
    },
    "autocomplete_rule": {
     "type": "timefence",
     "at_label": "created_at",
     "after": 86400
    }
    
  2. 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
    }
    

Upon entering/exiting a place

Examples
  1. Auto-create an action when user enters a place 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"
    }
    
  2. 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"
    }
    
  3. 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 ""