Create Geolocations and Trigger Geomatch

A geolocation space is needed before creating a geolocation. To create a geolocation space, you can use the UIs or APIs. In this case, let us use the APIs to define a geolocation space of geometry type point. You can refer to the Create Geolocations and Configure Geofence tutorial for creating geolocations and spaces using the UI.

1. Create geolocation space.

   You can get the API endpoints for the services from the service key that you generated for your subaccount. In the Postman collection (the Geomatch collection you downloaded from the GitHub link), execute the Step 3.1: Create a point space request by providing a unique name for the geolocation space to avoid conflicts (for example, Healthcare 0001). However, if you want to try out, below is the sample API endpoint and payload. Replace sap-iot-noah-live-geolocation-runtime.cfapps.eu10.hana.ondemand.com with the geolocation domain from the service key you generated for your subaccount in the below URL.

   https://sap-iot-noah-live-geolocation-runtime.cfapps.eu10.hana.ondemand.com/geolocation/v1/Spaces
   

   [{
   	"SpaceName": "Healthcare 0001",
   	"Geometry": {
   		"Type": "Point"
   	},
   	"Description": "Healthcare Point Space",
   	"ParentSpaceId": null
   }]
   

   In the above example, we have defined the geometry type as point.

2. Fetch the SpaceId.

   You can now get the SpaceId for the above space by checking the Locations key in the Response Headers. Select the alphanumeric string after ‘/Spaces’ for getting the ID. Update this SpaceId to point_space_id in the Postman environment variables for future use.

   

3. Read the point space.

   Read the above space with a GET request to the same endpoint, but with the SpaceId as the parameter. Use the Postman collection (Geomatch collection) and execute Step 3.2: Read point space request.

   However, if you want to try out, below is the sample API endpoint. Replace sap-iot-noah-live-geolocation-runtime.cfapps.eu10.hana.ondemand.com with the geolocation domain from the service key you generated for your subaccount in the below URL. Use the SpaceId you retrieved above in place of ee2002d6-57d6-4553-b9b5-eff164yuw3d.

   https://sap-iot-noah-live-geolocation-runtime.cfapps.eu10.hana.ondemand.com/geolocation/v1/Spaces/ee2002d6-57d6-4553-b9b5-eff164yuw3d
   

A location for the business object (business location) is needed for associating a thing to it using the manual geomatch request. A business location is a point of interest geolocation. Before triggering the geomatch request, do the following changes in the payload (Body tab in Postman):

1. Generate a GUID for the business location.

   Manual geomatch works for geolocations with BusinessObjectGUID. For the BusinessObjectGuid, generate a 32 character GUID using the GUID Generator. Update the generated GUID to the BusinessObjectGuid Postman environment variable.

2. Update the coordinates.

   The format of the coordinates in the payload is as below:

      "coordinates":[
           longitude,
           latitude
           ]
   

   You can get the coordinates for an address using https://www.gps-coordinates.net/. You must update the latitude and longitude values you are using in the latitude and longitude Postman environment variables for future use.

