View source for MEC Sandbox Help

= Platform Concepts =
MEC Sandbox is an interactive environment that enables users to learn & experiment with ETSI MEC Service APIs. These standardized RESTful APIs are targeted towards MEC application developers to expose the value added services offered by MEC, including real time access to network and context information, as well as location awareness. The design principles for developing the APIs have also been specified in ETSI GS MEC 009, along with http methods, templates, conventions and patterns. The MEC service APIs are available in YAML and JSON format at https://forge.etsi.org, presented via OpenAPI compliant descriptions.

MEC Sandbox provides the user with a choice of scenarios combining different network technologies (4G, 5G, Wi-Fi) and terminal types. Combining these assets in a geolocated environment, a user can gain hands-on experience on the behavior and capabilities of the Location (MEC013), Radio Network Information (MEC012), WLAN Information (MEC028), Edge Platform Application Enablement (MEC011) and Application Mobility (MEC021) service APIs. Such contextual information can offer significant differential performance for edge based MEC applications.

== MEC Sandbox Concepts & Usage ==
An introduction to MEC Sandbox concepts and usage was presented in a webinar (February 2021). The recording and related Q&A are available here:
* [https://www.etsi.org/events/1869-2021-01-webinar-getting-started-with-the-etsi-mec-sandbox MEC Sandbox Webinar]
* [https://mecsandbox.slack.com/archives/C01NBU36DU4 Q&A]

To access the Q&A users must first join the MEC Sandbox [[#Discussion_Board_.28Slack_channels.29|Discussion Board]].

== Web UI ==
MEC Sandbox Portal is a single page web application that provides an interactive interface; once signed in, it allows a user to experiment with an individual sandbox.

<br>
====Home Page====
* Brief description of the platform
* Links and references to learn more about ETSI MEC
* Control to:
** Navigate through the MEC Sandbox pages
** View version history
** Open the help menu to get started or access this wiki page
** Sign in to the platform

[[File:Page-home.png|border]]

<br>
====Sandbox Dashboard====
When a user signs in, MEC Sandbox creates the necessary backend resources and opens a user-specific sandbox dashboard that allows to:
* Deploy pre-defined network scenarios in the city of Monaco
* Configure terminal devices within the network (add/remove/pause)
* Manage MEC application instance IDs
* Control MEC Services lifecycle (enable/disable)
* Experiment with the MEC Service APIs from the browser by providing a browser based MEC client (SwaggerUI) 
* Alternatively, experiment MEC Services directly from an external application ''(your own or a third party application)''

In both cases, MEC Sandbox APIs respond according to the current state of the network scenario.

More details about the MEC Sandbox UI are provided in the [[#Usage|platform usage]] section of this wiki.

[[File:Page-sandbox.png|border]]

== Terminology ==

<br>
==== Point of Access (POA) ====
A point of attachment to access a network; MEC Sandbox networks supports 4G, 5G and WiFi POAs.
* Each POA has coverage range within which a terminal may attach to the network.
* The PoA range is represented by a circle and its the range varies depending on the network technology
* Both the PoAs and their associated range can be shown or hidden by selecting the appropriate layers on the map.

<br>
==== User Equipment (UE) / Terminal Device ====
A end user devices equipped with a wireless radio that allows to connect to a PoA.
* MEC Sandbox supports three types of UEs; stationary, low-velocity and high-velocity
** UE types are described in more detail in [[#UE_Types|this]] wiki section.
* Number of UEs present in a scenario can be configured
* Each UE has an associated velocity and path that defines how they move on the map; these are fixed in a scenario.
* UEs have their preferred access network types with their preferred order of connection
* Preferred connectivity order is (1) WiFi, (2) 5G and (3) 4G
* The default UE behavior is to remain connected to a POA as long as it is in range unless a higher priority network access becomes available.

<br>
==== Zone ====
A zone is a logical grouping of one or more PoAs, irrespective of their wireless technologies.
* On the map, zones are represented by using color coding.
* The definition of zones help structure the network.
* MEC Location Service (MEC013) can be used to discover zones or UEs present in a zone.

<br>
==== MEC Platform (MEP) ====
A MEC Platform represents a compute node located near the edge of the network.
* On the map, MEP are represented by a cloud icon
* MEC services are offered on MEP nodes via the MEC011 (Mp1) API; they can be discovered and consumed by MEC applications
* MEC applications running on external user equipment can be emulated as running on a MEP node by creating an Application Instance Id for a specific MEP instance.

<br>
==== Network Scenario ====
A simulated network of geo-located UEs and POAs that are grouped in Zones.
* One network scenario can be deployed at a time in a MEC Sandbox instance.
* At any time a user can terminate a scenario or select a new one without requiring to re-create a new sandbox.
* While a network scenario is deployed, requests can be sent to the MEC Service APIs which will return a response
* MEC Services may also generate notifications depending on the subscriptions created by the user
* Both responses and notifications reflect the state of the network at the moment they were generated

= Network Scenarios =
MEC Sandbox currently provides various network scenarios with different assortments of technologies. 
These scenarios were designed to simulate an urban environment using a single mobile network operator with combinations 
of 4G, 5G and WiFi PoAs and one or more MEC Platforms located near the network edge.

MEC Platform node(s) offer different MEC Services to be consumed by MEC Applications, allow MEC Applications to offer their 
new services and enable experimentation of MEC assisted application mobility.

UEs move along their pre-defined path, triggering changes in connectivity and in MEC Service outputs (responses & notifications).

The city of Monaco was chosen as the simulated location as shown on right.

'''Disclaimer:''' PoA characteristics do not reproduce Monaco's a real operator deployment

[[File:Monaco-3D-Satellite.png|border|750px]]

== Networks ==
MEC Sandbox provides the following simulated networks

<br>
==== 4G Macro Network (single MEP) ====
* Contains 10 4G-PoAs grouped into 4 different zones; together, these PoAs cover the entire Monaco area
* Network has a centrally located MEP

[[File:Network-4g.png|border|500px]]

<br>
==== 4G-WiFi Macro Network (single MEP) ====
* Builds on 4G Macro Network by adding 11 WiFi-PoAs distributed throughout the city
* Network has a centrally located MEP

[[File:Network-4g-wifi.png|border]]

<br>
==== 4G-5G-WiFi Macro Network (single MEP) ====
* Builds on 4G-WiFi Macro Network by adding 19 small cell 5G-PoAs distributed throughout the city
* Network has a centrally located MEP (same as 4G Scenario)

[[File:Network-4g-5g-wifi.png|border|500px]]

<br>
==== 4G-5G-WiFi Macro Network (dual MEP) ====
* Baselined on the 4G-5G-WiFi Macro Network 
* Scenario contains 2 MEC Platforms (MEP) geographically distributed within the MEC Sandbox emulated edge network
** MEP1 - Centrally located (as in the Single MEP scenarios)
** MEP2 - located in Zone 4 (green zone)
** Zone 4 (green) specific MEP2

* Two dual MEP scenarios are available:
** Regular path: high & low velocity terminals have the same mobility paths as in other scenarios; MEC021 AMS state transfer events occur infrequently due to the long travel path and not all terminals visiting zone 4.
** Short path: high velocity terminals have shortened mobility paths to increase transitions between zone 3 and 4; MEC021 AMS state transfer events occur frequently due to increased transitions.
[[File:Network-dual-mep-4g-5g-wifi.png|border|500px]]

== UE Types ==
UEs are divided into the following categories:

<br>
==== Stationary UE ====
* They have a static geo location
* They represent smart city IoT connected devices such as street cameras, smart sensors, etc.

[[File:Ue-stationary.png|border|500px]]

<br>
==== Low Velocity UE ====
* They change location relatively slowly
* They represent leisure cyclists or pedestrians moving through the city

[[File:Ue-low-velocity.png|border|500px]]

<br>
==== High Velocity UE ====
* They change location quickly
* They represent motorized vehicles moving along the main city roads

[[File:Ue-high-velocity.png|border|500px]]

 '''NOTE:''' The number of UEs in a network scenario is dynamically configurable, however the positions <br>and paths are the same for all scenarios.

= MEC Services =
<br>
==== MEC011 - Edge Platform Application Enablement (Mp1) ====
MEC Sandbox supports version v2.1.1 of the MEC011 specification, available on [https://www.etsi.org/deliver/etsi_gs/MEC/001_099/011/02.01.01_60/gs_MEC011v020101p.pdf ETSI website]

Mp1 reference point provides two different APIs: MEC Application Support and MEC Service Management

These APIs allow MEC Applications to interact with the MEC System, such as:
* Application registration/deregistration
* Service discovery & advertisement
* Event notifications about service and application availability
* Traffic rules, DNS rules and time of day
MEC Sandbox supports a subset of Mp1 API endpoints and subscription types; for more details on the supported endpoints access the SwaggerUI client in a MEC Sandbox.

<br>
==== MEC012 - Radio Network Information Service (RNIS) ====
MEC Sandbox supports version v2.1.1 of the MEC012 specification, available on [https://www.etsi.org/deliver/etsi_gs/MEC/001_099/012/02.01.01_60/gs_mec012v020101p.pdf ETSI website]

RNIS provides cellular radio network information to edge applications, such as:
* Radio network conditions
* Measurements related to user plane
* Information about UEs connected to the radio network (context, Radio Access Bearers (RAB))
* Notification events such as cell change, RAB establishment and RAB release
MEC Sandbox supports a subset of RNI API endpoints and subscription types; for more details on the supported endpoints access the SwaggerUI client in a MEC Sandbox.

<br>
==== MEC013 - Location Service ====
MEC Sandbox supports version v2.1.1 of the MEC013 specification, available on [https://www.etsi.org/deliver/etsi_gs/MEC/001_099/013/02.01.01_60/gs_mec013v020101p.pdf ETSI website]

Location Service provides geospatial and network location information to edge applications, such as:
* Location information related to user and zones
* Notification events such as user tracking, zonal status or traffic
MEC Sandbox supports a subset of the Location API endpoints and subscription types; for more details on the supported endpoints access the SwaggerUI client in a MEC Sandbox.

<br>
==== MEC021 - Application Mobility Service (AMS) ====
MEC Sandbox supports version v2.1.1 of the MEC021 specification, available on [https://www.etsi.org/deliver/etsi_gs/MEC/001_099/021/02.01.01_60/gs_mec021v020101p.pdf ETSI website]

Application Mobility Service provides support for relocation of user context and/or application instance between MEC hosts.

AMS defines three types of MEC application user-context transfer:
# Application self-controlled
#* Application triggers and executes the context transfer
#* Context is transferred from source to target application
#* MEC system's role is to enable connectivity
# Device assisted
#* Device triggers and executes the context transfer
#* Context is kept on the device
#* MEC system's role is to decide if application mobility is required
# MEC assisted
#* MEC system triggers and assists the context transfer
#* Context is transferred from source to target application
MEC Sandbox focuses on '''MEC assisted''' context transfers; device assisted requires Mx2 (future consideration) and application self-controlled can be realized by a user or MEC App without AMS as user traffic does not reach MEC Sandbox.

<br>
==== MEC028 - WLAN Access Information Service (WAIS) ====
MEC Sandbox supports version v2.2.1 of the MEC028 specifications, available on [https://www.etsi.org/deliver/etsi_gs/MEC/001_099/028/02.02.01_60/gs_mec028v020201p.pdf ETSI website]

WAIS provides WLAN radio network information to edge applications, such as:
* Access point conditions
* Information about terminals connected to the network
* Notification events such as terminal connectivity
MEC Sandbox supports a subset of the WAI API endpoints and subscription types. for more details on the supported endpoints access the SwaggerUI client in a MEC Sandbox.

= Usage =
The following section provides MEC Sandbox usage guidelines.

<br>
==== Sign In ====

The MEC Sandbox home page provides a ''Sign In'' button to initiate a user session.
When clicked, the user is prompted to authenticate with one of the following external OAuth 2.0 providers:
* GitHub: Sign in with a public GitHub account
* GitLab (ETSI): Sign in with an ETSI-On-Line (EOL) GitLab account

To successfully sign in to the MEC Sandbox, the user must have a valid account with one of the above providers,
must successfully sign in, and must accept an authorization request for access to public profile information.
Once signed in and after successful backend resource allocation, the user is redirected to the MEC Sandbox dashboard.

 '''NOTE:''' External OAuth provider login and authorization may be seamless if they have already <br>been performed

[[File:Sign-in.PNG|border|500px]]

<br>
==== MEC Sandbox Dashboard ====
The dashboard is the main screen of the MEC Sandbox; it is divided in 4 main areas that are explained below:
* Map area: Observe physical assets on the map
* Configuration area: Select networks and UEs
* API Console: Investigate MEC API communication
* Try-it area: Details about accessing MEC Service APIs

<br>
==== Map Area ====
Map area allows to observe the location of different assets; it provides the following information and capabilities:
* Zoom control
* Layer selection - display or hide assets
* PoAs
** Icon shows the type of PoA (4G/5G/WiFi)
** Clicking provides details
** PoAs are color coded according to their zone
** Circle surrounding the PoA represents the signal range - also color coded to the zone
* UEs
** Icon shows UE type (stationary/low/high velocity)
** Clicking provides details
** UEs are red when disconnected, blue otherwise
* Compute node
** Dark blue icon shows a cloud
** Clicking provides details
** MEC Application/Services are dynamically updated

[[File:Map.png|border|750px]]

<br>
==== Configuration area ====
Configuration area allows dynamic configuration of the MEC Sandbox; it provides the following capabilities:
* Network selection - deploy/terminate network scenarios
* Pause terminal movement - dynamically start/stop UE movement
* Set the number of terminals - dynamically add/remove UEs by type
* Configure Application Instance IDs - dynamically add/remove IDs

MEC011 API requires Application Instance IDs to be provisioned in the MEC Sandbox prior to using an 
external user MEC Application.

In a real MEC Platform deployment, the Application Instance ID of a MEC Application is provisioned at
orchestration time. 

In the MEC Sandbox, MEC Platforms are emulated and MEC Application orchestration is handled externally;

Application Instance IDs must therefore be provisioned manually.

[[File:Configuration.png|border|500px]]

<br>
==== API Console ====
API console displays a table of real-time requests and notifications that the MEC Service APIs receive and generate.

The table provides a summary of the communication messages, including
* type (request/notification)
* service involved
* endpoint
* HTTP method
*time
*response code.

Requests are HTTP messages received by the MEC Service
* Click on the request line in the table to see the response returned by the MEC Service

Notifications are HTTP message sent by the MEC Service
* These are generated only if a subscription was created in the MEC Service
* Click on the notification line in the table to see details about notification and received response

[[File:Api-console.png|border|750px]]

<br>
==== Try-it area ====
Try-it area provides information on how to access a specific MEC Service API in the MEC Sandbox.

A drop down allows to select the desired MEC API.

 '''NOTE:''' MEC Services are created on Network selection; time must be allowed for the <br>MEC Service to start. 

Selecting a MEC API changes the displayed information in the dashboard.

Application Details show information about the MEC Service application instance; it also provides controls to control MEC Service lifecycle.

Try-it in the browser allows to launch a SwaggerUI client for the selected MEC API

From the client a user can send requests to the MEC Services.

Try-it from your User application provides the link to use to reach the selected MEC API.

 '''NOTE:''' The provided link must be provisioned in an external MEC application that access MEC Sandbox.

== Swagger UI ==
The Swagger UI client is a powerful tool to learn about MEC APIs as it provides curated & browsable information about the API endpoints - but it also serves as an API client allowing to send requests and observe responses.

Next figure shows Swagger UI for the MEC Location Service.
* A header provides API name and details with links to related specifications
* The client is configured to communicate with your own sandbox
* API endpoints are listed along with their HTTP verb - clicking on an endpoint provides more details

[[File:Swagger1.png|border|750px]]

<br>
Next figure shows the documentation details available at the endpoint level:
* A description of the endpoint
* Parameters that may be required when invoking the endpoint
* Possible responses that the endpoint may return
* The <code>Try it out</code> button enables the client mode

[[File:Swagger2.png|border|750px]]

<br>
Next figure shows how a request can be sent to the MEC service running in the MEC Sandbox.

After clicking <code>Try it out</code>, the documentation page changes as follows:
* The parameters area allows to enter values if required; in this example, no parameters are needed
* An Execute button appears; clicking sends the request to the MEC API
* An informational window shows the request and parameters sent using the curl command
** Note that this command can be copied and sent from a Command line terminal
* The server response area shows the values received from the MEC Service API
** Responses can be downloaded

[[File:Swagger3.png|border|750px]]

<br>
== MEC Application ==
MEC Application developers can access MEC Services running in the MEC Sandbox using the base path URL provided in the <code>Try-it</code> area of the Sandbox dashboard. This link routes requests for the selected MEC API to a specific user sandbox.

 '''NOTE:''' Any external application or process with HTTP client capabilities and access to the <br>MEC Sandbox can be used to send requests to the MEC Services (for example ''curl'')

MEC applications must use the provided link as a base path for API requests and must append the desired endpoint path. MEC applications must also provide path, query and body parameters when necessary. For more details on the supported endpoint paths and parameters, access the Swagger UI client in a MEC Sandbox.

For notification subscriptions, MEC applications must provide notification URLs where MEC Service notifications should be sent. If a notification URL points to a publicly accessible endpoint, the API Console will show the request and response data and codes; otherwise, the request will fail and the API console will display a 500 Internal error.

MEC011 API requires Application Instance IDs to be provisioned in the MEC Sandbox prior to using an external user MEC Application. In a real MEC Platform deployment, the Application Instance ID of a MEC Application is provisioned at orchestration time. In the MEC Sandbox, MEC Platforms are emulated and MEC Application orchestration is handled externally; Application Instance IDs must therefore be provisioned manually.

<br>
== Examples ==
This section provides some common usage examples.

<br>
==== Subscriptions ====

The subscription endpoints available in each service are used to register for specific event notifications.

To subscribe for event notifications, a user may use the provided Swagger UI Try it out feature or may directly post a subscription request from a MEC application. In both cases, the subscription request body must contain the following:
* Notification URL where notifications will be sent
* Filter criteria to specify which events to register to

A successful subscription response includes the following:
* Subscription request data
* Subscription resource URL

The resource URL contains a unique subscription identifier that must be provided when updating or deleting a subscription.
|+
| style="text-align: left;" | [[File:Example-subscription.png|border|750px]]
|}

'''Location Subscriptions'''

To register for user location change events, set the following subscription request body:

 {
   "userTrackingSubscription": {
     "clientCorrelator": "0123",
     "callbackReference": {
       "notifyURL": "http://my.callback.com/location-user-tracking/some-id"
     },
     "address": "10.100.0.1",
     "userEventCriteria": [
       "Entering",
       "Leaving",
       "Transferring"
     ]
   }
 }

A successful response for the above subscription request creates a new subscription with and ID of '2', as shows in the following response body:

 {
   "userTrackingSubscription": {
     "address": "10.100.0.1",
     "callbackReference": {
       "notifyURL": "http://my.callback.com/location-user-tracking/some-id"
     },
     "clientCorrelator": "0123",
     "resourceURL": "https://try-mec.etsi.org/sbx123456/location/v2/subscriptions/userTracking/2",
     "userEventCriteria": [
       "Entering",
       "Leaving",
       "Transferring"
     ]
   }
 }

'''RNIS/WAIS/AMS/Mp1Subscriptions'''

The same subscription procedure and concepts apply for other MEC APIs, with the exception of the resource URL response format which sometimes differ. Refer to the SwaggerUI documentation for more details about subscriptions.

 {
   "_links": {
     "self": {
       "href": "https://try-mec.etsi.org/sbx123456/rni/v2/subscriptions/1"
     }
   },
   ...
 }

<br>
==== MEC013 Location API Common Examples ====

'''User Tracking'''

Track UE ''10.100.0.1'' as it moves across PoAs & zones:

 {
   "userTrackingSubscription": {
     "callbackReference": {
       "notifyURL": "http://my.callback.com/location_notifications/userTracking"
     },
     "address": "10.100.0.1",
     "userEventCriteria": [
       "Entering", "Leaving", "Transferring"
     ]
   }
 }

A ''ZonalPresenceNotification'' notification will be sent when UE ''10.100.0.1'' does the following:
* Enters a new zone
* Leaves its current zone
* Attaches to a different PoA within the same zone

 '''NOTE:''' If a UE switches from a PoA in one zone to a PoA in a different zone, then 2 separate <br>notifications are sent, one for leaving the old zone and another for entering a new zone.

'''Zonal Traffic'''

Track all UE location changes within ''zone01'':

 {
   "zonalTrafficSubscription": {
     "callbackReference": {
       "notifyURL": "http://my.callback.com/location_notifications/zonalTraffic"
     },
     "zoneId": "zone01",
     "userEventCriteria": [
       "Entering", "Leaving", "Transferring"
     ]
   }
 }

A ''ZonalPresenceNotification'' notification will be sent when any UE does the following:
* Enters ''zone01''
* Leaves ''zone01''
* Attaches to a different PoA within ''zone01''

'''Zonal Status'''

Track UE number thresholds within ''zone01'':

 {
   "zoneStatusSubscription": {
     "callbackReference": {
       "notifyURL": "http://my.callback.com/location_notifications/zonalStatus"
     },
     "zoneId": "zone01",
     "numberOfUsersAPThreshold": 2,
     "numberOfUsersZoneThreshold": 3
   }
 }

A ''ZoneStatusNotification'' notification will be sent on every change in UE connection count in ''zone01'' where:
* Number of UEs attached to a single PoA is greater than or equal to 2
* Number of UEs in zone is greater than or equal to 3

<br>
==== MEC012 RNI API Common Examples ====

'''Cell Change'''

Track UE ''10.100.0.1'' cell changes:

 {
   "subscriptionType": "CellChangeSubscription",
   "callbackReference": "http://my.callback.com/rni/cellChange",
   "filterCriteriaAssocHo": {
     "associateId": [
       {
         "type": 1,
         "value": "10.100.0.1"
       }
     ],
     "ecgi": [
       {
         "plmn": {
           "mnc": "001",
           "mcc": "001"
         },
         "cellId": "1010101"
       }
     ]
   }
 }

A ''CellChangeNotification'' notification will be sent when UE ''10.100.0.1'' does the following:
* Moves from a 4G PoA to another 4G POA with cell ID ''1010101'', MNC ''001'' & MCC ''001''
* Moves from a 4G PoA with cell ID ''1010101'', MNC ''001'' & MCC ''001'' to another 4G POA

 '''NOTE:''' Moving between a 4G and a non 4G POA will not trigger a cell change notification.

'''RAB Establishment'''

Track UE connections to cell ID ''1010101'':

 {
   "subscriptionType": "RabEstSubscription",
   "callbackReference": "http://my.callback.com/rni/rabEst",
   "filterCriteriaQci": {
     "ecgi": [
       {
         "plmn": {
           "mnc": "001",
           "mcc": "001"
         },
         "cellId": "1010101"
       }
     ],
     "qci": 80
   }
 }

A ''RabEstNotification'' notification will be sent when any UE does the following:
* Moves from a non 4G PoA to a 4G PoA with cell ID ''1010101'', MNC ''001'', MCC ''001'' & QCI ''80''

 '''NOTE:''' MEC Sandbox currently uses a constant QCI value of ''80''.

'''RAB Release'''

Track UE disconnections from cell ID ''1010101'':

 {
   "subscriptionType": "RabRelSubscription",
   "callbackReference": "http://my.callback.com/rni/rabRel",
   "filterCriteriaQci": {
     "ecgi": [
       {
         "plmn": {
           "mnc": "001",
           "mcc": "001"
         },
         "cellId": "1010101"
       }
     ],
     "erabId": 6,
     "qci": 80
   }
 }

A ''RabRelNotification'' notification will be sent when a UE with an Erabid of ''6'' does the following:
* Moves from a 4G PoA with cell ID ''1010101'', MNC ''001'', MCC ''001'' & QCI ''80'' to a non 4G PoA

 '''NOTE:''' A new ErabId is allocated every time a UE connects to a 4G POA and stays unchanged until <br>the UE disconnects from any 4G POA. The RAB Release notification can therefore only be seen once. <br>The ECGI is an optional parameter, omitting it will allow less constraints on the conditions to <br>see the notification.

<br>
==== MEC028 WAI API Common Examples ====

'''Associated Stations'''

Track stations associated to Wifi PoA with MAC ID ''005C02020202'':

 {
   "subscriptionType": "AssocStaSubscription",
   "callbackReference": "http://my.callback.com/wai/assocSta",
   "apId": {
     "macId": "005C02020202"
   }
 }

A ''AssocStaNotification'' notification will be sent when any UE does the following:
* Connects to a Wifi PoA with MAC ID ''005C02020202'';
* Disconnected from a Wifi PoA with MAC ID ''005C02020202'';

<br>
==== MEC011 - MEC Application startup & shutdown ====

Edge Application Enablement Service APIs (MEC011) allow MEC applications to:
* Discover & offer MEC platform services
* Subscribe for application lifecycle and MEC platform service availability notifications

External MEC applications wishing to use these service APIs must follow the startup & shutdown procedures described below.

'''Prerequisites'''

* Login via the frontend & select Sandbox tab
* Select a network to deploy in the user sandbox
* Create a unique MEC Application Instance ID
* Select & copy the MEC Application Support and MEC Service Management API paths
* Provision the instance ID & paths in the external MEC Application

'''Startup Procedure'''

* '''Step 1 -''' Confirm application readiness
Using the MEC application instance ID created with the MEC Sandbox frontend, inform the MEC Sandbox that the MEC application is up & running.

 POST /mec_app_support/v1/applications/bdbda75e-6136-4982-9b64-562e5db3f0bc/confirm_ready
 {
   "indication": "READY"
 }

* '''Step 2 -''' Subscribe for App Termination notifications
Optionally register for an application termination notification. This step is only required to enable graceful application shutdown.

 POST /mec_app_support/v1/applications/bdbda75e-6136-4982-9b64-562e5db3f0bc/subscriptions
 {
   "subscriptionType": "AppTerminationNotificationSubscription",
   "callbackReference": "https://my.callback.com/my.app.endpoint",
   "appInstanceId": "bdbda75e-6136-4982-9b64-562e5db3f0bc"
 }

'''Shutdown Procedure'''

* '''Step 1 -''' Delete the provisioned Application Instance ID
Using the MEC Sandbox frontend, delete the unique MEC application instance ID for the MEC Application to be shutdown.

* '''Step 2 -''' Gracefully terminate MEC Application (optional)
If subscribed for graceful termination, an application termination notification is sent to the registered callback URI.

The MEC application then has 10 seconds to gracefully terminate. It should clean up its resources and deregister any remaining subscriptions.

* '''Step 3 -''' Confirm App Termination
When the MEC application cleanup is complete it should send a confirmation to the MEC Sandbox.

 POST /mec_app_support/v1/applications/bdbda75e-6136-4982-9b64-562e5db3f0bc/confirm_termination
 {
   "operationAction": "TERMINATING"
 }

If the MEC Sandbox receives this confirmation before the shutdown grace period then it immediately clears any remaining resources associated with the application instance. Otherwise it waits for the grace period to expire before clearing the application instance resources. Subsequent requests from this application instance ID are ignored.

<br>
==== MEC011 - MEC Application service consuming use case ====

This use case describes how an external MEC Application discovers available MEC platform services and subscribes for service availability change notifications.

It is assumed that the MEC Application has no prior knowledge of the MEC Services offered by the MEC platform.

'''Procedure'''
	
* '''Step 1 -''' Run MEC Application Startup procedure
Create a sandbox and obtain an application instance ID using the [[#MEC011_-_MEC_Application_startup_.26_shutdown|MEC application startup procedure]].

* '''Step 2 -''' Discover available services
Send a request using the Service Management API to obtain a list of discoverable MEC Services.

 GET /mec_service_mgmt/v1/services

* '''Step 3 -''' Subscribe for service availability notifications
Register for MEC service service availability updates to receive MEC service state change notifications.

 POST /mec_service_mgmt/v1/applications/bdbda75e-6136-4982-9b64-562e5db3f0bc/subscriptions
 {
   "subscriptionType": "SerAvailabilityNotificationSubscription",
   "callbackReference": "http://my.callback.com/mec_service_mgmt_ser_availabilities/some-id",
   "filterCriteria": {
     "serNames": [
       "mec012-1"
     ],
     "states": [
       "ACTIVE",
       "INACTIVE"
     ],
     "isLocal": true
   }
 }

* '''Step 4 -''' Use discovered service
As long as the discovered services remain available, the MEC application may communicate with them. It may send requests or subscribe for event notifications using the using the discovered MEC Service transport information.

* '''Step 5 -''' Disable discovered Service
To simulate a change in service availability, use the MEC Sandbox frontend to disable the MEC Service that the MEC Application is watching.

This triggers a ''SerAvailabilityNotification'' to the registered subscription callback URI with a change type set to ''REMOVED''.

* '''Step 6 -''' Enable discovered Service
Use the MEC Sandbox frontend to enable the MEC Service that the MEC Application is watching.

This triggers a ''SerAvailabilityNotification'' to the registered subscription callback URI with a change type set to ''ADDED''.

* '''Step 7 -''' Run MEC Application Shutdown procedure
Gracefully terminate the MEC Application using the [[#MEC011_-_MEC_Application_startup_.26_shutdown|MEC application shutdown procedure]].

While processing the ''AppTerminationNotification'', unsubscribe from service availability notifications using the subscription ID obtained during registration.

 DELETE /mec_service_mgmt/v1/applications/bdbda75e-6136-4982-9b64-562e5db3f0bc/subscriptions/1

<br>
==== MEC011 - MEC Application service offering use case ====

This use case describes how an external MEC Application offers a MEC platform service for other MEC Applications to use.

'''Procedure'''

* '''Step 1 -''' Run MEC Application Startup procedure
Create a sandbox and obtain an application instance ID using the [[#MEC011_-_MEC_Application_startup_.26_shutdown|MEC application startup procedure]].

* '''Step 2 -''' Register service on the MEC platform
Using the Service Management API, provide the MEC Application service information to the MEC Sandbox.

 POST /mec_service_mgmt/v1/applications/0f576de5-3b22-41e7-a95a-375317fcae31/services
 {
   "serName": "TestServiceName",
   "serCategory": {
     "href": "catItem1",
     "id": "id12345",
     "name": "TestService",
     "version": "v2"
   },
   "version": "2.2.1",
   "state": "ACTIVE",
   "transportInfo": {
     "id": "TransId12345",
     "name": "REST",
     "description": "REST API",
     "type": "REST_HTTP",
     "protocol": "HTTP",
     "version": "2.0",
     "endpoint": {
       "uris": [
         "https://my.callback.com/sbx-test/mep1/test-service/v2/"
       ]
     }
   },
   "serializer": "JSON",
   "scopeOfLocality": "MEC_SYSTEM"
 }

* '''Step 3 -''' Discover newly registered service
Using the returned service instance ID, send a request to retrieve the newly registered MEC Service information.

 GET /mec_service_mgmt/v1/services/0c0f1cca-707a-45aa-a7db-df5120a4692a

* '''Step 4 -''' Deregister service from the MEC platform
Using the application & service instance IDs, send a request to remove the newly registered MEC Service.

 DELETE /mec_service_mgmt/v1/applications/0f576de5-3b22-41e7-a95a-375317fcae31/services/0c0f1cca-707a-45aa-a7db-df5120a4692a

* '''Step 5 -''' Run MEC Application Shutdown procedure
Gracefully terminate the MEC Application using the [[#MEC011_-_MEC_Application_startup_.26_shutdown|MEC application shutdown procedure]].

<br>
==== MEC011 - Scope Of Locality use case ====

This use case describes the impacts of locality & scope of locality on an external MEC Application.

MEC Application locality is determined by MEC platform on which it is deployed.

MEC Service scope of locality is provided at service creation.

MEC Application locality and MEC Service scope of locality are used to determine if a service is discoverable and local to a MEC application.

'''Procedure'''

* '''Step 1 -''' Run MEC Application Startup procedure
Create a sandbox and obtain an application instance ID using the [[#MEC011_-_MEC_Application_startup_.26_shutdown|MEC application startup procedure]].

The ''dual-mep'' network scenario must be selected for this use case; it is the only network with multiple MEC platforms and locality-specific ''Location Service'' instances.

The MEC Application instance ID should be created on MEC platform ''mep1''.

* '''Step 2 -''' Discover available services
Send a request using the Service Management API to obtain a list of discoverable MEC Services.

 GET /mec_service_mgmt/v1/services

* '''Step 3 -''' Subscribe for service availability notifications
Register for MEC service service availability updates to receive MEC service state change notifications.

In this case, register for service availability updates from the Location Service on MEC platform ''mep1''. Set ''isLocal'' to ''true'' in the subscription request to receive notifications for the local ''Location Service'' instance only.

 POST /mec_service_mgmt/v1/applications/1f424790-b7ab-48ba-bb69-7f325fb335c6/subscriptions
 {
   "subscriptionType": "SerAvailabilityNotificationSubscription",
   "callbackReference": "http://my.callback.com/mec_service_mgmt_ser_availabilities/some-id",
   "filterCriteria": {
     "serNames": [
       "mec013-1"
     ],
     "states": [
       "ACTIVE",
       "INACTIVE"
     ],
     "isLocal": true
   }
 }

* '''Step 4 -''' Disable discovered Service in same locality as MEC Application
To simulate a change in service availability, use the MEC Sandbox frontend to disable the local ''Location Service'' instance on MEC platform ''mep1''.

This triggers a ''SerAvailabilityNotification'' to the registered subscription callback URI with a change type set to ''REMOVED''.

* '''Step 5 -''' Disable discovered Service in different locality as MEC Application
To simulate a change in service availability, use the MEC Sandbox frontend to disable the remote ''Location Service'' instance on MEC platform ''mep2''.

Observe that no service availability notification is sent.

* '''Step 6 -''' Enable discovered Service in same locality as MEC Application
Use the MEC Sandbox frontend to enable the local ''Location Service'' instance on MEC platform ''mep1''.

This triggers a ''SerAvailabilityNotification'' to the registered subscription callback URI with a change type set to ''ADDED''.

* '''Step 7 -''' Run MEC Application Shutdown procedure
Gracefully terminate the MEC Application using the [[#MEC011_-_MEC_Application_startup_.26_shutdown|MEC application shutdown procedure]].

While processing the ''AppTerminationNotification'', unsubscribe from service availability notifications using the subscription ID obtained during registration.

 DELETE /mec_service_mgmt/v1/applications/1f424790-b7ab-48ba-bb69-7f325fb335c6/subscriptions/2

<br>
==== MEC021 - MEC Assisted application mobility use case ====

This use case describes how external MEC Applications should use the Application Mobility Service (AMS) API to perform MEC-assisted application context transfers.

Using the AMS API, MEC Applications can register for simulated terminal device Mobility Procedure notifications to trigger user application context transfers across MEC Applications.

MEC Sandbox assumes the following localities:
* MEC Applications on MEC Platform ''mep1'' coverage area: ''zone01'', ''zone02'' & ''zone03''
* MEC Applications on MEC Platform ''mep2'' coverage area: ''zone04''

'''Procedure'''

* '''Step 1 -''' Run MEC Application Startup procedure
Create a sandbox and obtain an application instance ID using the [[#MEC011_-_MEC_Application_startup_.26_shutdown|MEC application startup procedure]].

The ''dual-mep'' network scenario must be selected for this use case; it is the only network with multiple MEC platforms. Once deployed, enable 3 high-velocity UEs and pause UE mobility.

Create two MEC Application Instance IDs; one on each MEC platform.

 '''IMPORTANT NOTE:''' both MEC Application Instance IDs must be created with the same MEC Application name; <br>this informs the Application Mobility Service that the MEC Application instances are for the same <br>MEC Application and therefore candidates for user-context transfers.

* '''Step 2 -''' Discover Application Mobility Service (AMS)
Send a request using the Service Management API to obtain a list of discoverable MEC Services.

Use the service category ''AMSI'' as a query parameter to discover only the AMS services.

 GET /mec_service_mgmt/v1/services?ser_category_id=AMSI

* '''Step 3 -''' Register MEC Application instances with AMS
Using the AMS API, send registration information for the MEC Application instance running on MEC Platform ''mep1'' with device information for UE ''10.100.0.3''. This UE starts in ''zone02'' which is in the coverage area of ''mep1''.

 POST /amsi/v1/app_mobility_services
 {
   "deviceInformation": [
     {
       "appMobilityServiceLevel": 3,
       "associateId": {
         "type": 1,
         "value": "10.100.0.3"
       },
       "contextTransferState": 0
     }
   ],
   "serviceConsumerId": {
     "appInstanceId": "5db16acd-5cb7-496a-9463-f93ad4df663a"
   }
 }

Send registration information for the MEC Application instance running on MEC Platform ''mep2''. This application instance should not provide device information.

 POST /amsi/v1/app_mobility_services
 {
   "serviceConsumerId": {
     "appInstanceId": "a4340837-06ac-484c-ac3c-76a867ab9e03"
   }
 }

 '''NOTE:''' The target MEC Application instance must be registered with AMS to be considered a valid target.

* '''Step 4 -''' Subscribe for AMS Mobility Procedure notifications
Using the AMS API, subscribe the MEC Application instance running on MEC Platform ''mep1'' for Mobility Procedure Notifications.

 POST /amsi/v1/subscriptions/
 {
   "subscriptionType": "MobilityProcedureSubscription",
   "callbackReference": "http://my.callback.com/amsi-mobility-procedure/some-id",
   "filterCriteria": {
     "appInstanceId": "5db16acd-5cb7-496a-9463-f93ad4df663a",
     "associateId": [
       {
         "type": 1,
         "value": "10.100.0.3"
       }
     ]
   }
 }

* '''Step 5 -''' Wait for Mobility Procedure notification
Un-pause UE mobility in the MEC Sandbox frontend and wait for UE ''10.100.0.3'' to attach to a PoA in ''zone04''.

Observe a ''MobilityProcedureNotification'' with the target application information set to the MEC Application instance running on MEC Platform ''mep2''.

* '''Step 6 -''' Perform context transfer and inform AMS
The source MEC Application running on ''mep1'' performs the context transfer to the target MEC Application instance running on ''mep2''.

 '''NOTE:''' The context transfer executes within the user's external environment; it is out of scope of <br>the MEC Sandbox and AMS.

Once complete, the source MEC Application informs the AMS that the context transfer is complete by updating the device context transfer state.

 PUT /amsi/v1/app_mobility_services/1
 {
   "appMobilityServiceId": "1",
   "deviceInformation": [
     {
       "appMobilityServiceLevel": 3,
       "associateId": {
         "type": 1,
         "value": "10.100.0.3"
       },
       "contextTransferState": 1
     }
   ],
   "serviceConsumerId": {
     "appInstanceId": "5db16acd-5cb7-496a-9463-f93ad4df663a"
   }
 }

At this point, the target MEC Application running on ''mep2'' becomes the source MEC Application for future Mobility Procedure notifications. To do so, it must update its AMS registration and subscription to begin tracking the terminal device.

* '''Step 7 -''' Run MEC Application Shutdown procedure
Gracefully terminate the MEC Applications using the [[#MEC011_-_MEC_Application_startup_.26_shutdown|MEC application shutdown procedure]].

While processing the ''AppTerminationNotification'' for each MEC Application instance, unsubscribe from mobility procedure notifications using the subscription ID obtained during registration.

 DELETE /mec_service_mgmt/v1/applications/5db16acd-5cb7-496a-9463-f93ad4df663a/subscriptions/2

<br>
==== MEC011/MEC021 - Using an external application ====

The example described in this section uses an open source external application called Demo3 that can be configured to access ETSI MEC Sandbox and demonstrate interactions with MEC011 and MEC021 services.

Demo3 application is available as part of a project called AdvantEDGE (''[https://github.com/InterDigitalInc/AdvantEDGE GitHub]'', ''[https://interdigitalinc.github.io/AdvantEDGE/ Documentation]''); it is a simplified MEC application composed of a Frontend and Backend.
* '''Frontend''' presents a dashboard to the user for observing application state, controlling MEC011 registration and choosing terminals participating to MEC021 AMS
* '''Backend''' is the MEC Application communicating with MEC Services offered by the MEC Sandbox (MEC011, MEC021) and performing MEC011 registration and AMS management, including state transfers between different MEC021 AMS instances.

Demo3 application is available as a pre-built binary or alternatively can be built from source:
* Pre-built
** Available in the GitHub release bundle, starting with AdvantEDGE v1.8.1 (''[https://github.com/InterDigitalInc/AdvantEDGE/releases here]'')
** ''[https://interdigitalinc.github.io/AdvantEDGE/docs/usage/usage-demo3/#optionally-use-pre-built-binaries-from-github-release Instructions]''
* Built from source:
** ''[https://interdigitalinc.github.io/AdvantEDGE/docs/usage/usage-demo3/#optionally-use-pre-built-binaries-from-github-release Demo3 Build instructions]''
** ''[https://interdigitalinc.github.io/AdvantEDGE/docs/setup/env-dev/#go-toolchain Go toolchain build environment]''
** ''[https://github.com/InterDigitalInc/AdvantEDGE/tree/master/examples/demo3 Demo3 Source Code]''

Demo3 usage synopsis is:
# Provisioning for MEC Application instances
#* MEC Sandbox
#** Login MEC Sandbox
#** Deploy a Dual MEP Scenario (short-path recommended)
#** Configure two Application instance IDs (name: demo3, locality: one on MEP1 and one on MEP2)
#* Demo3
#** Configure two instances (with respective application instance IDs)
#** Start execution of both instances
#** NOTE: The system where each instance is executing must be able to receive MEC Sandbox notifications
# Execution and AMS events
#* From Demo3 Frontend dashboard of each application
#** Register both applications
#** Add tracked terminal(s) to AMS (e.g. 10.100.0.1, 10.100.0.2, etc.)
#** NOTE: terminals should be added to Demo3 instance corresponding to the zone where they are located when added
#** Observe MEC021 Assisted state transfers between both Demo3 instances as terminal transitions between Zone 3 and Zone 4

Detailed steps to use Demo3 with the MEC Sandbox are available [https://interdigitalinc.github.io/AdvantEDGE/docs/usage/usage-demo3/#using-demo3-with-etsi-mec-sandbox here]<br>

= Discussion Board (Slack channels) =
MEC Sandbox questions, feedback and discussions are tracked using slack channels in the '''MEC Sandbox Slack Workspace'''. The workspace is available here:

* [https://mecsandbox.slack.com/ MEC Sandbox Slack Workspace]

New users first need to join the MEC Sandbox slack workspace by creating a new account using the invitation link provided here:

* [https://join.slack.com/t/mecsandbox/shared_invite/zt-npe5mxvk-eOIHwrxtNbYG1OiwavHHDg Join the MEC Sandbox Slack Workspace]
[[File:slack-workspace.png|border|500px]]

= Reporting Issues =
MEC Sandbox issues should be reported on Slack, where they can be discussed with the STF team that maintains the MEC Sandbox.