Mapping convention Centralized endpoint usage Management Training Social Header Version/Format header Authorization header Synchronization header Email configuration service Get current configuration Update email server configuration User web services List users Get user Create user Update user Change password Activate user Deactivate user Send welcome mail Delete user Push notification web services Create push notification Groups Web services Create group Get group Update group Delete group Get root groups Group searcher Get children groups Get ancestor groups Get subgroups Get direct group users Add users to group Remove users from group Get group admins Add admins to group Remove admins from group Get commonId of a group Get externalId of a group Licenses web service  Get licenses Extended fields web services List extended fields

Mapping convention In order to use Netex Cloud web services, all Production customers should use the learningCloud integration domain: https://.learningcloud.me . This domain is mapped to our integration infraestructure, decoupled from our frontend infraestructure, so this is the recommended domain for integrations. You should note that Global Admin web services are still available at customer LMS domain (https://.learningcloud.me) since we'd like to offer a migration window to our clients; however, this domain will be deprecated in the future. This is the reason why along this document we are going to use both integration and customer domains in our examples. Our centralized web services will have the following url pattern: /integration/ws/{section}/{context} section: mandatory. Allowed values are: management: basic services, like managing users training: training services, like managing courses social: social services, like managing communities context: mandatory. Context of the url, specific for every section. To compose the complete url for a WS call, we must concatenate the integration domain and the WS url. For example, for the cutomer netex, WS urls start with https://.learningcloud.me/integration/ws/....

Cloud will provide us a single entry point for the execution of WS. From this point, Cloud will redirect requests to the appropriate WS (Central, Social, etc ). For this purpose, the previous paragraph define, by convention, how to invoke those services. In addition to obtaining a unified way to make requests to Web services, the authentication of users that make requests is centralized. Management Management web services have basic functionality like user management. Prefix is /ws/management and the services are redirected to Cloud internal WS. i.e: List users: http://.dev.learningcloud.me/integration/ws/management/rest/users Training This web services are responsible for training management. Prefix is /ws/training and they are redirected to Central web services. The way to request these services is adding the prefix to the corresponding WS. More information about Central WS i.e: If we make a request to list all courses in Central, we make the request to http://vm45.netexlearning.cloud/admin/rest/administration/api/courses . If we want the request to go through the centralized endpoint, we will make the request to http://netex.dev.learningcloud.me/integration/ws/training/admin/rest/administration/api/courses Header parameters, query parameters or form parameters are also redirected to the destination web service Social Social web services are those of the homonymous platform. Prefix is /ws/social and they are redirected to Social. Its operation is analogous to the previous section. 

Get current configuration Retrieves the currenct configuration URL: /integration/ws/management/rest/emailServer Method: GET Headers: Accept: version/format header X-Cloud-Auth-Token*: authorization header Responses: 200: OK. Body: commonId: entity commonId. extendedASCII: marked when the external server admit all the RFC email combinations. externalId: extenral Id. hostname: host of the email server. id: internal id. password: email server password. port: email server port. serverEnabled: if the param is marked as true, then we use the external email server, if not, we use netex email server . username: email server username. example URL: http://netex.local.cloud.me:8180/integration/ws/management/rest/emailServer Response example: Response { "commonId": "ae4024d91d2d41daa731042f8e8fe6f7", "extendedASCII": false, "externalId": null, "hostname": null, "id": "402881f2715a205101715a28c6740000", "password": null, "port": 25, "serverEnabled": false, "username": null } Update email server configuration Updates the currenct configuration URL: /integration/ws/management/rest/emailServer Method: POST Headers: Accept: version/format header X-Cloud-Auth-Token*: authorization header Body: commonId: entity commonId. extendedASCII: marked when the external server admit all the RFC email combinations. externalId: extenral Id. hostname: host of the email server. id: internal id. password: email server password. port: email server port. serverEnabled: if the param is marked as true, then we use the external email server, if not, we use netex email server . username: email server username. Responses: 200: OK. Body: commonId: entity commonId. extendedASCII: marked when the external server admit all the RFC email combinations. externalId: extenral Id. hostname: host of the email server. id: internal id. password: email server password. port: email server port. serverEnabled: if the param is marked as true, then we use the external email server, if not, we use netex email server . smtpAuth: indicates we use smtp protocol to connect with the email server. username: email server username. example URL: http://netex.local.cloud.me:8180/integration/ws/management/rest/emailServer Response example: response expand source