3. Create business location.

   Provide a unique name for GeoLocationName and BusinessObjectDisplayName(for example, University Medical Center Heidelberg POI 0001) in the payload to avoid conflicts and trigger the Step 4.1: Create Business Location request from the Postman collection (Geomatch collection).

   However, if you would like to try out, below is the sample API endpoint and payload. Replace sap-iot-noah-live-geolocation-runtime.cfapps.eu10.hana.ondemand.com with the geolocation domain from the service key you generated for your subaccount in the below URL and trigger a POST request.

   https://sap-iot-noah-live-geolocation-runtime.cfapps.eu10.hana.ondemand.com/geolocation/v1/GeoLocations
   

   [{
         "Type":"Feature",
         "Properties":{
            "ParentGeoLocationId":null,
            "ExternalId":null,
            "SpaceId":"ee2002d6-57d6-4553-b9b5-eff164yuw3d",
            "GeoLocationName":"University Medical Center Heidelberg POI 0001",
            "BusinessObjectType":"Hospital",
            "BusinessObjectGuid":"b3f24275-c351-4f1e-8389-a94ed431f097",
            "BusinessObjectDisplayName":"University Medical Center Heidelberg 0001",
            "IsGeoFence":false,
            "HasChild":false,
            "Descriptions":[
               {
                  "Locale":"en",
                  "Label":"University Medical Center Heidelberg"
               }
            ],
            "Addresses":[
               {
                  "Locale":"en",
                  "Address":{
                     "House":"672",
                     "Street":"Im Neuenheimer Feld",
                     "CityDistrict":null,
                     "City":"Heidelberg",
                     "District":null,
                     "RegionCode":"BW",
                     "Region":"Baden-Wurttemberg",
                     "CountryCode":"DE",
                     "Country":"Germany",
                     "PostalCode":"69120"
                  }
               }
            ]
         },
         "Geometry":{
            "type":"Point",
            "coordinates":[
               8.671045303344727,
               49.41686867456883
            ]
         },
         "SensitivityCategory":null
      }]
   

   As a user, you can choose to define a geolocation as personal information, personal sensitive information or none. You can define the SensitivityCategory as com.sap.appiot.security:spi for personal sensitive information, com.sap.appiot.security:pii for personal information or null. This is with respect to the Global Data Protection Regulation (GDPR).

4. Read the business location.

   You can now get the GeoLocationID for the above geolocation by checking the Locations key in the Response Headers. Select the alphanumeric string after /GeoLocations for getting the ID (similar to retrieving the SpaceId). Update this GeoLocationID to point_geolocation_id in the Postman environment variables for future use.

   Read the above business location using the Postman collection (Geomatch collection) and trigger Step 4.2: Read Business Location. However, if you want to try out the API, below is the sample API endpoint. Replace sap-iot-noah-live-geolocation-runtime.cfapps.eu10.hana.ondemand.com with the geolocation domain from the service key you generated for your subaccount in the below URL, replace 0bc4d7b4-bef9-4e0f-8f60-354673cc43ea with the GeoLocationID retrieved earlier and trigger a GET request.

   https://sap-iot-noah-live-geolocation-runtime.cfapps.eu10.hana.ondemand.com/geolocation/v1/GeoLocations/0bc4d7b4-bef9-4e0f-8f60-354673cc43ea
   

Geomatch is the process of comparing the location of the thing against the location of business objects and assigning the thing to the business object based on certain criteria like the distance between the thing and business object. Geomatch can be used to automatically detect the movement of a thing and accordingly do the assignment/un-assignment with a business object. Further, notifications can be generated to notify the person responsible if there is any unplanned movement of the thing and they can take further actions.

Geomatch functionality is based on the GPS data that a thing is generating. To configure the geomatch service to a business case, the radius values for calculations should be configured conforming to certain constraints. There can be only One Configuration per subaccount for geomatch. You can always modify the configurations if required.

1. Create geomatch radius settings.

   To create the geomatch radius settings, use the Postman collection (Geomatch collection) and execute Step 5.1: Configure GeoMatch Radius Settings. However, if you would like to try out, below is the sample API endpoint and the payload. Replace sap-iot-noah-live-geomatch-service.cfapps.eu10.hana.ondemand.com with the geomatch-service domain from the service key you generated for your subaccount in the below URL.

   https://sap-iot-noah-live-geomatch-service.cfapps.eu10.hana.ondemand.com/api/v1/geomatch/Configuration/geomatchRadiusSettings
   

   {
     "InitialRadius": {
       "Radius": 50,
       "Status": "Assigned",
       "CreateBOAssociation": true,
       "TreatMultipleMatchesWithSameStatus": false
     },
     "IntermediateRadius": [
       {
         "Radius": 100,
         "Status": "Nearby"
       },
       {
         "Radius": 200,
         "Status": "In 200m range"
       }
     ],
     "RestAllStatus": "Unassigned",
     "ManualMappedState": "Manually assigned",
     "ManualUnmappedState": "Manually unassigned",
     "AllowedDistanceError": 10
   }
   

   In the above payload, we have defined the radius settings with three statuses for different ranges of radius in meters.

