Skip to content

Using the Mobile Sample Service

A sample OData Enterprise Sales and Procurement Model (ESPM) service is available for developers to use during development and testing. The sample OData service also lets you evaluate how delta tokens are handled in your test application. The sample back end should not be used for production. Prerequisites include:

  • The Developer role.

  • For the Developer role, the runtime root URL is the application service URL to which the sample OData service is binding, for example, <application_service_url>/SampleServices/ESPM.svc/OData_version.

  • Click the metadata URL to view the sample OData entities and their metadata.

Administrators can view the sample back-end service via the cockpit. View the root service and metadata URLs, and generate sample sales orders and purchase orders for multiple entity sets. View the data for each entity in a separate text file, and reset the sample data.

When developers add the Mobile Sample OData ESPM feature to an application, the Mobile Connectivity feature is also added, if it has not already been added, and a destination named com.sap.edm.sampleservice.v4 is automatically created in Mobile Connectivity. Sample OData can be consumed via the Mobile Connectivity service, as well as be consumed directly via the Sample OData runtime URL (for example,<application_service_url>/SampleServices/ESPM.svc/OData_version).

Delta tokens let you retrieve the changes that have been applied to a service. You can send a request to the back end and the delta token is appended to the response.

By default, the application uses the following settings to provide a security check, and enable the developer to access the service using the following URLs:

  • Version 4: https://<application_service_url>/com.sap.edm.sampleservice.v4
  • Version 2: https://<application_service_url>/com.sap.edm.sampleservice.v2

For the SSO mechanism, Forward Authentication SSO is used, and cannot be modified.

Once you add the service to an application, you can use the service via the cockpit. You can also view the root service and metadata URLs, view the data for each entity in a separate text file, and reset the sample data. You can generate a demo HTTP error if a quantity value of SalesOrderItem is below zero. Use the OData error handling API to show the error for your application.

The demo error handling of OData sample service is to add a data validation functionality for the quantity field of SalesOrderItem. When you try to create or update the quantity value using the POST operation, which is less than or equal to 0, the response is:

<?xml version="1.0" encoding="utf-8"?>
<error xmlns="http://docs.oasis-open.org/odata/ns/metadata">
<code>400</code>
<message>DataServiceException: The value of quantity should be greater than zero.</message><innererror>
<details>com.sap.xscript.data.DataServiceException: The value of quantity should be greater than zero.</details>
</innererror>
</error>

The Products entity includes sample images identified, using the property PictureUrl. You can view the images in the cockpit, and provide image examples for tutorials. You can change the image examples.

EntityType Name="Product">
<Key>
<PropertyRef Name="ProductID"/>
</Key>
<Property Name="Category" Type="Edm.String" Nullable="true" MaxLength="40"/>
<Property Name="CategoryName" Type="Edm.String" Nullable="true" MaxLength="40"/>
<Property Name="CurrencyCode" Type="Edm.String" Nullable="true" MaxLength="5"/>
<Property Name="DimensionDepth" Type="Edm.Decimal" Nullable="true" Precision="13" Scale="4"/>
<Property Name="DimensionHeight" Type="Edm.Decimal" Nullable="true" Precision="13" Scale="4"/>
<Property Name="DimensionUnit" Type="Edm.String" Nullable="true" MaxLength="3"/>
<Property Name="DimensionWidth" Type="Edm.Decimal" Nullable="true" Precision="13" Scale="4"/>
<Property Name="LongDescription" Type="Edm.String" Nullable="true" MaxLength="255"/>
<Property Name="Name" Type="Edm.String" Nullable="false" MaxLength="80"/>
<Property Name="PictureUrl" Type="Edm.String" Nullable="true" MaxLength="255"/>
<Property Name="Price" Type="Edm.Decimal" Nullable="true" Precision="23" Scale="3"/>
<Property Name="ProductID" Type="Edm.Int64" Nullable="false" MaxLength="10"/>
<Property Name="QuantityUnit" Type="Edm.String" Nullable="true" MaxLength="3"/>
<Property Name="ShortDescription" Type="Edm.String" Nullable="true" MaxLength="255"/>
<Property Name="SupplierID" Type="Edm.Int64" Nullable="false" MaxLength="10"/>
<Property Name="Weight" Type="Edm.Decimal" Nullable="true" Precision="13" Scale="3"/>
<Property Name="WeightUnit" Type="Edm.String" Nullable="true" MaxLength="3"/>
<Property Name="Picture" Type="Edm.Stream" Nullable="true"/>
<NavigationProperty Name="Supplier" Type="ESPM.Supplier" Nullable="false" Partner="Products">
<ReferentialConstraint Property="SupplierID" ReferencedProperty="SupplierID"/>
</NavigationProperty>
<NavigationProperty Name="Stock" Type="ESPM.Stock" Nullable="true" Partner="Product">
<OnDelete Action="Cascade"/>
</NavigationProperty>
<NavigationProperty Name="PurchaseOrderItems" Type="Collection(ESPM.PurchaseOrderItem)" Partner="Product">
<OnDelete Action="None"/>
</NavigationProperty>
<NavigationProperty Name="SalesOrderItems" Type="Collection(ESPM.SalesOrderItem)" Partner="Product">
<OnDelete Action="None"/>
</NavigationProperty>
</EntityType>

  1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK.

  2. Select an application.

  3. To use the sample OData service, in the Info tab, click the add icon in the Assigned Features section.

  4. In the Add feature window, select Mobile Sample OData ESPM and click OK.

  5. Select the OData Version, V4 (the default) or V2.

  6. Select the Entity Sets.

  7. Select an operation for the selected entity set.

    • To open or save a text file of the JSON file contents for the selected entity, such as Customers.json, click the display icon.

    • To generate ten sample sales orders (each click generates ten more), click the sales-order icon. icon.

    • To generate ten sample purchase orders (each click generates ten more), click the my-sales-order icon.

    • To reset the data to an initial state of ten records, click the restart icon.

  8. Select a different entity set from the list, such as Customers, Product Categories, Product Texts, Products, and so on.

    You see a table of properties for the selected entity.Entity Properties

    Property Description
    Property Using the new OData framework with its new functionality. The new serviceList of entity properties, such as City, Country, and CustomerId.
    Data Type The property's data type, such as Edm.String, or Edm.DateTime.
    Nullable Whether the property is nullable, typically true or false.
    Property Type The property type, such as Simple.

