Extending Subscribed Mobile Development Kit Apps in SAP Business Application Studio¶

As a multi-tenant Mobile Development Kit app subscriber, metadata for the application is automatically updated into your SAP account. In your sub-account SAP Business Application Studio instance, you can customize the application metadata by creating an MDK Subscription App Extension project.

Creating a New Extension Project¶

Log on to SAP Business Application Studio and navigate to your workspace.
On the welcome screen, choose New Project from Template. Select MDK Subscription App Extension template and choose Start.

In the Basic Information tab:

Field	Description
`Your Project Name`	Enter a project name.
`Mobile Application URL`	Enter the SaaS mobile application URL.
`Choose a target folder`	By default, the target folder uses project root path. However, you can choose a different folder path.

Choose Next.

In the Application Passcode tab:

Enter the passcode generated by clicking Open a new browser page to generate your application passcode. Detailed information about the base project will be displayed in the Application Details section.

Choose Finish.

The newly created project is now available in your workspace. The new project automatically downloads the metadata for the base application and stores it in the .base folder.

Extend Project Based on Extension Points¶

Switch to MDK project explorer.
Make changes using MDK editor. All the changes will be saved in .mergemap file in extension project. The content of base project is read-only and cannot be changed.

Extend Metadata¶

The defined extension points can be viewed in the editors to identify where customization can be made. The editor will automatically store and merge the customizations into the .mergemap files.

The following metadata types support extension points:

JSON File

Mobile Development Kit supports extending JSON files with .mergemap files. The JSON files include: * Page * Fragment * Application.app * Service * Action * Global

After creating extension project, open it in SAP Business Application Studio and switch to MDK project explorer. The explorer will combine base and extension project metadata.

For example, when user wants to extend test.page from base project:

Click it from extension project in MDK project explorer
Customize it in page editor
After saving, the original test.page is not changed, but it will generate a test.mergemap file.
Next time when you open test.page from extension project, Mobile Development Kit editor will automatically merge test.page and test.mergemap.

Note

Editor can highlight controls with extension points.
Editor can show extension point details.
Editor can validate changes with extension points.

Below is a mergemap example of: * Change the caption to new caption * Insert an action bar item in begin * Insert 2 key value items into section SectionKeyValue0

[
    {
        "_Name": "Customers_Detail",
        "Caption": "new caption"
    },
    {
        "_Name": "bar1",
        "Items": {
            "Add": [
                {
                    "IndexAfter": -1,
                    "Value": {
                        "_Name": "ActionBarItem0",
                        "Caption": "save",
                        "Position": "Left",
                        "IsIconCircular": false,
                        "Visible": true
                    }
                }
            ]
        }
    },
    {
        "_Name": "SectionKeyValue0",
        "KeyAndValues": {
            "Add": [
                {
                    "IndexAfter": -1,
                    "Value": {
                        "Value": "Value",
                        "_Name": "KeyValue2",
                        "KeyName": "KeyName1",
                        "Visible": true
                    }
                },
                {
                    "IndexAfter": 0,
                    "Value": {
                        "Value": "Value",
                        "_Name": "KeyValue3",
                        "KeyName": "KeyName2",
                        "Visible": true
                    }
                }
            ]
        }
    }
]

Below is a mergemap example of: * Change order of action bar item * Insert a new action bar item

[
    {
        "_Name": "bar1",
        "Items": {
            "_Order": [
                "ActionBarItem1", "ActionBarItem0"
            ],
            "Add":[
                {
                    "IndexBefore": -1,
                    "Value": {
                        "_Name": "ActionBarItem2",
                        "Caption": "new",
                        "Position": "Right",
                        "IsIconCircular": false,
                        "Visible": true
                    }
                }
            ]
        }
    }
]

Rule File

Open rule editor, only the content within extension point is editable, the rest is read-only. Changes are saved into .mergemap files.

Below is an example to add extension point demo1 with one line of script:
```
[
    {
        "Name": "demo1",
        "Value": [
            "caption=\"new caption3\";"
        ]
    }
]
```
I18n and Style File

Merge extension project with base project. The extension metadata has higher priority.

User can edit in code editor, it supports code completion and validation. In object browser it can show the content both in extension and base project.
Other File

Currently, we don’t support extending following files: * Extension * Image

Validate Extension Points¶

As the changes are made in the editor, .mergemap file will be generated. If the changes are not allowed due to the extension points, the Problem view will automatically open and show the error details.

Switch to MDK project explorer.
Click validate button next to the project to validate all the generated .mergemap files.
After you run validation, the Problem view will display errors, if any.

The validation will validate the .mergemap files based on the extension points.

Sync Latest Base (Optional)¶

After creating an extension project, if there's another update to the base project, the extension developer can update the local base project by:

Switch to MDK project explorer.
Right-click the extension project and select Check Base to check the version information of the base project. If SAP Business Application Studio base project version doesn't match, a dialog box with the option to get the latest base project will be displayed.

Build in Local (Optional)¶

Before uploading the extension project to mobile services, user can build in local to verify if it's compatible with base project by:

Switch to MDK project explorer.

Right-click the extension project and select Build.

After build process, a report file ep-using.json will be generated in the .build folder.

[
    {
        "file": "Application.mergemap",
        "ext": [
            {
                "propeties": {
                    "OnLaunch": [
                        "InsertEnd"
                    ],
                    "Version": true
                },
                "name": "baseCRUD"
            }
        ]
    },
    {
        "file": "Pages/Main.mergemap",
        "ext": [
            {
                "propeties": {
                    "ActionBar/Items": [
                        "InsertEnd"
                    ],
                    "ToolBar/Items": [
                        "InsertEnd"
                    ]
                },
                "name": "Main"
            }
        ]
    },
    {
        "file": "Rules/GetCaption.mergemap",
        "ext": [
            {
                "name": "demo1"
            }
        ]
    }
]

Deployment¶

User can deploy extension project in SAP Business Application Studio.

The deployment content only contains metadata from extension project.

By default, it triggers process of syncing and building base project in local automatically. You can change it in user settings. Check User Settings.

Switch to MDK project explorer.
Click Deploy button next to the project to upload the extension project to SaaS mobile services application. The project will be activated if there is no error.

Last update: October 13, 2023