Introduction
In part one of the blog post series, we have used the APIs of PdMS to create Indicators, Indicator Groups, a Model Template and a Model.
In this part, we are going to publish the Model and create an Equipment from the Model. Afterwards, we are going to ensure that the Equipment is replicated to IoT Application Enablement and SAP Cloud Platform Internet of Things for the Cloud Foundry Environment (aka IoT Services 4.0).
Previous Posts
Pre-Requisites
Before publishing the Equipment, make sure that the external systems are maintained correctly, according to:
https://help.sap.com/viewer/067e3d8253654398996ec49271b7441a/1902/en-US/697e20cec0af47d798ea3b76e637...
https://help.sap.com/viewer/067e3d8253654398996ec49271b7441a/1902/en-US/ac5129f13f6c43eb99025ebdd079...
Publish Model
Make sure that you can still connect to the system with your Cookie. If needed, repeat steps "Authentication and Authorization for API Access" from blog post 1.
See if everything works with this request:
curl -H @headers.txt \
"${PDMS_BASE_URL}"/ain/services/api/v1/models
Make sure that the MODEL_ID from blog 1 is still present as environment variable:
➜ ~ echo $MODEL_ID
D9B4D6A2FDBA4E888A7527220D351150
Publish the Model:
curl -X PUT \
"${PDMS_BASE_URL}/ain/services/api/v1/models(${MODEL_ID})/publish" \
-H @headers.txt \
-H 'Content-Type: application/json'
This request will return the Model JSON object and the status ("status") should be "2".
Create And Publish Equipment
Now we can create an Equipment. In my case it has the internalId Weather_Station-WDF49-5th-floor. We indicate in the objectsSync object that it should be synced with IoT Services and IoT AE (here called "PdMS"):
export EQUIPMENT_ID=`curl -X POST \
"${PDMS_BASE_URL}"/ain/services/api/v1/equipment \
-H @headers.txt \
-H 'Content-Type: application/json' \
-d '{"internalId":"Weather_Station-WDF49-5th-floor","description":{"language":"en","short":"Weather Station WDF49 5th Floor","long":""},"modelId":"'"$MODEL_ID"'","operatorID":"'"$ORG_ID"'","lifeCycle":"2","sourceBPRole":"1","modelKnown":true,"serialNumber":"1","batchNumber":"","templates":[],"objectsSync":[{"externalSys":"HCP IoT 4.0","status":true},{"externalSys":"PdMS","status":true}]}' \
| jq -r '.equipmentId'`
If everything went well, you should have the Equipment Id as environment variable:
~ echo $EQUIPMENT_ID
44F6588537524198BF895C376D0B81FF
After the initial creation, the Equipment is not yet synchronised with the external systems. We have to publish the Equipment to trigger the synchronisation. The initial publish will take some time, because it creates objects in both IoT AE as well as IoT Services:
curl -X PUT \
"${PDMS_BASE_URL}/ain/services/api/v1/equipment(${EQUIPMENT_ID})/publish" \
-H @headers.txt
If the call returns a rather large JSON object it should be synchronised.
Retrieve External ID of Equipment
We can now ask the API for the external IDs of the Equipment:
curl -H @headers.txt \
"${PDMS_BASE_URL}/ain/services/api/v1/objectid/externalid(${EQUIPMENT_ID})"
This call returns an array of external IDs. The external ID from the systemName "pdmsSysThing" is the Thing ID from IoT AE and the external ID from the systemName "IoT Services 4.0" is the device id in IoT Services 4.0. The actual external ID is in the JSON object externalID:
[{"id":"F4A6B223F03148A0BDBE8B3F2AB793D8","systemType":"PdMS","systemName":"pdmsSysThing","systemStatus":0,"systemID":"5460AC542F6B493EB3B14BFAFC236A32","sID":null,"systemClient":"","url1":"https://appiot-mds.cfapps.eu10.hana.ondemand.com/Things","url2":"","additionalInfo":"","ainObjectID":"44F6588537524198BF895C376D0B81FF","externalID":"CF1446EF0F3B481684E3F1E1A391E182","createdOn":"2019-03-27","changedOn":"2019-03-27","isOwnSystem":1,"externalObjectTypeCode":null,"externalObjectTypeCodeDescription":null,"isPrimarySystem":0,"isPrimaryExternalID":0},{"id":"35A1DD87A898423981B9DF8949CCB053","systemType":"HCP IoT 4.0","systemName":"IoT Services 4.0","systemStatus":0,"systemID":"8D3FE41F99AE4D908C140BBB29024E7D","sID":null,"systemClient":"","url1":"https://61e494a9-6640-44cc-a953-a1fb2e5642bc.eu10.cp.iot.sap","url2":"","additionalInfo":"","ainObjectID":"44F6588537524198BF895C376D0B81FF","externalID":"4","createdOn":"2019-03-27","changedOn":"2019-03-27","isOwnSystem":1,"externalObjectTypeCode":null,"externalObjectTypeCodeDescription":null,"isPrimarySystem":0,"isPrimaryExternalID":0}]
From the response above, we see that the thing id of our Equipment is CF1446EF0F3B481684E3F1E1A391E182 and the device id is 4.
Retrieve External ID of Model
After the Equipment is synched, we can also retrieve the external IDs of the Model from the system. The external ID of the Model is the ThingType in IoT AE and the Sensor in IoT Services 4.0:
curl -H @headers.txt \
"${PDMS_BASE_URL}/ain/services/api/v1/objectid/externalid(${MODEL_ID})"
The response is:
[{"id":"0A61464C32144DEC9A3BEDA3ECCC9236","systemType":"PdMS","systemName":"pdmsSysPackage","systemStatus":0,"systemID":"2441996EE8954ADC8D9F628AD9CA2902","sID":null,"systemClient":"","url1":"https://appcore-conf.cfapps.eu10.hana.ondemand.com/Configuration","url2":"","additionalInfo":"","ainObjectID":"D9B4D6A2FDBA4E888A7527220D351150","externalID":"dca.demo.sap.weatherstation:M_Weather_Station","createdOn":"2019-03-27","changedOn":"2019-03-27","isOwnSystem":1,"externalObjectTypeCode":null,"externalObjectTypeCodeDescription":null,"isPrimarySystem":0,"isPrimaryExternalID":0},{"id":"284C46BB4AA843F4AFCB9E7BD343D1E2","systemType":"HCP IoT 4.0","systemName":"IoT Services 4.0","systemStatus":0,"systemID":"8D3FE41F99AE4D908C140BBB29024E7D","sID":null,"systemClient":"","url1":"https://61e494a9-6640-44cc-a953-a1fb2e5642bc.eu10.cp.iot.sap","url2":"","additionalInfo":"","ainObjectID":"D9B4D6A2FDBA4E888A7527220D351150","externalID":"4b8ed9e4-bfa9-4ede-828a-0d4a467918eb","createdOn":"2019-03-27","changedOn":"2019-03-27","isOwnSystem":1,"externalObjectTypeCode":null,"externalObjectTypeCodeDescription":null,"isPrimarySystem":0,"isPrimaryExternalID":0}]
From the response above, we see that the ThingType is dca.demo.sap.weatherstation:M_Weather_Station and the sensor id is 4b8ed9e4-bfa9-4ede-828a-0d4a467918eb.
Retrieve External IDs of Indicators and Indicator Groups
To insert some sensor data, we now need to know what are the external IDs of the Indicators and the Indicator Groups. Luckily, there is an API , to get those information for IoT AE external IDs:
curl -X GET \
"${PDMS_BASE_URL}/ain/rest/models/${MODEL_ID}/externalmapping" \
-H @headers.txt
which returns in my case:
{"modelId":"D9B4D6A2FDBA4E888A7527220D351150","externalId":"dca.demo.sap.weatherstation:M_Weather_Station","templateList":[{"templateId":"9D57ACE0264449921600C406FDF33F4E","indicatorGroupList":[{"indicatorGroupId":"4F43ACE0264449921600C406FDF33F4E","internalId":"Measurements","externalId":"dca.demo.sap.weatherstation:IG_Measurements","propertyTypeId":"IG_Measurements0","indicatorList":[{"indicatorId":"44A7D99BD7234224BA83D1F36371146D","internalId":"Temperature","externalId":"I_Temperature"},{"indicatorId":"5B6E6C882E2244C19DB844C6580D6C69","internalId":"Pressure","externalId":"I_Pressure"},{"indicatorId":"57B820CE1900487682F0276B20D09632","internalId":"Humidity","externalId":"I_Humidity"}]},{"indicatorGroupId":"5043ACE0264449921600C406FDF33F4E","internalId":"Scores","externalId":"dca.demo.sap.weatherstation:IG_Scores","propertyTypeId":"IG_Scores0","indicatorList":[{"indicatorId":"4DF2F5ED959A4320993D5D2645870480","internalId":"Score","externalId":"I_Score"},{"indicatorId":"9012F668086B4E8FBBA7963F79E6DA35","internalId":"Normalized_Score","externalId":"I_Normalized_Score"}]}]}]}
From the above response payload we can conclude the following mapping for the Indicator Groups:
Indicator Group |
Property Set Type |
Property Set |
Measurements |
dca.demo.sap.weatherstation:IG_Measurements |
IG_Measurements0 |
Scores |
dca.demo.sap.weatherstation:IG_Scores |
IG_Scores0 |
and the following mapping for the Indicators:
Indicator |
Property |
Temperature |
I_Temperature |
Pressure |
I_Pressure |
Humidity |
I_Humidity |
Score |
I_Score |
Normalized_Score |
I_Normalized_Score |
For more information about the mapping, refer to this help page:
https://help.sap.com/viewer/067e3d8253654398996ec49271b7441a/1902/en-US/ac5129f13f6c43eb99025ebdd079...
With this information we are able to use the APIs of IoT AE to upload sensor data for this Equipment / Thing. That concludes this part of the blog post series. In the next part of the series we will upload some sensor data to IoT AE and verify that it arrives in the PdMS system.
