Skip to content

Developing SAP Mobile Cards

Abstract

All the features and guides useful for an SAP Mobile Cards Developer are listed on this page.

SAP Mobile Cards developers are responsible for building and designing cards. Developers may use SAP Web IDE or SAP Business Application Studio for their development tasks.

Card Types and Templates

There are two categories of SAP Mobile Cards:

  • Single Instance Cards - Data is fetched from one or many back-end entities but the information is rendered in a single card. The URL defined in the URLs tab fetches data that can be rendered in one instance of the card on the device

    Example

    If an employee requests for a leave, the data will come from different back-end entities such as employee details, leave details etc. Though the information is fetched from different entities, it can only be rendered in a single card.

    A single instance card can have more than one card in the group. However, to create each card an action must be performed by the server or the end-user.

    Example

    Suppose you create a single instance product card and subscribe to it. The card can have information from different entities such as product and supplier details. If you define a query to fetch information for a particular product by defining a subscription parameter, now based on the user input, the card will be rendered for that particular product. Therefore, in this case the number of cards is not determined by the Query URL, but by an action being performed.

  • Multi Instance Cards - A collection of cards added or removed by the queries executed by the server. The number of cards created is equal to the number of entity sets returned by the Query URL, which can be 0 or n.

    Example

    A manager has three leave requests, the query URL gets a list of the three leave requests, and each list item will be rendered as a card with employee information and the type of leave requested. We will thus have a three cards as the number of cards is defined by the number of results returned by the query URL defined in the URLs tab.

Card Metadata

The metadata properties of a card are defined in the metadata.json file. You can edit the metadata using the metadata editor or the default code editor.

The metadata.json file has multiple tabs in the Metadata Editor.

Tab Name Details
Info Define the Template Details and Card Template properties.
Operational Define the operation settings such as gatekeeper, and refresh mode.
URLs Manage data endpoint definitions, retrieve data sets for URLs, and make changes to the code.
Actions Define front-end actions and the operations to be performed on the back end.
Header Create custom HTTP headers to be sent with the card.
Notifications Enable and define push notification rules at the card level.
Lifecycle Enables a developer to set card versions.

Info Tab

Field Details
Name Name of the card as seen by the users on the device.
Version Version of the card.
Destination Define the source of back-end business data for the card.
Select a destination from the drop-down list. The list contains all the destinations that are configured in the mobile services connectivity feature.
To create new destinations for SAP Mobile Cards click here.
Description Add a short summary for the card in the default language. This description is shown to the end user in the Subscription menu and on the back of the card.
Card Template Single Instance or Multi-Instance
To read more about card types and templates click here

Operational Tab

Field Details
Gatekeeper Select a gatekeeper to limit card subscriptions to specific roles associated with users. This allows you to provide users only the subscriptions that are relevant to them.
Navigate to the Gatekeeper section to see how this feature is configured.
Grouping Lets you create a group for cards based on certain properties.
In the drop-down menu, select either the global parameters defined under the Info tab, or the ones defined under the URLs tab as the grouping property.
Sort by URL Parameter Sort the cards in a group by selecting the sorting property.
The group name is not visible in the app.
From the drop-down menu, you can select an available group name.
The group names are based on either global parameters defined under the Info tab, or ones defined under the URLs tab.
Select the Data Type of the sort parameter from the drop-down list: Boolean, Date, Numeric or String.
Data Refresh Mode Define how often mobile services should check for changes on the card. If changes are available, mobile services supplies a new copy of the card when the client requests one. It improves optimization and performance.
Click here to see the details of all the data refresh modes.
Query Refresh Mode Define how often mobile services should query the back-end server.
Keep up-to-date: queries are automatically executed and are always up-to-date
Use daily interval: queries are executed once daily at the specified time.
Use custom interval: queries are executed based on the data refresh time specified by the developer.
Query Refresh Time Define the daily or custom time interval for the selected Query Refresh Mode.
Deep Link URL Define a related webpage URL for any Card Template. The option appears for each card instance as an Open (Details) Action in the end-user's app.
Admin can define a related webpage URL for any card template so that the user can open the relevant webpage for each card instance in the app. The deep link URL can be parameterized with any card type or instance parameter, including the userId.
This URL can also be configured using HTML. For further details click here.
Web Page Expression Match The match expression is a string with embedded pattern references {$1}, {$2}.... The pattern can have any number of references, with a minimum of 1 reference. If there are multiple possible matches in the server, the first successful match is used. It is not possible to predict what match is found first by the server. Thus, it is advised to define match expressions that are unique across cards.
Available only for Single Instance cards
Automatic Subscription Automatically pushes the card to the user's deck. You needn't explicitly subscribe to these cards.

