WEB API

for end-users

Monitor - Set Up

Edit
Info: Stellantis End User API for ex Groupe PSA brands (Citroën, DS, Peugeot, Opel and Vauxhall) is not publicly available.

Post Monitor Request #

1. Overview #

Here is an overview of an HTTP request intended to create a monitor.

We will then take a closer look to the body request.

POST | https://api.groupe-psa.com/connectedcar/v4
/user/vehicles/{id}/monitors 
1
2
3
4
5
6
7

$ curl \
  --POST \
  --url 'https://api.groupe-psa.com/connectedcar/v4/user/vehicles/{id}/monitors' \
  --data 'client_id=<client_id>' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'x-introspect-realm: <realm>' \
  --data '<check out HTTP body>' \

1
2
3
4
5
6

{
  "label": "monitor-name",
  "subscribeParam": { },
  "extendedEventParam": [ ],
  "triggerParam": { }
}

First, we will have a look at the callback configuration: “subscribeParam” and “extendedEventParam”.

Then we will see how to create triggers and triggering policy for your monitors with “triggerParam”.

At the end we will see examples of monitor configuration.

2. Callback Configuration #

Firstly, you have to configure your monitor to send an HTTP callback to your webhook when it is triggered. This is the models explaining how to configure the callback:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

{
   "label": "",
   "subscribeParam": {
      "retryPolicy": {
         "policy": "None",
         "maxRetryNumber": 0,
         "retryDelay": 0
         },
      "batchNotify": {
         "size": 0,
         "timeWindow": 0
      },
      "callback": {
         "webhook": {
            "target": "https://my.post.callback",
            "name": "My_Webhook",
            "attributres": [
               {
               "type": "Header",
               "key": "X-Vehicle_Id",
               "value": "$vin"
               },
               {
               "type":"Header",
               "key":"Authorization",
               "value":"Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
               }
            ]
         }
      },
      "refreshEvent": 100
   },
   "extendedEventParam": [
      "vehicle.alerts",
      "vehicle.status"
   ],
   "triggerParam": { }
}

Below is a description of the JSON models explaining how to configure the callback. Please refer to API Reference models to read a full description of the callback configuration.

MonitorParameter: this JSON object allow you to configure your monitor callback:

  • retryPolicy: this where you set retry policy, it’s in case your webhook has not received the callback, whatever is the reason.
  • batchNotify: you can set this object in case you need to receive notification in batch instead of one by one.
  • callback>webhook: this required object is where you will set the address and name of you webhook. This is also where you can customize the HTTP notification (example: for authentication purpose).
  • refreshEvent: if the trigger is satisfied, refreshEvent define the period between two re-checking.
  • extendedEventParam: this events table allow you to send extra vehicle data in the notification.

3. Event Triggering #

3.1 Triggers

Let’s have a look at how to create monitor triggers. First, you have to decide what will be the triggers of your monitor.

As explained before triggers can be on Zone, Time and/or Data basis.

  • Zone: a vehicle go in/out a circle area.
  • Time: a vehicle is being used within a time interval
  • Data: choose a sensor and set a triggering when the value is: equals to/greater than/lower than/include in/or changing.

Choose and configure the triggers you need as a JSON table:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

{
   "label": "",
   "subscribeParam": { }
   "triggerParam": {
      "triggers": [
         {
            "name": "z1",
            "zone": {
               "transition": "Out",
               "circle": {
               "radius": 20,
               "center": {
                  "longitude": 2.333333,
                  "latitude": 48.866667
                  }
               }
            },
            "name": "t1",
            "time": {
               "times": [
                  {
                     "recurrence": "Daily",
                     "start": "PT14H30M",
                     "occurence": {
                        "day": [
                        "Mon"
                        ]
                     },
                     "duration": "PT04H30M"
                  }
               ],
               "timeZone": "Europe/Paris"
            },
            "name": "o1",
            "data": {
               "data": "Vehicle.odometer",
               "op": "greaterThan",
               "value": [
               "75"
               ]
            }
         }
      ],
      "boolExp": ""
   }
}