Once the service is configured, the developer can access it using the following URLs after onboarding:

  • V4: com.sap.edm.sampleservice.v4
  • V2: com.sap.edm.sampleservice.v2

Note

The sample OData service automatically assigns the sample OData destination named com.sap.edm.sampleservice.sample_service_version when you add a sample back-end feature to a mobile application. The sample back-end feature allows you to use the configuration user interface to maintain or configure back-end data. The com.sap.edm.sampleservice.sample_service_version takes care of the runtime connectivity channel from device to OData back end.

Viewing Sample Pictures

You can preview embedded sample back-end images in SAP mobile service cockpit. Prerequisites include:

  • Log into SAP mobile service cockpit with a Developer role.

  • Include the Mobile Sample OData ESPM in the application definition.

  • You must provide the right security information to preview images.

You can preview images in several ways:

  • Direct way: https://<mobile_service_host>/<PictureURL_value>, where the Picture URL is the complete address to access the image.

  • If the Mobile Sample OData ESPM feature has been assigned to an application, you can modify the PictureUrl value, and preview the image.

  • If the Mobile Sample OData ESPM feature has been assigned to an application and a registration has been generated, you can view the PictureUrl with the X-SMP-APPCID in the request header.

  • In SAP mobile service cockpit, select Mobile Applications > Native/Hybrid.

  • Select an application, then select Mobile Sample OData ESPM under Assigned Features (or add it first).

  • Select Products from Entity Sets, and click view data display .

    Open the download to see the Products data, including the Picture URL values for all products in the catalog.

    {
"d":{
"results":[
{
"Category":"Graphic Cards",
"CategoryName":"Graphic Cards",
"CurrencyCode":null,
"DimensionDepth":"35.0000",
"DimensionHeight":"17.0000",
"DimensionUnit":"cm",
"DimensionWidth":"22.0000",
"LongDescription":"Proctra X: PCI-E GDDR5 3072MB",
"Name":"Proctra X",
"PictureUrl":"/imgs/HT-1070.jpg",
"Price":"70.900",
"ProductId":"6041F167-63B2-45EC-BB35-471DDEDCB3A7",
"QuantityUnit":"EA",
"ShortDescription":"Proctra X: PCI-E GDDR5 3072MB",
 ...

  • Use the PictureUrl value to preview the picture, using an available option.

  • (Optional) If the Mobile Sample OData ESPM feature has been assigned to an application, you can visit the picture URL, and preview the image. Use the format:

    <cockpit_admin_url>/app/<app_name>/service/sample-odata-v2-espm/v4/imgs/<picture_name>

Launching the Demo App

Launch a basic Web user interface for the sample service from SAP mobile service cockpit. This demo tool provides developers with a way to see data changes for a mobile client on the desktop, and to generate mobile apps from the annotations to understand how the mobile client works. Keep in mind:

  • The list page only shows the basic type entity attribute. Navigation type entities (which link to another entity) and structure type entities are not supported.

  • Binary type is not supported.

  • Product creation is not supported because of an Xscript OData v2 limitation.

  • When creating the SalesOrderItem, the SalesOrderHeader related information is also needed.

  • For single object creating and editing, only necessary attributes are allowed.

  • The user interface follows standard Fiori Elements behavior. You can upload its customization annotation as well, and the demo application will be rendered using the customized annotation.

Launch the demo app:

  1. In SAP mobile service cockpit, select Mobile Applications > Native/Hybrid.

  2. Select an application, and then under Assigned Features select Mobile Sample OData ESPM.

  3. In the Configuration tab, make sure Version 4 is selected from the OData Version drop-down list.

  4. In Entity Sets, select one of the support sets, which includes Products, Customers, SalesOrderHeaders, and SalesOrderItems.

  5. Select the Launch Demo icon, show-edit .

  6. Log into the Sample Service Demo, based on your application security configuration. The standard screen appears for the entity you selected, such as Customers.

    You can use the demo app as described in Using the Mobile Sample Service, except for exceptions and limitations described in Context.

Last update: October 1, 2024