Grouping

By default, the SAP Mobile Cards client groups all the card instances created for one Card Template. This feature is customizable, allowing users to either sub-group card instances within a Card Template or cross group card instances across Card Templates.

The Grouping ID is selected from a drop-down list in which the items are generated based on the parameters defined. For further details on creating parameters click here.

Sub-Grouping Cards

Divide the card instances created by a single Card Template into multiple sub-groups. The grouping is done on the basis of the grouping parameter selected. Though a Static Parameter can be used, usually a URL parameter is used as the Grouping ID.

Example

Let's say a Sales Order Card Template has over 50 card instances. By default, all the 50 cards are grouped together. To improve visibility and accessibility, the developer decides to group the Sales Order Card based on the Purchaser ID. So they select Purchaser ID as the Grouping ID, thus the cards are divided into 10 different sub-groups. Each group contains cards with the same Purchaser ID.

Cross Grouping Cards

Group card instances created across multiple Card Templates into a single group. Grouping is done based on the grouping ID selected. Either a Static Parameter or a URL parameter is used as the Grouping ID.

Example

Let's say an end-user has five leave request and five equipment request cards which the user has to Approve or Reject. A developer can set a Grouping ID to group these functionally similar cards, enabling the end-user to see all the 10 cards that require an action in a single group.

Data Refresh Mode

Data Refresh Mode specifies how often the server checks for changes on the card. If changes are available, the server supplies a new copy of the card when the client requests one. This helps in improving optimization and performance.

1
2
3
4
5
6
7
8
Refresh is performed by the client asychonously when:

* The client app is launched
* The client app is brought to foreground
* The deck is swiped down by the user (pull refresh)
* The refresh is an asynchronous request
* Every 5 minutes when the app is in the foreground 
* Every 20 minutes when the app is in the background
  • Keep up-to-date ‒ Every time a refresh is triggered by the client or 30 seconds after the previous refresh, the server checks for changes. If the server detects any changes, a new copy of the card is sent to the client.

    The server sends a silent notification when the deck is ready and can be downloaded by the client. This requires the:

    • Notifications to be enabled on the device
    • Notifications to be configured for the app store client when using an app store client or custom configuration when using a cloud build client

    Note

    The background execution is triggered by the operating system. Based on the power profile, it might be blocked.

    On iOS, the number of silent notifications is limited to around 3 notifications every hour. The notifications may disappear if the app is rarely used.

  • Use daily interval ‒ The developer defines the Data Refresh Time. The server checks for changes only if the card was last sent to the client before the data refresh time and if the current time is later than the data refresh time. If the server detects changes, a new copy of the card is sent to the client.

    Example

    If the data refresh time is 11:00 AM, and a client refreshes cards at 8:00 AM, the server does not check for changes; however, if the client refreshes at 11:30 AM, the server does send a new copy of the card if any changes are detected.

  • Use custom interval ‒ The server checks for changes only if the card is older than the data refresh time. If the server detects changes, a new copy of the card is sent to the client.

  • Destination Managed ‒ The destination server is responsible for updating the card content. This mode can only be used by Back-end Managed Cards.

URLs Tab

