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 can 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 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. This means that we will have three cards because 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	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 of 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 Click here to learn more about card types and templates.

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 with the subscriptions that are relevant to them. Go 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 in the Info tab, or the parameters defined in 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 in the Info tab, or parameters defined in 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. An 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 more 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, so we advise defining 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 don't need to subscribe explicitly 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 more details about 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, so that 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 requests 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.

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:
- 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 datasets in a user's context for URLs, and make changes to the code.

Data Endpoint URL¶

Data can be fetched from multiple endpoints. To add a new endpoint, 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, the /TeamDetails URL is called only once for all the 100 employees. If the Shared URL option is selected, 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 a URL

URLs Details View¶

Action	Details
URL	The endpoint 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 endpoint 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`. Click here to learn more about the Query URL.
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 URLs except for the type `query`.
Collection Handling	Determines how the server processes data returned from the query. Click here to learn more about collection handling.
Image Paths	Specify the path of the image to be embedded in an HTML card. Click here to learn more about image paths.
Shared	If the data fetched by the Primary URL is not unique to the user context, the Shared checkbox can be selected. When selected, the mobile services server fetches the data from this URL only once for all the users. This option is available for all URLs 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. Click here to learn more about share query result data.
News Enabled	Show data as a news feed in the iOS extension and Android widget. Click here to learn more about news enabled.

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
OData Version 2 XML Feed
OData Version 2 (SAP)
OData Version 4

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:

Query URL Collection Root (Required)
Query Entity Key Paths (Required)
Query Entity Wrapper
News Enabled

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:

Share Query Result Data
News Enabled

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 Entity Key Paths (Required)
Share Query Result Data
News Enabled

Query URL Collection Root¶

Identifies the array that contains the entities.

Specifies a JSON path pointing to the start of the JSON array from where the card resources should be extracted. 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 doesn't need to be specified. The relative path is specified in the HTML file. For more information, 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

The mobile services server uses SAP Business Technology Platform destinations to make internet requests, so 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.

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 a news feed in the iOS extension and Android widget.

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 at runtime, meaning that 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 user's 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 a 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 -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 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 has 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 to perform the action.

Actions Table Bar¶

Action	Details
Add	Add an Action
Expand all nodes of the table	Expands all the nodes in the Actions Table.
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 to learn more about parameters.

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. Click here to learn more about Behaviour after Action.	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. Click here to learn more about Consider Action As.	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 easily.

Example

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

The Consider Action As value can be assigned as follows:

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 in the Actions Tab.
Subscription Parameters	Parameters to be used in the query or primary URL, that help 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 z` ‒ `2001.07.04 AD at 12:08:56 PDT` ○ `EEE, MMM d, ''yy` ‒ `Wed, Jul 4, '01` ○ `h:mm a` ‒ `12:08 PM` ○ `hh 'o''clock' a, zzzz` ‒ `12 o'clock PM, Pacific Daylight Time` ○ `K:mm a, z` ‒ `0:08 PM, PDT` ○ `yyyyy.MMMMM.dd GGG hh:mm aaa` ‒ `02001.July.04 AD 12:08 PM` ○ `EEE, d MMM yyyy HH:mm:ss Z` ‒ `Wed, 4 Jul 2001 12:08:56 -0700` ○ `yyMMddHHmmssZ` ‒ `010704120856-0700` ○ `yyyy-MM-dd'T'HH:mm:ss.SSSZ` ‒ `2001-07-04T12:08:56.235-0700` ○ `yyyy-MM-dd'T'HH:mm:ss.SSSXXX` ‒ `2001-07-04T12:08:56.235-07:00` ○ `YYYY-'W'ww-u` ‒ `2001-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 more 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 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 by selecting 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 the rule. ‒ Move the rule up. ‒ Move the rule down.

Note

Only one push notification message can be sent for each card and the rules are evaluated sequentially. This means that 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	Differentiates between the states of the same card. For example, this id will change if the state of a card is changed from development to productive or prototype.
Last Modified At	Time at which the card was last modified.
Last Modified Tag	Identifies if the Card on SAP Business Application Studio is the same as the card on SAP mobile service cockpit. If the tag is different, you should either deploy the card in SAP Business Application Studio as a new card or download the card present on SAP mobile service cockpit.
Mobile Service	Name of the Mobile service deployed on SAP Business Application Studio.
Mobile Service URL	URL of the deployed mobile service.

Note

When a card is deployed for the first time, click to fetch the Card ID and Reference Card Type ID. These IDs reflect the information of the card deployed on the server that are required to launch the emulator.
Select 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. Interactive HTML elements such as input fields, buttons, drop-down lists, date pickers, etc. cannot be used in the card. Design the card accordingly.

SAP Mobile Cards provides an option to perform actions and collect user input. Click here to learn more about actions.

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

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.

You can specify the path to the actual JSON reference in the HTML file.

Auto complete for HTML files is supported in SAP 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 dataset 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 will 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 be displayed 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 e-mail to an e-mail ID displayed on the card, the e-mail 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 e-mail client with the enclosed e-mail 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; it can be used to open a web page with data specific to a 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.

Import .ttf files of your custom fonts to the project.

In template.css file, add a new font-face.

You must define a @font-face as follows:

@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;

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 "Note"

1	`The emulator currently does not support custom fonts.`

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

Last update: November 18, 2021

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

Developing SAP Mobile Cards¶

Card Types and Templates¶

Card Metadata¶

Info Tab¶

Operational Tab¶

Grouping¶

Sub-Grouping Cards¶

Cross Grouping Cards¶

Data Refresh Mode¶

URLs Tab¶

Data Endpoint URL¶

Data Endpoint URL Action Bar¶

URLs Details View¶

Query URL¶

Generic REST API¶

OData Version 2 XML Feed¶

OData Version 2 (SAP)¶

OData Version 4¶

Query URL Collection Root¶

Query Entity Key Paths¶

Query Entity Wrapper¶

Image Paths¶

Share Query Result Data¶

News Enabled¶

HTTP Request Headers¶

Subscription Parameters¶

Subscriptions Details View¶

Select List¶

URL Parameters¶

Actions Tab¶

CSRF Token URL¶

Actions Table Bar¶

Actions Table¶

Action Parameters¶

Action Headers¶

Details View¶

Behavior After Action¶

Consider Action As¶

Parameters¶

Auto Replaced Parameters¶

Header Tab¶

Notifications Tab¶

Lifecycle Tab¶

Design the Card UI¶

Data Mapping¶

Test Data for Designing¶

Content-Based Actions¶

Using Custom Fonts¶