2. Read the geomatch radius settings.

   Use the Postman collection (Geomatch collection that you downloaded from the GitHub link) and trigger the Step 5.2: Read GeoMatch Radius Settings Configuration request. If you want to try out, below is the sample API endpoint. Replace sap-iot-noah-live-geomatch-service.cfapps.eu10.hana.ondemand.com with the geomatch-service domain from the service key you generated for your subaccount in the below URL.

   https://sap-iot-noah-live-geomatch-service.cfapps.eu10.hana.ondemand.com/api/v1/geomatch/Configuration/GeoMatchRadiusSettings
   

Now that the radius settings are configured for the subaccount, you can trigger a geomatch request.

The geomatch request API is a REST API, which allows you to request one of the supported actions like ‘Automatic geomatch’, ‘Manual geomatch’, ‘Manual Un-mapping’ and ‘Clearing of Manual Mappings’ to be performed on a single thing. For triggering the geomatch request for a thing, the location of the thing is needed.

1. Retrieve the ThingID.

   • First, update the thing type name in the Postman environment variable ThingType with the thing type (for example, iot.trainingf954d.com.sap.silo10:silo_type_1) you created for your thing model (Refer to Onboard Virtual Devices Sending Data from Your Computer tutorial to create a thing model and ingest data).

   • Next, trigger the Step 6.1: GET ThingID request to get the ThingID. However, if you would like to try out, you can use the below endpoint.

   https://appiot-mds.cfapps.eu10.hana.ondemand.com/Things?$filter=_thingType eq 'iot.trainingf954d.com.sap.silo00:silo_type_1'
   

   In the above API, replace appiot-mds.cfapps.eu10.hana.ondemand.com with the appiot-mds domain from the service key and replace iot.trainingf954d.com.sap.silo00:silo_type_1 with the thing type from your thing model.

   The above API will return all the things for the thing type provided in the request. Select the ThingID(_id in the response) you want to use. Update the ThingID(_id in the response) and the ThingDisplayName(_name in the response) you retrieved here, in the Postman environment variables thing_id and thing_displayName for future use.

   

2. Trigger manual geomatch request.

   Manual geomatch requires that the geolocation is a business location, i.e, it has a BusinessObjectGUID for associating a thing to a geolocation. This will be the Business Partner information. The BusinessObjectType and BusinessObjectGUID are the type and ID of the business object to which the thing shall be manually assigned.

   For the manual geomatch request, the ThingLatitude and ThingLongitude can be the same as the business location (point of interest) coordinates values which you created earlier.

   As a user, you can choose to define a geomatch request as personal information, personal sensitive information or none. Define the SensitivityCategory as com.sap.appiot.security:spi for personal sensitive information, com.sap.appiot.security:pii for personal information or NONE. This is with respect to the Global Data Protection Regulation (GDPR).

   Use the Postman collection (Geomatch collection) and trigger Step 6.2: Manual Geomatch Assignment request. However, if you would like to try out, below is the sample API endpoint and payload. Replace sap-iot-noah-live-geomatch-service.cfapps.eu10.hana.ondemand.com with the geomatch-service domain from the service key you generated for your subaccount in the below URL. In the below sample payload, use the ThingID, ThingDisplayName (from the thing details),BusinessObjectGUID and BusinessObjectType (from the geolocation details) you retrieved above.

   https://sap-iot-noah-live-geomatch-service.cfapps.eu10.hana.ondemand.com/api/v1/geomatch/request
   

   {
      "RequestType": "MANUAL_ASSIGN",
      "ThingID": "{{thing_id}}",
      "ThingDisplayName": "{{thing_displayName}}",
      "IgnoreStatuses": "",
      "BusinessObjectType": "<Geolocation-BusinessObjectType>",
      "BusinessObjectGUID": "<Geolocation-BusinessObjectGUID>",
      "ThingLatitude": {{thing_latitude}},
      "ThingLongitude": {{thing_longitude}},
      "RequestTime": {{requestutctimestamp}},
      "SensitivityCategory": "NONE"
   }
   