Select URLs to manage data endpoint definitions, retrieve data sets in a user's context for URLs, and make changes to the code.

Data Endpoint URL

Data can be fetched from multiple end-points. To add a new end-point, click Add URL in the Data Endpoint URL Action Bar. This creates a new entry in the Data Endpoint URL table. Select the table entry to open the URL n View, where 'n' is the number of the URL.

For single instance cards, each new URL is called once, unless it is a Shared URL.

Example

A Primary URL /Employees returns the details of all the 100 employees in the system. To fetch the team details, URL /TeamDetails is called only once for all the 100 employees. If the Shared URL option is checked, the URL is called only once for all the employees and the URL will be called again only if the refresh interval has expired.

For a Multi Instance Card Template, each new URL is called n times, where 'n' is the number of instances that Query URL returns.

Example

A Query URL /Employees returns the details of all the 100 employees in the system. Suppose you make subsequent calls to fetch the salary and personal details, URL /SalaryDetails is called 100 times, and URL /PersonalDetails is called 100 times.

Data Endpoint URL Action Bar

Action Details
add
Add
Add a URL

URLs Details View

Action Details
URL The end-point entered in the text-box is appended to the destination specified, and fetches the data from a back-end server.
This option is available for all URLs except for the type query.
Query The end-point entered in the text-box is appended to the destination specified, and fetches the data from a back-end server.
The Query URL determines the number of card instances that need to be created. The number could be 0, 100 or more.
Query URL can only be defined once for a Multi Instance Card. It is always the first entry in the Data Endpoint URL table, and can be identified with the type query.
For more details on Query URL click here.
Destination Select a destination for the defined URL. If the destination is not selected, the URL will use the default destination specified in the Info Tab.
This option is available for all URL except for the type query.
Collection Handling Determines how the server processes data returned from the query.
For more details on collection handling click here.
Image Paths Specify the path of the image to be embedded in an HTML card.
For more details on image paths click here.
Shared If the data fetched by the Primary URL is not unique to the user-context, the Shared checkbox can be checked. When checked, the mobile services server fetches the data from this URL only once for all the users. This option is available for all URL except for the type query.
Share query result data The server stores a copy of the query result in an in-memory cache, and if the same data is requested again, the cache copy is shared with the user, avoiding multiple calls to the back-end system.
This option must be selected only when the data is not user-specific.
For more details on share query result data click here.
News Enabled Show data as news feed in the iOS extension & Android widget.
For more details on news enabled click here.

Note

The view to the right of the Data Endpoint URL table changes based on the Card Template and the selection made in the Data Endpoint URL Table.

Query URL

The Query URL options change based on the Collection Handling - a method to control how the server processes data returned from the query. Currently, the following Collection Handling methods are supported:

Generic REST API

REST-API handling of data returned from queries; excludes anything that is SAP-specific. The options under this collection handling method are:

OData Version 2 XML Feed

Previously known as the "Default OData" option, OData Version 2 XML Feed is an OData Version 2-specific handling of data returned from queries. The server executes the collection query, identifies the individual entities, executes the query for each entity, and fetches each individual entity in the collection with a GET query. The back-end system must therefore support entity GET queries.

The options under this Collection Handling method are:

Note

The query should return an OData collection.

OData Version 2 (SAP)

SAP-specific handling of data returned from queries. The Query URL Collection Root, Query Entity Key Paths and Query Entity Wrapper are defined by the server.

The options under this collection handling method are:

OData Version 4

OData Version 4-specific handling of data returned from queries, especially for cards in which the wrapper property needs to be empty.

The options under this collection handling method are:

Query URL Collection Root

Identifies the array that contains the entities.

A JSON path pointing to the start of the JSON array from where the card resources should be extracted is specified. The server extracts individual entities from the result set.

If Query Entity Wrapper is configured, each JSON entity is embedded in its wrapper.

Query Entity Key Paths

