SocIoTal Tutorial

sociotal edited this page Aug 26, 2016 · 40 revisions

#SocIoTal: Communities Manager & Context Manager Demo This document intends to present the main functionalities of the SocIoTal Communities, playing a demonstrator about a SocIoTal application that involves also (and also demonstrates a set of functionalities) the SocIoTal Context Manager and the SocIoTal Web User Environment. All the here presented functionalities conform only a subset of all capabilities offered by the SocIoTal integrated platform. Expanded information can be found in SocIoTal GitHub

The scenario

Within the proposed scenario, Alice is a SocIoTal user that plans to build, over SocIoTal platform, an application for her closer relatives. Alice’s grandfather has Alzheimer’s disease and, due to this, he sometimes suffers from sudden episodes of disorientation and confusion when he walks outside home. In order to help her family to take care of her grandfather and avoid him to get lost, Alice has programmed an easy android app to be installed in her relative’s smartphones, and mainly in her grandfather’s one. This app is able to capture the GPS coordinates and send it every 2 minutes. Supported by SocIoTal platform, she plans to create a SocIoTal Community, made up of her family members, install her application on their smartphones, register them within her Community and share here the position of each one. This way, every Alice relative (and ONLY Alice’s relatives) will easily know the last valid position of each other relative, including Alice’s grandfather, what helps to find him if necessary.

The tools

All the software required to play this demo is available to be tested by the user. All this software is fully operative and could be used to extend, complement and even inspire other use cases and applications, but its main objective is to help on understand SocIoTal and what can this project offer to final users.

The Android APK

Can be downloaded from SocIoTal GitHub and installed on an android smartphone supporting location services. For the sake of simplicity and focused on show how the SocIoTal Integrated platform works, we’ve designed a very simple interface where we can easily show the different actions an application like this should perform in order to send data to the SocIoTal Context manager. The figure below shows a capture of this SocIoTal_Test APK

Fig 1. SocIoTal Test APK for the demo

In order to be able to send a captured GPS position to the specified SocIoTal Context Manager and this captured data will be shared only within a given SocIoTal Community, the app requires:

1- A valid SocIoTal user (User field) plus its corresponding password (Pass field)

2- An existing SocIoTal Community, given by its Community name (Community field)

3- A device ID (just the last name of the complete ID) identifying the mobile terminal sending the data (DeviceID field) and that belongs to the pointed community. This ID will be created when we first register the device.

4- The domain id (Domain field) the community and the user have been created (currently, only default domain is available)

With this data, the app can first request a token for the pointed user within the specified community. The Token URL field points to the SocIoTal’s Communities Manager instance where the community was created and the SocIoTal IdM that hosts the user. It executes the Communities Manager simpleRequest method to obtain the Community-Token that authenticates the user and identifies it as member of the pointed community. If the user and password are correct and belong to the pointed SocIoTal Community, this method will retrieve directly a valid Community-Token.

Once the App has obtained a valid Community-Token from the SocIoTal Communities Manager, it executes a call to the SocIoTal Context Manager updateContext method including on its header the obtained Community-Token that identifies the user and the community where the update goes to and within its payload, the corresponding device Id that identifies the mobile terminal, the attribute “location” with the GPS coordinates captured and the action “UPDATE” that allows the position update performing. This way, the GPS coordinates of this device will be updated every time we push the “click me!” button (if we want the app do it automatically every X seconds, we should modify its source code. This should be easy to do for any android programmer).

In order to latter access this updated data, we should execute a SocIoTal Context Manager queryContext or extended queryContext including, on its header, a Community-Token valid for the initial SocIoTal pointed community, that only members of this community may obtain.

The SocIoTal Integrated Platform instance

In order to properly run the SocIoTal Test APK, we require an instance of SocIoTal Integrated Platform that includes, at least:

  • SocIoTal IdM, to support new user creations, identifications and authentications

  • SocIoTal Context Manager, to keep devices and manage provided context information

  • SocIoTal Commuities Manager, that allows the user to create and manage communities, as well as assign users and context entities to these communities In order to enhance the user experience when working with SocIoTal Integrated Platform, we will use its

  • SocIoTal Web User Environment that provides a simple user interface to create and execute most of the actions required to run the use case while makes easier the presentation layer.

