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.
1 2 3 4 5 6 7 8 |
|
-
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¶
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:
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.
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.
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 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
, andPATCH
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:
The actions on an Android device are:
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
orPOST
. - 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.
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 newfont-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 aretruetype (.ttf)
,webopenfont (.woff)
,webopenfont2 (.woff2)
, andopentype (.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.
- After designing the card, Deploy and Publish it to see the changes on your device.
!!! note "Note"
1 |
|
You can change the font by defining the font type in the template.css
file.