A comma-separated array of JSON path values that identifies properties in the extracted JSON for each entity. These values represent the key parameters, which can be used to construct a unique identifier for the card. For example:

  • If the collection root is $.d.results, then the key path to a property ID would be $.d.ID
  • If the collection root is $.value.results, then the key path to a property ID would be $.value.ID

For non-SAP OData systems, the Query URL Collection Root and Query Entity Key Paths must be specified; these values are optional for an SAP OData system. Remember that there is a relationship between Query Entity Key Paths and Query Entity Wrapper, which helps ensure that the query retrieves the correct data set. For example:

  • If Query Entity Key Paths is set to $.d.SalesOrderID, then the Query Entity Wrapper must be set to "d".
  • If Query Entity Key Paths is set to $.SalesOrderID, then the Query Entity Wrapper must be empty.

Query Entity Wrapper

Define a root element for the extracted JSON user data. All user data is positioned as child elements of the entity wrapper value.

For example: When 'd' is used as an entity wrapper, the following JSON data

{
 "name": "John Doe",
 "id": "123ABC"
}

becomes:

{
 "d": {
   "name": "John Doe",
   "id": "123ABC"
 }
}

The Query Entity Wrapper is set to a default value when either OData Version 2 or OData Version 4 is selected as the Collection Handling.

Image Paths

Images can be added in a card. Following are the various ways in which the image path can be defined:

  • Image is present in the folder structure - The image path need not be specified. The relative path is specified in the HTML file. To know more, see Designing the Card UI.
  • Image is present in the destination - Specify the relative path in the image path field. This path is appended to the URL defined in the destination to fetch the image.
  • Image is present in the absolute HTTP URL - Specify the absolute URL in the image path field.

    Note

    mobile services server uses SAP Business Technology Platform destinations to make internet requests. Hence a destination needs to be specified in mobile services to use the absolute path in the image path field.

  • Image path is present in the response JSON - Specify the JSON path in the image path field.

Note

To use multiple images, use a comma separated list.

Share Query Result Data

The server stores a copy of the query result in an in-memory cache, and if the same data is requested again, the cache copy is shared with the user, avoiding multiple calls to the back-end system.

Note

This option must be selected only when the data is not user-specific.

News Enabled

Show the data returned by the URL as news feed in the iOS extension & Android widget.

SAP Mobile Cards on Android and iOS

Checking this box enables the Share query result data checkbox and creates the following parameters:

  • TodayExtensionTitle ‒ (required) defines the title for the news cards.
  • TodayExtensionBody ‒ text that's shown in the news feed. (optional)
  • TodayExtensionURL ‒ add any image URL that is to be shared. (optional)

HTTP Request Headers

Add a custom HTTP header, method, and body for each URL. This header is sent as part of the URL request.

Subscription Parameters

Subscription parameters can be defined for single and multi instance card templates. When you specify a value for the parameter, it is directly substituted in the query or primary URL at runtime.

Example

If you specify a value for the country parameter, this value will replace ${country} in the following query/primary URL during runtime, i.e sales orders for the specified country will be returned.

Subscriptions Details View

Specify the details for the item selected in the Subscription Parameter Table.

Option Details
Name Property name.
Label Card title that appears on the users screen.
Data Type Data type of the input parameter, such as Edm.String or Edm.DateTime.
Maximum Length Maximum length of the input parameter.
Default Value Specify default value for the subscription property.
Is Key Indicates whether the property is a key.
Is Nullable Indicates whether the property is nullable. Typically, it is true or false.

Select List

The SelectList Data Type allows you to create a drop-down list for user-input.

You can define a Label for each option, and the value can either be a variable of text provided in the Value field.

URL Parameters

The value of a variable from JSON data can be saved as a URL Parameter. This parameter can be used in other URLs and actions, or for sorting and grouping.

Example

In this tutorial, a URL Parameter is used in the subsequent URL.

In this tutorial, a URL Parameter is used in an Action.