List users Obtains a list of users (always synchronously). Url: /integration/ws/management/rest/users Method: GET Headers: Accept: version/format header X-Cloud-Auth-Token*: authorization header  Parameters: startIndex: index of the first user to list count: maximum number of users to list (default and limit 500) Responses:  200: OK. Content: status: generic status location: generic location of the resultant resource, if any message: generic success or error message, if any responsePlatforms: response for every platform it concerns. Each one with the content: status: status in the platform location: location of the resultant resource in the platform, if any message: success or error message in the platform, if any Url example: http://.learningcloud.me/integration/ws/management/rest/users Parameters example: startIndex: 5 count: 3 Response example: {  "aboutMe": "Soy una niña a la que le gusta mucho vestir con una caperuza roja.",· "email": "caperucita.roja@netex.com",  "enabled": true,  "extra": {},  "id": "ff8081814fb1ee7f014fb1f319800000",  "image": {  "url": "/opt/cloud/netex/2015/09/09/b59236b6-9fef-4225-9e3d-ea999036e3e2.jpg"  },  "interests": "Llevar comida a mi abuelita, asustarme con el lobo feroz.",  "language": "es",  "location": null,  "mobilePhone": "222222222",  "name": "Caperucita",  "officePhone": "111111111",  "roles": {  "social": ["user"],  "training": ["user"],  "management": ["user"]  "play": ["user"]  },  "surname": "Roja",  "timezone": "Europe/Paris",  "username": "caperucita.roja"  }, {  "aboutMe": "I'm the title character and protagonist of the novel Oliver Twist by Charles Dickens. I was the first child protagonist in an English novel.",  "email": "oliver.twist.pero@netex.com",  "enabled": true,  "extra": {},  "id": "ff8081814fb1ee7f014fb20105ba0004",  "image": {  "url": "/opt/cloud//netex/2015/09/29/bfc5296d-e36f-4888-bfef-74643c220e50.jpg"  },  "interests": "I want some more",  "language": "en",  "location": "London",  "mobilePhone": "222222222",  "name": "Oliver",  "officePhone": "111111111",  "roles": {  "management": ["user"],  "social": ["user"],  "training": ["user"]  "play": ["user"]  },  "surname": "Twist",  "timezone": "Europe/London",  "username": "oliver.twist"  }, {  "aboutMe": "Hiperbólico andaluz, poeta de odas y madrigales, anciano, miserable y ciego.",  "email": "max.estrella@netex.com",  "enabled": true,  "extra": {},  "id": "ff8081814fb1ee7f014fb201ea240008",  "image": {  "url": "/opt/cloud/netex/2015/09/09/a6d831d1-e6f7-42bd-a8f8-30cb138796a3.jpg"  },  "interests": null,  "language": "es",  "location": "Madrid",  "mobilePhone": "222222222",  "name": "Max",  "officePhone": "111111111",  "roles": {  "social": ["user"],  "training": ["user"],  "management": ["user"]  "play": ["user"]  },  "surname": "Estrella",  "timezone": "Europe/Paris",  "username": "max.estrella" }