Other SocIoTal components (trust manager, Security Framework, SocIoTal Enablers…) can be linked to this scenario to expand functionalities or to create a different one. This is up to the user imagination.

SocIoTal project provides the user with a complete cloud instance of its Integrated platform, able to support all the methods, functionalities and capabilities required for this use case, as well as all those documented in the SocIoTal WiKi for all SocIoTal Components.

The SocIoTal Integrated Platform to evaluate components and build applications url is: http://platform.sociotal.eu https://platform.sociotal.eu

Directly executing this url will access the SocIoTal Web User Interface, either, over http or https protocol. For this demo we will use http, but the same can be done using https protocol.

No direct access to SocIoTal IdM is required for this demo (these accesses will be done through the Web User Environment or the Communities Manager). To know more about accessing SocIoTal IdM refer to its WiKi section.

To access SocIoTal Context Manager and SocIoTal Communities Manager respective APIs (either over http or https), the IP and ports will be:

https://platform.sociotal.eu:8443/

http://platform.sociotal.eu:3500/

The respective linked SocIoTal WiKi pages will provide detailed information about how to execute the different methods played along this demo, including the provided specific information referred to the Cloud Instance.

Playing the Demo

The main target of this demo is to introduce the user to the basic main features of SocIoTal Integrated Platform while, at the same time, provides (and guides) them with the access to the Cloud Instance of this platform and the tools to build their apps or even their own SocIoTal instances.

The following diagram shows in one shot the different steps we will later describe in order to execute the complete demo.

Fig 2. Demo schema

Create a SocIoTal User

Previously to star with demo’s steps, we consider, SocIoTal user “Alice” already exists within the platform. To create a SocIoTal user you can use 2 alternative ways, both of them relaying on the same User’s directory (created user’s will be compatible).

1- Use the SocIoTal IdM Java libraries described in SocIoTal WiKi and create (or embed) your own code to register SocIoTal users within a given SocIoTal Integrated Platform. This is useful when creating your own apps.

2- Use the Communities Manager API and directly, through its “addUser” HTTP POST method create the required user SocIoTal SERVER http://platform.sociotal.eu:3500/
POST /SocIoTal_COMM_V1/USERS/addUser HEADERS
Content-type application/json

Payload (example)

{
"userName":"Alice",
"nickName":"aliceTest",
"formatted": "Alice Community Testing",
"password":"passAlice",
"email": "maindemosociotal@gmail.com",
"description":"Alice test user",
"domainName":"Default",
"address":{
    "addressType":"Home",
    "addressStreetAddress":"High Street",
    "addressLocality":"Santander",
    "addressPostalCode":"39005",
    "addressCountry":"Spain"
},
"organization":"HOME",
"department":"none",
"active":true
}

Web User Environment (WUE) allows the user to register their identities, providing a user interface that makes more friendly the new user registration. Behind this interface, one of the above mentioned methods is used.

a) Call http://platform.sociotal.eu

Fig 3. Web User Environment-WUE- (platform.sociotal.eu) log in screen

b) Press “Sign Up” and fill the minimum required data (username, password and email address)

Fig 4. WUE Create user screen

Fig 5. WUE create user confirmation screen

c) After checking your mail account and activate your new user (and SocIoTal account) you will be able to access SocIoTal Web User Interface and you will have already registered a user. You will see your dashboard and will have access to different SocIoTal Platform features.

Fig 6. Log in SocIoTal WUE with Alice user

Fig 7. Alice WUE dashboard

Detailed information about the SocIoTal Web User Environment and the features it offers can be found on its SocIoTal WiKi page

NOTE: If you create the user through the WUE interface, you will need to set manually its internal “userName” attribute (automatically set to user ID value). To do this, you have to call SocIoTal ComM” modifyUser method to set this attribute as your real user name:

1- We need a token (not necessary linked to any community) that identifies us as platform user. This time, we will request it using the user ID (and simpleRequest method)