There are other parameter types as well in SAP Mobile Cards; click here for details.

Actions Tab

SAP Mobile Cards allows the end users to perform actions based on the context of the current card instance. These actions can either be simple option clicks such as Approve, Reject, Call, Book etc. or the user will have to enter details in a form.

CSRF Token URL

Specify a URL from which the CSRF token must be extracted.

Example

A POST operation on the back-end system may require a GET operation because the GET operation retrieves a CSRF token. The URL refers to the service document root within which the action URL is defined.

If a CSRF token is required, set the following values for the action headers:

  • Header Name ‒ X-Requested-With
  • Header Value ‒ XMLHttpRequestAction

This ensures that the necessary privileges are in place for performing the action.

Actions Table Bar

Action Details
add
Add
Add an Action
expand
Expand all nodes of the table
Expands all the nodes in the Actions Table.
collapse
Collapse All nodes of the table
Collapses all the nodes in the Actions Table.

Actions Table

  • Action: View of all the Actions in use.
  • Actions: Add or Delete Action Parameters

The Action entries in the table can be expanded or collapsed to view the parameters and headers of an action.

Action Parameters

The end-user provides the input in a form for the action parameters. When an end-user clicks on the action, this form is shown. The action is successfully completed once the input is provided.

Example

Tutorial coming soon.

SAP Mobile Cards has different types of parameters; click here for details.

Action Headers

Add a custom HTTP header for an action. This header is sent as part of the URL request. Actions that specify a CSRF Token URL must specify Action Headers.

Details View

Specify the details for the item selected in the Actions Table.

  • Action Details:

    Option Details Mandatory
    Name Name of the action. Yes
    Label Label for the action that an end-user will see. Yes
    URL The URL to be invoked on the back-end system to execute the operation.
    The URL is relative to the destination provided for the card.
    Yes
    Behaviour after Action Determine if the action can be performed multiple times or if the card should be deleted once the action is performed.
    For more details on behaviour after action click here.
    Yes
    HTTP Method Choose an HTTP Method from: POST, PUT, PATCH, DELETE, GET. Yes
    Consider Action As Assign contextual icons for actions on Android to make the interaction with actions fast and easy.
    For more details on consider action as click here.
    Yes
    Show in Notification Center Specify whether to show the action in the device's notification area.
    If this option is enabled, you can add at most one String Parameter.
    No
    Action Body Data that is supplied to execute the action. It is applicable for PUT, POST, and PATCH methods. No
  • Parameter Details:

    Option Details Mandatory
    Name Property name Yes
    Label Title that appears on the card No
    Data Type Data type of the input parameter, such as Edm.String or Edm.DateTime Yes
    Maximum Length Maximum length of the input parameter No
    Default Value Specify the default value for the action property No
    Use For Notification If this action is enabled to appear in the device's notification center, select this option for at least one parameter that needs to be used for the notification. The data type of this parameter must be "string" and the maximum length is 255 characters No
    Is Key Indicates whether the property is a key No
    Is Nullable Indicates whether the property is nullable No
  • Request Header Details:

    Option Details
    Name Name of the header.
    Value Value to be passed with the header (optional).

Behavior After Action

Defines the status of a card instance upon the completion of a successful action performed on the card instance.

  • ACTIVE ‒ Allows another action to be performed on the card instance upon successful completion of an action.
  • INACTIVE ‒ Disables actions specified in the actions tab on the card instance upon successful completion of an action.
  • DELETE ‒ Removes the card instance upon successful completion of an action.

Consider Action As

Contextual Icons can be set for actions on an Android Device. Such icons allow the end-user to identify the required action quickly and work on it in a hassle free manner.

Example

Consider a use case where a card has three actions - Approve, Reject, and Comment.

The Consider Action As value can be assigned as following:

Action Details Image

The actions on an Android Device are:

Android Quick Actions Image

The icons accompanying the action make it easier for the end-user to interact with it.

Parameters

