Skip to content

Developing SAP Mobile Cards

Abstract

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

SAP Mobile Cards developers are responsible for building and designing cards. They use SAP Web IDE or SAP Business Application Studio for their development tasks, such as defining the data-source, designing the cards, defining actions, etc. To onboard themselves, developers should follow the instructions listed on this page.

Card Metadata

The metadata properties of an SAP Mobile Card are defined in the metadata.json file. Using Web IDE or Business Application Studio, you can edit metadata using either 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.
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.

Info Tab

Template Details

Field Details
Name Name of the card as seen by the users on the device.
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.
Ping Click Ping to determine the availability of the selected destination server.
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.

Note

The combination of Name and Destination must be unique.

Card Template

Note

Card Template configurations change based on the Card Template selected. The configurations listed below apply to all the Card Templates unless specified otherwise.

Field Details
Card Template SAP Mobile Cards has five Card Templates. Each Card Template is designed for specific use cases.
To view the details on Card Templates click here
Parameters Create parameters with static values. These parameters can be used in Grouping, Deeplink URLs, Description, URLs Tab, Actions Tab, Header Tab, etc.
For further details click here

Card Types and Templates

There are two categories of 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.

1
2
3
Multi Instance Card Templates are designed for use cases in which an end user wants to receive a set of cards (Zero to Many). Each item in an entity set is represented as a card, and all the cards are grouped in the user's mobile client.

To determine the set of items, the Card Template definition defines a query URL that is used to retrieve the collection from the back-end system. For further details on creating a query URL [click here](#urls-tab).

Operational Tab

Operation Settings

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 Order By property from the drop-down list: Ascending or Descending.
Select the Data Type of the sort parameter from the drop-down list: Boolean, Date, Numeric or String.
Data Refresh Mode Define how often SAP Mobile Services should check for changes on the card. If changes are available, SAP 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.
Refresh Interval If you selected Use custom interval data refresh mode, specify the weeks, days, hours, and minutes at which custom updates occur.
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}.... TThe 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.
Automatic Subscription Automatically pushes the card to the user's deck. You needn't explicitly subscribe to these cards.
Hidden Subscription Enable hidden subscription if you want to limit the developers who can make changes to the card. These cards are hidden in the All Subscription Tab of the user's app. This means that these cards can only be pushed to a device or loaded via a link.
Limit Subscriptions Restrict the end-user access to the card by authorizing select users.
Query Refresh Mode Define how often SAP 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.
Defined only for Multi Instance Card Template.
Query Refresh Time Define the daily or custom time interval for the selected Query Refresh Mode.
Defined only for the Multi Instance Card Template.
Refresh Interval If you selected Use custom interval query refresh mode, specify the weeks, days, hours, and minutes at which custom updates occur.

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.

  • Keep up-to-date ‒ The server checks for changes when the client requests updated content. If the server detects any changes, a new copy of the card is sent to the client.
  • 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 Action Bar

Action Details
Get Data / Retrieve Preview the data set for the card to be delivered. The data set appears under Data in the right pane.
Save Copy the retrieved data to Userdata.json.
For further details click here.
add
Add
Add a URL
expand
Expand all nodes of the table
Expands all the nodes in the Data Endpoint URL Table.
collapse
Collapse All nodes of the table
Collapses all the nodes in the Data Endpoint URL Table.

Data Endpoint URL Table

  • URL: View of all the URLs in use.
  • Actions: Add or delete URL Parameters

The URL entries in the table can be expanded or collapsed to view the parameters and URIs specified for the entry.

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.

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.

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.

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.

Single Instance Cards Options

Following are the options available for single instance cards.

  • Primary URL

    The end-point entered in the Primary URL text-box is appended to the destination specified in the Info tab, and fetches the data from a back-end server.

  • 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.

Multi Instance Cards Options

Following are the options available for multi instance cards.

  • Define Query URL

    Define Query URL is the end-point that is appended to the destination specified in the Info tab* to fetch the data.

    The Query URL determines the number of card instances that need to be created. The number could be 0, 100 or more. Thus, no data is shown for this 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:

    Option Name Details
    Query URL Collection Root
    (Required)
    Identifies the array that contains the entities.
    A JSON path pointing to the start of the JSON array from which 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
    (Required)
    A comma-separated array of JSON path values that identifies properties in the extracted JSON for each entity. These values represent the key parameters that 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.
    Keep in mind 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.
    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.
    News Enabled Adds news feed in the iOS & 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)

    Notice the What's New section in the following image.
    SAP Mobile Cards on Android and iOS
  • 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.

    Option Name Details
    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.
    News Enabled Adds news feed in the "Today's Extension"
    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)
  • 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.

    Option Name Details
    Query Entity Key Paths
    (Required)
    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.
    Keep in mind 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.
    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.
    News Enabled Adds news feed in the "Today's Extension"
    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)

Data Endpoint URL

In Welcome Card, Server Managed Card, Back-end Managed Cards and Automatic Instance Generation templates, data can be fetched from multiple end-points. To add a new end-point, a developer must click on the 'Add URL' Button in the Data Endpoint URL Action Bar. This creates a new entry in the Data Endpoint URL Table. Click the table entry to open the URL n View, where 'n' is the number of the URL.

For Welcome Card, Server Managed Card and Back-end Managed Cards Templates, each new URL is called once per user, unless it is a Shared URL.

Example

A Primary URL /Employees returns the details of all the 100 employees in the system. Each of the subsequent URLs /SalaryDetails and /PersonalDetails are also called only once.

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. Each of the subsequent URLs /SalaryDetails and /PersonalDetails are called 100 times for the 100 employees.

In this view, a developer can do the following:

  • Define the end-point appended to the destination which is specified in the Info tab.
  • Enable sharing of the end-point.

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.

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.

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
    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 Details 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).

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.

Actions Table Image

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 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 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.

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.

An SAP Mobile Card has two views on the device - Front and Back. Each side's design is defined in an HTML file. The design of an SAP Mobile 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 of an SAP Mobile Card 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. The Mobile Card Pane renders the card design using the test data.

To open the Mobile Card Pane, choose one of the following options:

  • Click Mobile Card Pane option in the right hand bar Web IDE Side Bar Image
  • Click ViewMobile Card Pane. Mobile Card Pane Menu Option Image

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.

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.

URLs Tab Results Connection Image

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

Data Binding in Code Image

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

Email Tag Image

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

Tip

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 BAS

  • 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: October 23, 2020