POST /SocIoTal_COMM_V1/TOKEN/simpleRequest HTTP/1.1
Host: platform.sociotal.eu:8443 (https)
Content-Type: application/json
Cache-Control: no-cache
Payload:
{
   "id":"ec1b1f1f-790a-498d-9393-fe9e7c1533d1",
   "password":"passAlice",
   "domainName":"Default"
}

Response: 13dae75cdabb4f4b8e6870bba6bb709f We can obtain the Alice (user) ID from Alice dashboard, by click on “Alice” name (top right corner)

Fig 8. Alice WUE dashboard

2- Once we have a valid token, we can call “modifyUser” method, setting the “userName” parameter the same you used in the WUE registration:

PUT /SocIoTal_COMM_V1/USERS/modifyUser HTTP/1.1
Host: platform.sociotal.eu:8443
Accept: application/json
Community-Token: 13dae75cdabb4f4b8e6870bba6bb709f
Content-Type: application/json
Cache-Control: no-cache
{
"userName":"Alice",
"domainName":"Default",
"active":true
}

Here, you can include as many parameters as you want to modify, following the same structure used in addUser method.

Creating the Community

Now we have created SocIoTal User Alice (username = Alice), we can start using SocIoTal Platform features. We have 2 complementary main options to start using it:

a) We can do a login (userName/password) within the WUE, as shown in Create a SocIoTal User section, to access our dashboard and execute some of the available SocIoTal functionalities.

b) We can request a Community Token and directly use the SocIoTal Communities Manager and/or the Context Manager APIs to create communities, register devices, add users or share information. To request a token (initially not linked to any community) we can use any of the available methods:

POST /SocIoTal_COMM_V1/TOKEN/request HTTP/1.1 Host: platform.sociotal.eu:8443 (https) Content-Type: application/json Cache-Control: no-cache`

Payload:

{
   "userName":"Alice",
   "password":"passAlice",
   "domainName":"Default"
}

We will get the UUID token that later will be used in further HTTP Requests and identifies and authenticates Alice:

{
    "values": {
        "token": {
            "methods": [
                "password"
            ],
            "issued_at": "2016-08-12T11:34:17.613168Z",
            "expires_at": "2016-08-26T11:34:17.613115Z",
            "audit_ids": [
                "GJ7bmEciRECiY758HZTvLw"
            ],
            "user": {
                "id": "86f27b97-b8e4-4290-88d0-63625c6d73b3",
                "name": "Alice",
                "domain": {
                    "id": "default",
                    "name": "Default"
                }
            }
        }
    },
    "communityToken": "f6dfacabaa8f4fe6a783051b38770d5f"
}

With this token, we can create directly a community using “create” method:

POST /SocIoTal_COMM_V1/COMMUNITIES/create HTTP/1.1 Host: platform.sociotal.eu:8443 (https) Content-Type: application/json Community-Token: f6dfacabaa8f4fe6a783051b38770d5f Cache-Control: no-cache

{
"description":"Alice Own Comm",
"communityName": "AliceOwn",
"contact":{
    "email01":"maindemosociotal@gmail.com"
    },
"extraData":{
    "extradesc":"This is reserved for Alice purposes"
    }
}

Having as a response, the Id, name, Owner and domain where the new community has been created

{
    "community": {
        "id": "48ed9867307848caa43e3311d83130b1",
        "name": "AliceOwn"
    },
    "domain": {
        "id": "default",
        "name": "Default"
    },
    "owner": {
        "id": "86f27b97-b8e4-4290-88d0-63625c6d73b3",
        "userName": "Alice"
    }
}

From the WUE Alice dashboard (Fig 7) we can also create a community. Just, by clicking the “Create Community” button.

Fig 9. MyFamily community creation screen

After clicking the “Save” button, the “MyFamily” community will be created and you will be redirected the WUE communities screen (Fig 9), where all communities registered within the SocIoTal instance in use will be shown. The screen will first show those communities where you belong (notice that, in this use case, both communities, the one created directly with the Communities API and the one created through the WUE, appear) and you have access to, and later, all the available communities. To access any of the communities you have no membership, the system will send a notification (if you use the WUE) to that community owner, requesting access.

Fig 10. WUE screen listing all registered communities

By clicking the “MyFamily” box name, you will access your community info, showing the owner, the current members, their roles and the domain the community (an all the members) belong to.

Fig 11. WUE’s Community info screen

The “x” button on the top right corner will delete your community.

Add Members to the Community

We will work, within this use case, with the “MyFamily” community. The idea now is to add other registered SocIoTal users to “MyFamily” community, in particular, Alice’s family, those we’re interested to be part of the application. To do this, we’ve created, following Create a SocIoTal User section and directly using Communities Manager API two new SocIoTal users, corresponding to two Alice relatives: Relative_01 and Relative_02.

Using WUE, we access as Relative_01 user to its Dashboard

Fig 12. Alice’s Grandfather Tom (Relative_01 user) WUE dashboard

And clicking “View Communities” we select “MyFamily” community, within SocIoTal Communities group MyFamily community screen [WUE FAILURE]

Fig 13. MyFamily Community membership request WUE screen

As Relative_01 is not still a member of this community, by clicking the blue cross, the system will automatically send an email to Alice (the owner of the community) to accept user Realtive_01 as a member. Within the email sent, Alice will find a link (requires a web open session as Alice in the same PC to work) which directly adds the requestor user (Relative_01) to the selected community (MyFamily). After Alice execute this, Relative_01 will be part of the community and will be able to register devices and access registered devices within MyFamily.

Fig 14. Alice’s Grandfather Tom (Relative_01 user) list of communities

The same can be done using directly the SocIoTal ComM API (WUE uses these methods to internally add members and show communities info) [Supposing that we (Alice) already know the user (userName) we want to add to our community (MyFamily)]:

1- As “Alice” user, we request a Community-Token to operate with SocIoTal Communities. In this case, as we want to work with “MyFamily” community, the token must be scoped to this community

POST /SocIoTal_COMM_V1/TOKEN/request HTTP/1.1
Host: platform.sociotal.eu:8443
Content-Type: application/json
Cache-Control: no-cache

{
"userName":"Alice",
"password":"passAlice",
"domainName":"Default",
"communityName":"MyFamily"
}

This way, the retrieved Community-Token is linked to user Alice and MyFamily community

{
    "values": {
        "token": {
            "methods": [
                "password"
            ],
            "issued_at": "2016-08-17T10:50:51.198981Z",
            "expires_at": "2016-08-31T10:50:51.198950Z",
            "audit_ids": [
                "SfkBZWV4QJmOmLrPkICdYw"
            ],
            "roles": [
                {
                    "id": "23953f74b44b42c6b9c59522828071f9",
                    "name": "owner"
                }
            ],
            "community": {
                "id": "15a4bc07a9ce446784ee0780ce437582",
                "name": "MyFamily",
                "domain": {
                    "id": "default",
                    "name": "Default"
                }
            },
            "user": {
                "id": "86f27b97-b8e4-4290-88d0-63625c6d73b3",
                "name": "Alice",
                "domain": {
                    "id": "default",
                    "name": "Default"
                }
            }
        }
    },
    "communityToken": "94c11d9264e2428799539ac906ac3fbb"
}

2- In order to add a user to a community, its user Id is required. We know the username (Relative_01) so, with the obtained Community-Token and the “Get user Info by Name” method, we will obtain the description of the user (and its id)

GET /SocIoTal_COMM_V1/USERS/getUserInfobyName/Relative_01 HTTP/1.1
Host: platform.sociotal.eu:8443
Content-Type: application/json
Community-Token: 94c11d9264e2428799539ac906ac3fbb
Accept-Type: application/json
Cache-Control: no-cache

Response:

{
    "users": [
        {
            "formatted": "Alice Grandfather Tom",
            "enabled": true,
            "department": "none",
            "addressStreetAddress": "Pza de la Ciencia S/N",
            "domain_id": "default",
            "addressType": "Work",
            "userCommunityId": "0a1e99bff6b84be998d3060d271cd2aa",
            "id": "0c194bb5-4600-4771-81fe-3b6c09681ad5",
            "organization": "HOME",
            "username": "Relative_01",
            "addressLocality": "Santander",
            "attName": {
                "formatted": "Alice Grandfather Tom"
            },
            "email": "fam1demosociotal@gmail.com",
            "nickName": "Alice_Grandfather",
            "description": "Alice Grandfather for demo",
            "name": "Relative_01",
            "userName": "Relative_01",
            "addressPostalCode": "39005",
            "addressCountry": "Spain",
            "addresses": [
                {
                    "streetAddress": "Pza de la Ciencia S/N",
                    "postalCode": "39005",
                    "locality": "Santander",
                    "type": "Work",
                    "Country": "Spain"
                }
            ]
        }
    ]
}

3- With the proper user ID and the Community-Token, now Alice can add Relative_01 to her community, as a member

PUT /SocIoTal_COMM_V1/COMMUNITIES/assignRole HTTP/1.1
Host: platform.sociotal.eu:8443
Content-Type: application/json
Community-Token: 94c11d9264e2428799539ac906ac3fbb
Cache-Control: no-cache

{
    "userId":"0c194bb5-4600-4771-81fe-3b6c09681ad5",
    "roleName":"member"
}`
 