In SAP Mobile Cards a developer can store a variable value in Parameters. The different kinds of parameters available on SAP Mobile Cards are:

Parameter Type Details
Global Parameters Parameters that are available in the entire context of the card. For example, a global parameter can be used in the Actions tab, Info tab, a Header tab, etc.
Global Parameters are created in the Info tab.
URL Parameters Parameters that store the data retrieved from a URL. For example, store the Customer ID in a URL Parameter and then use that parameter to fetch the Customer details only for that Customer.
URL Parameters are created in the URLs Tab.
Action Parameters Parameters that store the input provided by an end-user. For example, if a Leave Request Rejection action requires a reason. An action parameter can be created to collect the end-user's input.
Action Parameters are created under an Action in the Actions Table present in the Actions Tab.
Subscription Parameters Parameters to be used in the query or primary URL, that helps the end users customize the content viewed.
Subscription Parameters are created in the URLs tab.
Auto Replaced Parameters These parameters are automatically replaced with actual values at runtime, enabling users to obtain localized or customized cards.

Auto Replaced Parameters

The parameters defined here are automatically replaced with actual values at runtime, enabling users to obtain localized or customized cards.

Property Details
UserId The user’s ID is automatically returned by the authentication provider.
For example, if the user ID is ´JohnDoe´, and the input is:
${userId} - it is replaced with JohnDoe
${userId:lower} - it is replaced with ´johndoe´
${userId:upper} - it is replaced with JOHNDOE
Language This property returns localized data that is supported by the back end.
For example, if the locale configured on the device is English, then ${language} is replaced by en.
Current server time (xsddatetime) Returns the current server time in UTC.
For example, if the user input is ${xsddatetime}, the value returned is 2017-10-28 19:05:01.
Custom date time Returns date and time based on the pattern and duration. You can define a date or time format, including epoch (such as seconds or milliseconds from January 1st 1970, 0:00:00 UTC).
Syntax: ${DT<pattern>;<duration>}
Valid patterns and their corresponding results include the following:
yyyy.MM.dd G 'at' HH:mm:ss z2001.07.04 AD at 12:08:56 PDT
EEE, MMM d, ''yyWed, Jul 4, '01
h:mm a12:08 PM
hh 'o''clock' a, zzzz12 o'clock PM, Pacific Daylight Time
K:mm a, z0:08 PM, PDT
yyyyy.MMMMM.dd GGG hh:mm aaa02001.July.04 AD 12:08 PM
EEE, d MMM yyyy HH:mm:ss ZWed, 4 Jul 2001 12:08:56 -0700
yyMMddHHmmssZ010704120856-0700
yyyy-MM-dd'T'HH:mm:ss.SSSZ2001-07-04T12:08:56.235-0700
yyyy-MM-dd'T'HH:mm:ss.SSSXXX2001-07-04T12:08:56.235-07:00
YYYY-'W'ww-u2001-W27-3
Duration is specified as PnYnMnDTnHnMnS, where:
P (required) is the period
nY is the number of years
nM is the number of months
nD is the number of days
T is the start of a time section
nH is the number of minutes
nS is the number of seconds
You can prefix - or + to add or subtract duration.
For example, ${DTyyyy-MM-dd'T'HH:mm:ss.SSSZ;-P4D}.
For epochs use:
○ es ‒ UNIX time, seconds since 01.01.1970 0:00:00 UTC
○ eS ‒ Java time, milliseconds since 01.01.1970 0:00:00 UTC
For example, ${DT:es;+P1M}
Longitude and Latitude Returns the current location of the SAP Mobile Cards client and pushes location-relevant cards to the client.
Location services must be enabled on the SAP Mobile Cards client.
For example, if the user input is ${long} and ${lat}, the values returned are http://sample.openweathermap.org/data/2.5/weather?lat=${lat}&lon=${long}&appid=b6907d289e10d714a6e88b30761fae22

For information, see:

Header Tab