For the entire documentation, look closer at [API Reference>MonitorParameter>triggerParam>triggers. This is where you can find the entire list of available triggers.

Deprecated: timeZoneTrigger and dataTrigger.

MonitorParameter>triggerParam>timeZoneTrigger and MonitorParameter>triggerParam>dataTriggers are deprecated according to the most up to date specification.

This is the old way of setting a triggering policy, it'is less performant as it allows only "AND relationship" between triggers. Because of retro-compatibility purposes it's still available, but we recommend you strongly to use the new data schema.

3.2 Boolean Expression

Once you have selected your triggers, you’ll have to combine them together to create a triggering policy. To do so, you will use boolean expression. Using boolean expression allow you to have various triggering policies in one monitor.

Let’s see how to use this boolean expression:

Gramar: Here is the list of available operands for monitors configuration.

1
2
3
4

exp::= exp '&' exp
       | exp '|' exp
       | (exp)
       | !exp
  • AND: exp1 & exp2 if both conditions have to be triggered
  • OR: exp1 | exp2 if at least one condition have to be triggered
  • PARENTHESIS: exp1 | (exp2 & exp3) to prioritize an expression over another
  • NOT: !exp1 if the condition have not to be triggered

This is an example of boolean expression, where z1, z2, t1, t2, o1, o2, o3 are trigger names as seen before:

1
2
3
4
5
6
7
8

{
   "label": "",
   "subscribeParam": { }
   "triggerParam": {
      "triggers": [ ],
      "boolExp": "((z1 & t1) | (z2 & !t1) | (o1 & z1) | (o2 & (z1 | t2))  | (o3 & (z1 | z2)))"
      }
}

In this boolean expression, the monitor will notify your webhook in all these situations:

  • (z1 & t1) = z1 AND t1 are being triggered
  • (z2 & !t1) = z2 is triggered AND t1 is NOT triggered
  • (o1 & z1) = o1 is triggered AND z1 is triggered
  • (o2 & (z1 | t2)) = o2 is triggered AND either z1 OR t2 is triggered
  • (o3 & (z1 | z2)) = o3 is triggered AND either z1 OR z2 is triggered

4. Examples #

4.1 Autonomy

This request ask to create an “IDF Zone monitor With Data Triggering:[vehicle.energy.electric.level]” monitor with the following parameters:

  • It will be refreshed every 600s if the event is still triggered.
  • If the callback notification is not received, the request will be sent again every 120s until it’s properly delivered.
  • The callback will be sent once 10 callback notifications are ready to be sent or 300s after triggering.
  • The callback will be sent to your http://my.dn/monitors/cb1 webhook with the vin of the vehicle as a query param and your Basic authentication in HTTP header.
  • In the JSON response, you will find the alerts and status of the corresponding vehicle.
  • This monitor is triggered if the vehicle’s electric autonomy is lower than 50% AND either is out of an 20km radius circle of the center of Paris, France OR on Mondays.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

{
   "label":"IDF Zone monitor With Data Triggering:[vehicle.energy.electric.level] OR on Mondays",
   "subscribeParam":{
      "refreshEvent":600,
      "retryPolicy":{
         "policy":"Always",
         "maxRetryNumber":3,
         "retryDelay":120
      },
      "batchNotify":{
         "size":10,
         "timeWindow":300
      },
      "callback":{
         "target":"http://my.dn/monitors/cb1",
         "name":"HTTP_CB",
         "attributes":[
            {
               "type":"Query",
               "key":"vin",
               "value":"$vin"
            },
            {
               "type":"Header",
               "key":"Authorization",
               "value":"Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
            }
         ]
      }
   },
   "extendedEventParam":[
      "vehicle.alerts",
      "vehicle.status"
   ],
   "triggerParam":{
      "triggers": [
      {
         "name": "outOfParis",
         "zone": {
            "transition": "Out",
            "circle": {
               "radius": 20,
               "center": {
               "longitude": 2.333333,
               "latitude": 48.866667
               }
            }
         },
         "name": "onMonday",
         "time": {
            "times": [
               {
               "recurrence": "Daily",
               "start": "PT14H30M",
               "occurence": {
                  "day": [
                     "Mon"
                  ]
               },
               "duration": "PT04H30M"
             }
            ],
            "timeZone": "Europe/Paris"
         },
         "name": "batteryIsLow",
         "data": {
          "data": "vehicle.energy.electric.level",
          "op": "lowerThan",
          "value": [
            "50"
            ]
        }
      }
    ],
    "boolExp": "((outOfParis & (batteryIsLow | onMonday)"
  }
}

4.2 Heatwave

Another example monitor to detect heatwave:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

{
   "label":"IDF Zone monitor With Data Triggering:[environment.air.temp]",
   "subscribeParam":{
      "refreshEvent":600,
      "retryPolicy":{
         "policy":"Always",
         "maxRetryNumber":3,
         "retryDelay":120
      },
      "batchNotify":{
         "size":10,
         "timeWindow":300
      },
    "callback": {
      "webhook": {
        "target": "https://my.post.callback",
        "name": "My_Webhook",
        "attributres": [
            {
            "type": "Header",
            "key": "X-Vehicle_Id",
            "value": "$vin"
            },
            {
               "type":"Header",
               "key":"Authorization",
               "value":"Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
            }
         ]
      }
    },
   "extendedEventParam":[
      "environment.air.temp"
   ],
   "triggerParam":{
      "triggers": [
         {
         "name": "outOfParis",
         "zone": {
            "transition": "Out",
            "circle": {
               "radius": 20,
               "center": {
               "longitude": 2.333333,
               "latitude": 48.866667
               }
            }
         },
        "name": "outsideTemperatureIsHight",
        "data": {
          "data": "environment.air.temp",
          "op": "greaterThan",
          "value": [
            "30"
          ]
        }
      }
    ],
    "boolExp": "(outOfParis & outsideTemperatureIsHight)"
  }
}

This request ask to create a heatwave monitor triggered inside the city of Paris, if the temperature is greater than 30 °C.

4.3 Merge Monitors

In place of having two monitors like example 4.1 and 4.2 you can use boolean expression to merge those 2 examples in only one monitor:

1
2
3
4
5
6
7
8
9
10
11
12
13

{
   "label": "",
   "subscribeParam": { }
   "triggerParam": {
      "triggers": [
         { "name": "outOfParis" },
         { "name": "outsideTemperatureIsHight" },
         { "name": "outOfParis" },
         { "name": "onMonday" },
         { "name": "batteryIsLow" }
      ],
      "boolExp": "((outOfParis & (batteryIsLow | onMonday) | (outOfParis & outsideTemperatureIsHight))"
}

Post Monitor Response #

Here is an example of HTTP response after POSTING a new monitor.

1
2
3
4

{
   "monitorId":"c7eeaafdf0ab9683d5a1b8d51572014996540m0021",
   "status":"Created"
}

The monitor have been created with id=c7eeaafdf0ab9683d5a1b8d51572014996540m0021. This id will be sent with every notification to your webhook.