Version/Format header To specify the version of WSs to use or the format in which we want the response, we must send the header Accept : application/vnd.netex.nlc-api(.{version})?(+{format})? version: optional. Allowed values are: management: v1.0.0, v1.0.1. If no value is specified, last version will be used. training: v1, v2. If no value is specified, last version will be used. format: optional. Allowed values are json, plain and xml. If no value is specified, json will be used. * This header has no effect if the section is social. * This header has no effect if the section is management (always uses last version and json). Authorization header To specify the authorization of the WS, we must send the header X-Cloud-Auth-Token. The value of this header can be obtained in Netex Cloud ('Your account'). Sync header We must send the header header X-Cloud-Synchronization to specify the timing of the WS. The allowable values are: synchronous: synchronous from the WS version. When a call to a WS of Cloud with this type is made, calls to other platforms (Central, Social, etc) that makes the web service run as synchronous. I.e., waiting for each of these calls end to return the result of the service call. Thus, calls to this type of service are, as a general rule, slower to type asynchronous but we make sure that the changes have spread to the rest of the platforms. In the event that an error occurs in any of the calls to the platforms, is you will inform us in response. asynchronous: asynchronous version of the WS. When a call to a WS of Cloud with this type is made, each call to other platforms that service, generates a message in a queue that will be processed asynchronously. It is not expected to get reply from the WS of other platforms which, as a general rule, such calls are less than those of type synchronous response time. However, not sure what changes have also propagated in other platforms once we get the response of completion of the service. Therefore we will not know immediately if operations are performed successfully, or an error occurs. If no value is specified is used asynchronous.

Get user Obtains a user (always synchronously) by id or username. Url: /integration/ws/management/rest/users/ Method: GET Headers:  Accept: version/format header  X-Cloud-Auth-Token*: authorization header  Responses:  200: OK. Content: status: generic status location: generic location of the resultant resource, if any message: generic success or error message, if any responsePlatforms: response for every platform it concerns. Each one with the content: status: status in the platform location: location of the resultant resource in the platform, if any message: success or error message in the platform, if any Url example by user id:  http://netex.dev.learningcloud.me/integration/ws/management/rest/users/ff8081814fb1ee7f014fb20105ba0004 Url example by username:  http://netex.dev.learningcloud.me/integration/ws/management/rest/users/oliver.twist Response example: { · "aboutMe": "I'm the title character and protagonist of the novel Oliver Twist by Charles Dickens. I was the first child protagonist in an English novel.", · "email": "oliver.twist.pero@netex.com", · "enabled": true, · "extra": {}, · "id": "ff8081814fb1ee7f014fb20105ba0004", · "image": { · "url": "/opt/cloud//netex/2015/09/29/bfc5296d-e36f-4888-bfef-74643c220e50.jpg" · }, · "interests": "I want some more", · "language": "en", · "location": "London", · "mobilePhone": "222222222", · "name": "Oliver", · "officePhone": "111111111", · "roles": { · "management": ["user"], · "social": ["user"], · "training": ["user"] · "play": ["user"] · }, · "surname": "Twist", · "timezone": "Europe/London", · "username": "oliver.twist" }

Create user Creates a user. Url: /integration/ws/management/rest/users Method: POST Headers: Accept: version/format header  X-Cloud-Auth-Token*: authorization header  X-Cloud-Synchronization: synchronization header Content-Type*: application/json Parameters: user*: user to create: username: user's username password: user's password name: user's name surname: user's surname language: user's language code timezone: user's timezone code email: user's email officePhone: user's office phone number mobilePhone: user's mobile phone number interests: user's interests aboutMe: user's information location: user's location authSource: system where user credentials are validated, LOCAL if not specified image: user's image. Can be specified as: url: url in which the image is stored ({"url": "image_url"}) base64: image data ({"base64Image": "image_data", "mimeType": "image_mimeType"}) enabled: user's activation status roles: user's roles. Specified as a map with the section as key and the role list as value. Allowed values are: management:  , mandatory at least one of the following) : user, groupadmin, admin training: user, trainer, groupadmin, admin social: user, admin play: user, author, validator, admin Responses:  200: OK. Content: status: generic status location: generic location of the resultant resource, if any message: generic success or error message, if any responsePlatforms: response for every platform it concerns. Each one with the content: status: status in the platform location: location of the resultant resource in the platform, if any message: success or error message in the platform, if any 400: If you send a request without a username or the username you want to change already exists Url example:  http://.learningcloud.me/integration/ws/management/rest/users Response example (synchronous): Header Location: http://.learningcloud.me/integration/ws/management/rest/users/ff808181556ee70e015571fe3d52000e { "location": null, "message": "", "responsePlatforms": { "training": { "location": null, "message": null, "status": 201 }, "social": { "location": null, "message": null, "status": 201 }, "play": { "location": null, "message": null, "status": 201 }, "management": { "location": null, "message": null, "status": 201 } }, "status": 201 } Response example (asynchronous): { "location": null, "message": "", "responsePlatforms": { "training": { "location": null, "message": null, "status": 202 }, "social": { "location": null, "message": null, "status": 202 }, "play": { "location": null, "message": null, "status": 201 }, "management": { "location": null, "message": null, "status": 201 } }, "status": 201 }