In SAP Mobile Cards a developer can send additional information to the server in the form of headers. These headers are created in the Header Tab.

  • Request HTTP Method - Depending on the back-end system, select a RequestHttpMethod; GET, or POST.
  • Request Body - Data that is supplied to execute the HTTP Method.
  • Header Definitions Table - List of all the Request Headers.
  • add Add Header Option - Add a new request header.
  • Request Header n View - Provide the following details for the Request Header:
    • Header Name - Unique name that contains only alphanumeric characters and dashes.
    • Header Value - A value that cannot begin or end with spaces. (optional)

Notifications Tab

The SAP Mobile Cards iOS and Android client supports push notifications. The developer can enable this feature and define rules to send specific push notification messages.

  • Push Notification Definition - Enable or Disable push notifications for this Card Template using the Enable push notification for this Card Template checkbox.
  • Push Notification Strings - Define the notification message for the following use cases:
    • New Card Notification - Specify the notification message to be sent when a new card is added.
    • Changed Card Notification - Specify the notification message to be sent when an existing card is updated.
  • Push Notification Rules - Define custom rules to trigger a notification message.

    Field Value
    Name Select parameters from the drop-down list for new rules. These parameters are populated from the Global Parameters List and URL Parameters List.
    Operator Apply operands to operators to form a rule.
    Data Type The type of data being used.
    Note: The data type of the parameter and the Values should be the same.
    Value The comparison value used by the operator.
    Second Value The second comparison value used by the operator.
    Note: Used when a range is specified; For example, if the operator "between" is used.
    Date Format Date format of the string to be parsed in the JSON property.
    Note: This property can be defined only if the Data Type is Date.
    Message Notification message to be sent when the conditions are met.
    Action Perform the following actions:
    delete ‒ Delete the rule.
    up ‒ Move the rule up.
    down ‒ Move the rule down.

    Note

    Only one push notification message can be sent for each card and the rules are evaluated sequentially. Therefore, the rule that evaluates to true first sends the message.

Lifecycle Tab

A developer can set the card version, launch the emulator and navigate to SAP mobile service cockpit.

Field Value
Card ID Unique card identifier.
Reference Card Type ID
Last Modified At Time at which the card was last modified.
Last Modified Tag
Mobile Service Name of the Mobile service deployed on Business Application Studio.
Mobile Service URL URL of the deployed mobile service.

Note

When a card is deployed for the first time, click refresh to fetch the Card ID & Reference Card Type ID. These IDs reflect the information of the card deployed on the server that are required to launch the emulator.
Select journey-arrive to launch SAP mobile service cockpit

Design the Card UI

SAP Mobile Cards is a card based micro application. The design of the cards can be changed as needed. The developer will need HTML, CSS, and JavaScript skills to design a card.

A card has two views on the device - Front and Back. Each side's design is defined in an HTML file. The design of a card is defined in the following files:

  • template_en.html - HTML code that defines the design of the front of a card.
  • templateBack_en.html - HTML code that defines the design of the back of a card.
  • template.css - CSS style sheet that defines the custom styling of a card.

Note

The card portion is read-only, i.e. interactive HTML elements such as input fields, buttons, drop-down lists, date pickers etc. cannot be used in the card. Thus, the card must be designed accordingly.

SAP Mobile Cards provides an option to perform actions and collect user input. For details please click here.

A developer can see the design changes without having to deploy the card each time on a device. For more details on SAP Mobile Cards preview click here.

Data Mapping

SAP Mobile Cards renders the card with data fetched from the back-end system. To show the data on the card, the developer specifies the relative path of the data.

In the HTML file, the path to actual JSON path reference can be specified.

Auto complete for HTML files is supported in Business Application Studio.

Example