Now that a geomatch request is triggered for a thing, the status of the thing will be based on the request type, radius settings and thing’s location. The results of the geomatch requests will be persisted as a Geo association data. The same is exposed as an OData API.

Trigger the Step 7: Latest Geo-Associations for one Thing request from the Postman collection (Geomatch collection) to fetch the latest associations for the thing. However, if you’d like to try out, below is the sample API Endpoint. Replace sap-iot-noah-live-geomatch-association-odata.cfapps.eu10.hana.ondemand.com with the geoassociation-odata domain from the service key you generated for your subaccount in the below URL.

https://sap-iot-noah-live-geomatch-association-odata.cfapps.eu10.hana.ondemand.com/api/v1/geomatch/odata/LatestgeomatchAssociationBythings?thingId={{thing_id}}

In the above API endpoint, the thing_id is the ThingID you used for triggering the geomatch request. You can read the latest geomatch associations or all the geomatch associations for the thing. The sample response for LatestGeoMatchAssociationByThings is as below:

The Matching_Status of the thing’s association depends on the request type, radius settings and the thing’s location.

Before defining an action, configure a Destination for the geomatch request API Endpoint for your subaccount. Please refer to the Step 1: Configure destination for geomatch request part of this tutorial.

1. Create an action to trigger geomatch request.

   If the above rule condition is satisfied, the rule will trigger an action. To define an action to trigger the geomatch request, navigate to the IoT Rules and Actions tab and then to Actions tile in the Fiori launchpad.

   • Once you are in the create screen, provide a unique name for the name and description fields (for example, Geomatch Request Action 0001) to avoid conflicts.

   • Select Event from rule for Triggered by field.

   • Select the rule you created (for example, Geomatch request rule 0001) in the previous step for the Rule field.

   • Select the Action Type as Service Integration, select the destination you created for Destination field and define the sample payload for the geomatch request. We have provided the sample payload below:

   {         
     "RequestType": "AUTOMATIC",     
     "ThingID": "${thing.id}",     
     "ThingDisplayName": "${thing.description}",     
     "IgnoreStatuses": "",     
     "BusinessObjectType": null,     
     "BusinessObjectGUID": null,     
     "ThingLatitude": ${silo_status.latitude},
     "ThingLongitude": ${silo_status.longitude},
     "SensitivityCategory": "NONE"
   }
   

   In the above payload, the RequestType of the geomatch request will be AUTOMATIC. The ThingLatitude and ThingLongitude values are the coordinates of the thing which comes from the thing model.

   An example of an action is below:

   

2. Create an action for FLP (Fiori launchpad) notification.

   As a follow-up, you can define another action to be triggered with the Action Type as In-App Notification after the completion of the previous action. This will trigger an FLP notification for the user.

   • Provide a unique name for the name and description fields (for example, Geomatch request FLP notification 0001) in the action screen.

   • Provide the email you are logged on with (SAP user) for the Recipients to receive notifications.

   • For Text field, you can use the below sample text or any other text of your choice.

   Geomatch was called for thing ${thing.name}
   

   An example of an action is provided below:

   

   Once the geomatch request is triggered by the action, the user will get a Fiori launchpad notification for the same.

   

   You can now retrieve the latest geomatch associations for the thing by using the APIs (like shown above in Read geomatch association for the thing) or create more actions for the same. A destination (similar to the geomatch request destination) must be configured for the associations API for consuming the API in the actions.

   In conclusion, the vending machine will now be assigned to the University Medical Center Heidelberg business object, which we did using manual geomatch. For the other things, geomatch request will be triggered from rules and actions as the data gets ingested with different locations. Based on the distance between thing and business location, assignment/un-assignment will happen.