Update user Updates a user by id or username. Url: /integration/ws/management/rest/users/ Method: PUT Headers:  Accept: version/format header  X-Cloud-Auth-Token*: authorization header X-Cloud-Synchronization: synchronization header Content-Type*: application/json Parameters:  user*: user to update: name*: user's new name surname*: user's new surname language*: user's new language code timezone*: user's new timezone code email*: user's new email username*: new username officePhone: user's new office phone number mobilePhone: user's new mobile phone number interests: user's new interests aboutMe: user's new information location: user's new location authSource: system where user credentials are validated image: user's new image. Can be specified as: url: url in which the image is stored ({"url": "image_url"}) base64: image data ({"base64Image": "image_data", "mimeType": "image_mimeType"}) enabled: user's new activation status roles: user's new roles. Specified as a map with the section as key and the role list as value. Allowed values are: management: mandatory at least one of the following: user, groupadmin, admin training: user, trainer, groupadmin, admin social: user, admin play: user, author, validator, admin, groupadmin talent: admin, employee content: author, manager, reviewer, projectowner extendedFields: Key/value map for customer extended field user values externalId: user's external id extra: Responses:  200: OK. Content: status: generic status location: generic location of the resultant resource, if any message: generic success or error message, if any responsePlatforms: response for every platform it concerns. Each one with the content: status: status in the platform location: location of the resultant resource in the platform, if any message: success or error message in the platform, if any Url example by user id:  http://netex.dev.learningcloud.me/integration/ws/management/rest/users/ff808181556ee70e015572136a250012 Url example by username:  http://netex.dev.learningcloud.me/integration/ws/management/rest/users/restuser.acme Response example (synchronous): { "location": null, "message": "", "responsePlatforms": { "training": { "location": null, "message": null, "status": 200 }, "social": { "location": null, "message": null, "status": 204 }, "play": { "location": null, "message": null, "status": 204 }, "management": { "location": null, "message": null, "status": 204 } }, "status": 204 } Response example (asynchronous): { "location": null, "message": "", "responsePlatforms": { "training": { "location": null, "message": null, "status": 202 }, "social": { "location": null, "message": null, "status": 202 }, "play": { "location": null, "message": null, "status": 204 }, "management": { "location": null, "message": null, "status": 204 } }, "status": 204 }

Change password Changes a user's password (always synchronously) by id or username. Url: /integration/ws/management/rest/users//changePassword Method: PUT Headers: Accept: version/format header  X-Cloud-Auth-Token*: authorization header  Parameters: newPassword*: user's new password Responses:  200: OK. Content: status: generic status location: generic location of the resultant resource, if any message: generic success or error message, if any responsePlatforms: response for every platform it concerns. Each one with the content: status: status in the platform location: location of the resultant resource in the platform, if any message: success or error message in the platform, if any Url example by user id: http://.learningcloud.me/integration/ws/management/rest/users/ff808181556ee70e015572136a250012/changePassword Url example by username: http://.learningcloud.me/integration/ws/management/rest/users/restuser.acme/changePassword Parameters example: newPassword: 1234 Response example: { "location": null, "message": "", "responsePlatforms": { "management": { "location": null, "message": null, "status": 204 } }, "status": 204 }