When a Sample Sales Order Template is created, the following data is retrieved for each item.

    {
        "resourceIdentifier": "SalesOrderHeaders('9AD82F55-DE96-4777-AFAE-3A02EBABB245')",
        "data": {
            "d": {
                "CreatedAt": "/Date(1528994068446)/",
                "CurrencyCode": "EUR",
                "CustomerDetails": {...},
                "CustomerId": "79F57743-A752-4C12-B491-817CD500AC8F",
                "GrossAmount": "3185.630",
                "Items": {...},
                "LifeCycleStatus": "N",
                "LifeCycleStatusName": "New",
                "NetAmount": "2677.000",
                "SalesOrderId": "9AD82F55-DE96-4777-AFAE-3A02EBABB245",
                "TaxAmount": "508.630",
                "__metadata": {...}
            }
        }
}

Since Sample Sales Order Card is a Multi Instance Card, the data-set contains multiple data items. This data collection is stored in a collection root called results that is specified in the URLs tab.

The relative JSON path dataSets.[0].data.d.xxx is determined using the result data retrieved by the URL and the query collection root.

To access data retrieved by URL 1, URL 2 etc. the URL number is specified dataSets.[1].data.d.xxx, dataSets.[2].data.d.xxx etc.

Test Data for Designing

While developing SAP Mobile Cards, a developer can view how the design would look in the Mobile Card Pane. This preview pane renders the card using the test data stored in userdata.json.

Any changes made to userdata.json will reflect in the Mobile Card Pane.

The content of userdata.json is determine by the URL. In the URLs tab when a developer clicks Save the data is saved into userdata.json.

Note

The data in userdata.json is used only for development. The data on a device will be dynamically rendered based on the data retrieved from the back-end system.

Content Based Actions

Using SAP Mobile Cards, you can create actions based on the data field.

SAP Mobile Cards supports action functionality - end users can perform actions based on the context of the current card instance. Developers can create custom actions or content-based actions.

Content-based actions are defined in the HTML file based on the data field.

To enable content-based actions, the data must be enclosed in a <div> tag with a specific class.

Example

To send an email to a mail id displayed on the card, the email Id field must be enclosed in a div class of c2g_email

<div class="c2g_email">
    {{d.results.[0].SupplierDetails.EmailAddress}}
<\div>

SAP Mobile Cards interprets the class and creates an action to launch the default email client with the enclosed email Id as the recipient.

Email Action Image

The list of currently supported content based actions are:

Class Action Name Action Details
c2g_email Email abc@xyz.com Open the default e-mail client and add the data-field as the recipient
c2g_address Open Maps Open the default maps client and search for the data-field
c2g_phoneNumber Call +1-1111
SMS +1-1111
Call the number in the data field
Open the SMS app and add the number in the data field as the recipient
c2g_website Open (Details) Open the data field in the default web browser
This tag enables each card instance to open a specific web-page; thus, it can be used to open web-page with data specific to card
Deep Link URL in the Info Tab opens the same web-page for all card instances

Example

Follow this tutorial to create content based actions.

Using Custom Fonts

You can add and configure custom fonts in SAP Mobile Cards.

  1. Import .ttf files of your custom fonts to the project
  2. In template.css file, add a new font-face

    You must define a @font-face as following:

    @font-face {
        font-family: 'Font Name';
        src: url (<URL for font>) format('<font-type>');
    }
    
    Attribute Detail
    font-family Name of the font that can be used in the CSS file
    src Relative path of the font file
    font-type Font file type.
    Valid formats are truetype (.ttf), webopenfont (.woff), webopenfont2 (.woff2), and opentype (.otf)

    Example

    @font-face {
        font-family: 'CustomFont';
        src: url('3270Medium.ttf') format('truetype');
    }
    
    (...)
    
    font-family: Custom, Helvetica, Arial;
    
  3. To use your custom font add it as a font-family in your class

Custom Font View In SAP Business Application Studio

  • After designing the card, Deploy and Publish it to see the changes on your device.

!!! note The emulator currently does not support custom fonts.

You can change the font by defining the font type in template.css file.


Last update: April 14, 2021