The response now will point the role, the community and the user we’ve just added:

`{
    "community": {
        "id": "15a4bc07a9ce446784ee0780ce437582",
        "name": "MyFamily"
    },
    "domain": {
        "id": "default",
        "name": "Default"
    },
    "role": {
        "id": "2b99314eea3541b79ea88ad5aecfd2b6",
        "name": "member"
    },
    "user": {
        "id": "0c194bb5-4600-4771-81fe-3b6c09681ad5",
        "userName": "Relative_01"
    }
}

Once we’ve added both users (Relative_01 and Relative_02), the MyFamily community will look like this:

Fig 15. MyFamily community info screen (WUE)

Add Devices to the Community

Now, Alice, Relative_01 and Relative_02 SocIoTal users will be able to register new devices and access provided info within MyFamily community. The process to register a new device is the same in any case. To carry on with the use case, we will use as SocIoTal Device the mobile phone of each member of the community, with the Android APK described in the tools section installed.

Using the WUE (from any of these three users) and accessing the Device Screen (Fig 15), just click the blue cross on the top right corner.

Fig 16. Relative_01 WUE Device screen

Let’s use a blank template to register the device and fill the different boxes according to what we want to register. Within this use case, the Mobile App has been internally programmed (this cannot be changed without modifying the code of the APK) to work in SocIoTal project, belonging to SAN deployment and as urn:x-org:sociotal:resource:MobileLoc context type, but we can use the Entity Name we consider best. With all of this, the Relative_01 complete Entity ID will be SocIoTal:SAN:MobileLoc:GrandPa. The community box will let us register this device within any of the communities we belong to (or by default, in the “open” one). We select here MyFamily, so, only MyFamily members will be able to access it. In “Attributes” menu (click the blue cross) we will select “Location” attribute, since this will be the data the device will share.

Fig 17. WUE Device registration template

Just click “save” button and the system will ask us if we want to create a “channel” for this new entity. This channel will be used later to access (from the WUE session of the current user) the data uploaded by this device.

Using the SocIoTal CM API, the steps will be:

1- Request a Community-Token (now as Relative_02 user) to operate with SocIoTal Communities. In this case, as we want to work with “MyFamily” community, the token must be scoped to this community. This way, when we later use this token to register the device, the CM will automatically assign it to MyFamily community and Relative_02 as its owner.

POST /SocIoTal_COMM_V1/TOKEN/request HTTP/1.1
Host: platform.sociotal.eu:8443
Content-Type: application/json
Cache-Control: no-cache

{
"userName":"Relative_02",
"password":"passRelative_02",
"domainName":"Default",
"communityName":"MyFamily"
}

As a response:

{
    "values": {
        "token": {
            "methods": [
                "password"
            ],
            "issued_at": "2016-08-17T16:27:06.804565Z",
            "expires_at": "2016-08-31T16:27:06.804530Z",
            "audit_ids": [
                "9sfeQBBeRmO0Py4o0ikaIQ"
            ],
            "roles": [
                {
                    "id": "2b99314eea3541b79ea88ad5aecfd2b6",
                    "name": "member"
                }
            ],
            "community": {
                "id": "15a4bc07a9ce446784ee0780ce437582",
                "name": "MyFamily",
                "domain": {
                    "id": "default",
                    "name": "Default"
                }
            },
            "user": {
                "id": "4d95deab-a385-45c1-afd8-113835f95cbf",
                "name": "Relative_02",
                "domain": {
                    "id": "default",
                    "name": "Default"
                }
            }
        }
    },
    "communityToken": "d1cedc1843324131a6a9fa37afdc485c"
}

2- To create a new entity, we can follow different ways, depending on the use of pure NGSI we want. We can use NGSI9 registerContext if we want to create a registry in the SocIoTal context entities directory and an NGSI10 updateContext (append) if we want later to provide context info OR, in this case, use the EXTENDED createContextEntity to do both actions in just one HTTP call. Either the way we use, we need to attach (in header) a valid Community-Token

POST /SocIoTal_CM_REST_V3/EXTENDED/createContextEntity HTTP/1.1
Host: platform.sociotal.eu:8443
Accept: application/json
Content-Type: application/json
Community-Token: d1cedc1843324131a6a9fa37afdc485c
Cache-Control: no-cache

{
	"entity": {
		"type": "urn:x-org:sociotal:resource:MobileLoc",
		"isPattern": "false",
		"id": "SocIoTal:SAN:MobileLoc:Mother"
	},
	"attributes": [{
		"name": "Location",
		"value": "43.472057, -3.800156",
		"type": "http://sensorml.com/ont/swe/property/Location",
		"metadatas": [{
			"name": "WorldGeographicReferenceSystem",
			"value": "WSG84",
			"type": "http://sensorml.com/ont/swe/property/WorldGeographicReferenceSystem"
		}]
	}],
	"duration": "PT1H",
	"providingApplication": "http://platform.sociotal.eu:3500/SocIoTal_CM_REST_V3/NGSI10_API"
}

Response

{
    "id": "SocIoTal:SAN:MobileLoc:Mother",
    "duration": "PT1H",
    "registrationId": "57b492e8d9a45c626dc575a1",
    "communityId": "15a4bc07a9ce446784ee0780ce437582"
}

After registering a device for every community member, MyFamily community have three members: Alice, Relative_01 (Grandfather) and Relative_02 (Mother) and three devices: “GrandPa”, “Mother” and “Alice”.

Fig 18. Devices registered in MyFamily community (from Alice dashboard)

Notice that you have to belong to “MyFamily” community to see the devices registered in the community. Otherwise, you will only see the community name.

Sharing Information within the Community

Now, we have created the community as the environment where data will be shared, we have registered three members (Alice, Grandfather and Mother) and each one have added their corresponding Mobile Location apk instance, running on their mobile phones. Now it is time to share data from devices.

Uploading data from the APK

The SocIoTal Test APK described in “The Android APK” section is intended to provide a quick and easy look at the way data is uploaded/updated in the SocIoTal integrated platform. What this apk does is just UPDATE the data of an already registered context entity with new information captured. This is, previously to properly run the APK, we have registered the entity we want to update within the platform and in the corresponding community (as done in “Add Devices to the Community” section). Taking this into account, we’re going to update the location data of GrandPa device (the mobile phone belonging to Alice Grandfather).

Executing SocIoTal Test app in Grandfather’s mobile and using Grandfather’s SocIoTal user (Relative_01) we fill the data required by the app:

Fig 19. Alice’s Grandfather SocIoTal Test apk capture

• User: the userName defined when creating the user • Pass: the password defined when creating the user • Community: the community name where the device have been registered in (or the community where we want to send the data if we have registered the device in several communities) • DeviceID: the device ID we used when the device was registered in the pointed community. This app uses only the name (not the complete ID) the rest of the ID components are automatically set by this app. • Domain: de domain ID where the user, de community and the device belong to (so far only “default” is allowed)

This set of data is used by the app to form and execute the API calls required to update the data. In TOKEN URL and POST URL fields, we can set the instance of the platform we are working with. This instance should host the SocIoTal IdM where we registered the user, the SocIoTal ComM where we created the community and the SocIoTal CM storing the context element and information. This example uses the SocIoTal cloud instance (platform.sociotal.eu) and the apk supports only http. To use https or other SocIoTal instance, just modify these elements. When we push “Click Me!” button, the apk captures the location data and:

1- With provided User, Pass, Community and Domain data and the URL to the selected platform, creates and executes a token simpleRequest method:

POST /SocIoTal_COMM_V1/TOKEN/simpleRequest HTTP/1.1
Host: platform.sociotal.eu:3500
Content-Type: application/json
Cache-Control: no-cache
{
"userName":"Relative_01",
"password":"passRelative_01",
"domainName":"Default",
"communityName":"MyFamily"
}

*Notice the method uses “domainName” instead of “domain ID”. Currently “Default/default” is managed by the platform but the corresponding domain name/id will be easily obtained through an existing method (but not yet documented) provided by the Communities API.

Response: fdc94b84c1a34af4becf220e87c03c18

2- The obtained Community Token identifies the user and the community. Now, the APK creates and executes the SocIoTal CM updateContext method

POST /SocIoTal_CM_REST_V3/NGSI10_API/updateContext HTTP/1.1
Host: platform.sociotal.eu:3500
Accept: application/json
Content-Type: application/json
Community-Token: fdc94b84c1a34af4becf220e87c03c18
Cache-Control: no-cache
{
    "contextElements": [{
        "id": "SocIoTal:SAN:MobileLoc:GrandPa",
        "type": "urn:x-org:sociotal:resource:MobileLoc",
        "isPattern": "false",
        "attributes": [{
            "name": "Location",
            "value": "43.472057, -3.700156",
            "type": "http://sensorml.com/ont/swe/property/Location"
            
        }]
    }],
    "updateAction": "UPDATE"
}

The platform will return an HTTP 200 OK message when the updateContext has been properly executed and the data relies now in the SocIoTal CM instance.

Accessing shared Mobile Location Data

Data now is stored in the SocIoTal CM and protected by the Community-Token. In order to access information uploaded in the community, basically you can proceed in two “different” ways:

a) You can just directly query for the last update of any of the registered devices (or all in a row): queryContext method

b) You can subscribe and receive a notification every time a new data is available (asynchronous) or every X minutes (synchronous): subscribeContext method

To close this demo, we will show a direct query using the SocIoTal CM API (implementing Option A):

1- First, we need a Community-Token scoped to “MyFamily” community. We can use any of the methods already shown in this demo or documented in the Communities WiKi:

POST /SocIoTal_COMM_V1/TOKEN/simpleRequest HTTP/1.1
Host: platform.sociotal.eu:8443
Content-Type: application/json
Cache-Control: no-cache
{
"userName":"Alice",
"password":"passAlice",
"domainName":"Default",
"communityName":"MyFamily"
}

Response: bd0b8c10367b444486b0eaf0079a0275

2- Then, we can execute a simple queryContext (we will use here the EXTENDED queryContext) to ask for a concrete device:

GET /SocIoTal_CM_REST_V3/EXTENDED/queryContext/SocIoTal:SAN:MobileLoc:GrandPa HTTP/1.1
Host: platform.sociotal.eu:8443
Accept: application/json
Community-Token: bd0b8c10367b444486b0eaf0079a0275
Cache-Control: no-cache

Response

{
    "contextResponses": [
        {
            "statusCode": {
                "reasonPhrase": "OK",
                "code": "200"
            },
            "contextElement": {
                "id": "SocIoTal:SAN:MobileLoc:GrandPa",
                "attributes": [
                    {
                        "name": "Owner",
                        "value": "0c194bb5-4600-4771-81fe-3b6c09681ad5",
                        "type": "http://sensorml.com/ont/swe/property/RoleCode",
                        "metadatas": [
                            {
                                "name": "DataDescription",
                                "value": "string",
                                "type": "http://sensorml.com/ont/swe/property/DataDescription"
                            }
                        ]
                    },
                    {
                        "name": "Location",
                        "value": "43.472057, -3.700156",
                        "type": "http://sensorml.com/ont/swe/property/Location",
                        "metadatas": [
                            {
                                "name": "WorldGeographicReferenceSystem",
                                "value": "WSG84",
                                "type": "http://sensorml.com/ont/swe/property/WorldGeographicReferenceSystem"
                            },
                            {
                                "name": "DataDescription",
                                "value": "string",
                                "type": "http://sensorml.com/ont/swe/property/DataDescription"
                            }
                        ]
                    },
                    {
                        "name": "owner",
                        "value": "0c194bb5-4600-4771-81fe-3b6c09681ad5",
                        "type": "identitier:UUID"
                    },
                    {
                        "name": "update",
                        "value": "restricted",
                        "type": "text"
                    }
                ],
                "type": "urn:x-org:sociotal:resource:MobileLoc",
                "isPattern": "false"
            }
        }
    ]
}

And here we obtain the last update on GrandPa device. We can play with NGSI10 SocIoTal CM queryContext method to obtain all registered devices or perform any search. NGSI9 SocIoTal CM discoverContextAvailability will help on discover available devices and context information.

By clicking on “View Details” of any of the presented devices on Fig 17, the WUE will show its related information and the last update.

Fig 20. Detailed info of a registered device, including context information

In order to implement option B and automatically receive notifications on a “listener”, SocIoTal CM provides NGSI10 subscribeContext method. A “listener” is considered here as the URL of an endpoint able to receive and process an HTTP POST. When any subscription condition happens, SocIoTal CM will automatically send a HTTP POST to this specified URL including, as payload, the subscribed new context information.

To perform a subscription to any device belonging to MyFamily (here we show ONCHANGE option), the steps are:

1- First, as in most operations involving communities, we need a Community-Token scoped to “MyFamily” community. This way, we will be able to access all devices registered within this community:

POST /SocIoTal_COMM_V1/TOKEN/simpleRequest HTTP/1.1
Host: platform.sociotal.eu:8443
Content-Type: application/json
Cache-Control: no-cache
{
"userName":"Alice",
"password":"passAlice",
"domainName":"Default",
"communityName":"MyFamily"
}

Response: 9da287d5171c435f817c0909a727e10b

2- Perform subscribeContext operation:

POST /SocIoTal_CM_REST_V3/NGSI10_API/subscribeContext HTTP/1.1
Host: platform.sociotal.eu:8443
Accept: application/json
Content-Type: application/json
Community-Token: 9da287d5171c435f817c0909a727e10b
Cache-Control: no-cache
{
   "entities": [
       {
           "type": "urn:x-org:sociotal:resource:MobileLoc",
           "isPattern": "true",
           "id": "SocIoTal:SAN:MobileLoc:.*"
       }
   ],
   "reference": "http://193.143.201.50:3570/Callback_Apps/Listeners/LogWriterFile",
   "duration": "P1D",
   "notifyConditions": [
       {
           "type": "ONCHANGE",
           "condValues": [
               "Location"
           ]
       }
   ],
   "throttling": "PT5S"
}

With this request, we’re asking SocIoTal CM to send an HTTP POST to http://193.143.201.50:3570/Callback_Apps/Listeners/LogWriterFile every time any change on “location” is reported by ANY MobileLoc belonging to SocIoTal:SAN deployment registered in MyFamily community. This is, when any of the three registered devices reports a new location.

The response:

{
    "subscribeResponse": {
        "duration": "P1D",
        "throttling": "PT5S",
        "subscriptionId": "57b5cc70d9a45c626dc575a4"
    }
}

Reports everything was fine and requested subscription was registered.

These steps are performed by the WUE when creating a CHANNEL. By clicking on the blue chain (top right) on Fig 19, we create a channel for the selected device.

Fig 21. Channel creation to track Grandfather’s location

Then, once saved, by clicking on “subscribe” text (Fig 21), the WUE automatically executes a subscription to the selected device and data will appear on the Data section of the screen every time new location info is sent to the SocIoTal CM by the “GrandPa” device.

Fig 22. WUE Channel information