Unlocking a Fabric App

From 2023.05, Quantum Fabric supports the Unlocking of Fabric Apps, which removes locking for an app. The feature helps you unlock a locked Fabric app and update a client’s requirements in the base app, which you cannot achieve with one of the app extension points.

Use Case: When a partner team wants to customize a locked Infinity app for a client's requirement:

For example,

  • The Country Model bank (client) team wants to implement a local modification on the locked Infinity app but realizes that it is not possible by using the existing extensibility points. In that case, the partner team must either take an unlocked version of the <Infinity> app and apply the client’s changes or create new services to implement logic and configurations. The partner team can use the unlock app feature to achieve this goal.

    NOTE: Only a Fabric user with an Owner role has access to use these commands.

    IMPORTANT: App upgrades for unlocked apps: When a customer imports the updated base application for upgrades, the original base app is upgraded to the existing locked app; it excludes the custom changes made in the unlocked base app.

Prerequisites

  • mflci.jar Version: 9.7.2.0

    Supported commands for the unlocking app feature are as follows:

    • unlock-app

    • merge-app-with-extns

  • Quantum Fabric Version 2023.05

  • Locked Fabric app

How the Unlocking a Fabric App Works:

When a locked Fabric app is unlocked, the MFCLI command removes all lock configurations of the base app and extended folder from the app. And the base app is divided into two different .zip folders.

For example,

  • app_unlocked.zip: You will need this app part to make the required changes in the base app.

  • app_extensions.zip: You will need this app part while merging with the app_unlocked.zip app to create a complete Fabric app.

After you customize the app_unlocked.zip app part in Fabric Console, you need to lock it.

Finally, you must merge the app_unlocked_locked.zip and app_extensions.zip files to create a combined app: app_unlocked_locked_merged.zip.

How to Unlock a Fabric App

Unlocking a Fabric app functionality involves the following three steps:

1. Unlocking the app configurations from the locked base app using the MFCLI

NOTE: You need to have a Fabric user with an Owner role to perform the following steps:

  1. Open the mfcli.jar file path in the command prompt.

  2. Run the “unlock-app” command to unlock a locked app. This command takes the locked app as input and removes all lock configurations of the base app and extended folder from the app.

    • For example:

      for Kony Cloud (manage.kony.com) environment,

      java -jar mfcli.jar unlock-app -u <user> -p <password> -t <account id> -clurl <cloud url> -a <app name> -ua <unlocked app name> -ea <extended app name>

      java -jar mfcli.jar unlock-app -u abc@kony.com -p password -t 100054321 -clurl https://manage.temenos-cloud.com -a ~/../app.zip -ua app_locked.zip -ea app_extended.zip
      for on-premise installation,

      java -jar mfcli.jar unlock-app -u <user> -p <password> -au <Identity URL> -cu <Console URL> -a <app name> -ua <unlocked app name> -ea <extended app name>

      java -jar mfcli.jar unlock-app -u abc@kony.com -p password -au http://10.10.24.79:8080 -cu http://10.10.24.78:8081 -a ~/../app.zip -ua app_locked.zip -ea app_extended.zip


      The following two parts of the base app are extracted to your local system:

      • app_unlocked.zip: It contains all base app details that are not locked. You will use this app to make the required changes. The app_unlocked.zip app is not similar to the locked version of the base app provided to the customer.

      • app_extensions.zip: It contains the extended details part only added to the locked base app, and this is not a complete app. You will need this app part while merging the latest updates you make in the app_unlocked.zip app.

        IMPORTANT:  When you unlock the locked base app, if the app has custom/extended services, these services are available in the app_unlocked.zip and not part of the app_extensions.zip file.

        IMPORTANT: If the app_unlocked.zip has a custom service <CustomService1>, you can unlink the service before you lock the app_unlocked.zip file. Otherwise, the Fabric Console locks the base app and custom services.

       

      • -t, --account

        9 digit id of the Kony Cloud account (visible in top right corner in Console) for e.g. 100054321. Not relevant for an on-premise installation.

      • * -a, --app

        Path of the locked app

      • -clurl, --cloud-url

        URL of cloud instance

        Default: <empty string>

      • -cu, --console

        URL of Kony Fabric Console (without context path), relevant for on-premise installation only. For e.g. http://10.10.24.78:8081

      • -ea, --extended-app

        Name of the app with extensions folder e.g., AppName_extended

      • -au, --identity

        URL of Kony Fabric Identity Services (without context path), relevant for on-premise installation only. For e.g. http://10.10.24.79:8080

      • --mfa

        If specified, multi-factor authentication is enabled. The secret key for multi-factor authentication required for generating one time password (OTP) needs to be specified in the properties file.

        Default: false

      • -p, --password

        Password for the Kony user. This could be plain text or, encrypted using 'encrypt' command. This is mandatory.

      • -ua, --unlocked-app

        Name of the new app zip with lock config and extensions folder removed.

        e.g., AppName_unlocked

      • -u, --user

        Kony user required for authentication, for e.g. abc@kony.com. This is mandatory.

 

2. Customizing the base app using Fabric Console

Ensure that you do not modify the base app details, which can cause runtime issues.

NOTE: You need to have a Fabric user with an Owner role to perform the following steps:

  1. In your Fabric Console, import the app_unlocked.zip, which you have extracted from step 1.

  2. Modify required changes in the app.

  3. Now lock the app_unlocked.zip app in one of the two ways:

    1. In the Apps page, hover your cursor over the App menu button and click the Export Locked App.

      Or, you can access the Export Locked App option within the app when the app is selected.

      The base app configurations are locked, and the current workspace app gets exported to your local system. The app is downloaded with a new name, for example, <app>_unlocked_locked.zip.

3. Merging the updated locked base app with the extended app using MFCLI

Merge the app_unlocked_locked.zip and app_extensions.zip to create a complete Fabric app, as follows:

  1. Open the mfcli.jar file path in the command prompt.

  2. Run the merge-app-with-extns command to merge the locked base app with the extended app.

    • For example,

      for Kony Cloud (manage.kony.com) environment,

      java -jar mfcli.jar merge-app-with-extns -u <user> -p <password> -t <account id> -clurl <cloud url> -la <locked app name> -ea <extended app name> -a <merged app name>

       

      for on-premise installation,

      java -jar mfcli.jar merge-app-with-extns -u <user> -p <password> -au <Identity URL> -cu <Console URL> -la <locked app name> -ea <extended app name> -a <merged app name>

      The locked app with custom changes in the base app version is ready now. For instance, app_unlocked_locked_merged.zip. For example, app_unlocked_locked_merged.zip.

      NOTE: After importing the merged .zip file, you can link services as part of the extension, which will be available as unlocked services.

      • -t, --account

        9 digit id of the Kony Cloud account (visible in top right corner in Console) for e.g. 100054321. Not relevant for an on-premise installation.

      • * -a, --app

        Path of the locked app

      • -clurl, --cloud-url

        URL of cloud instance

        Default: <empty string>

      • -cu, --console

        URL of Kony Fabric Console (without context path), relevant for on-premise installation only. For e.g. http://10.10.24.78:8081

      • * -ea, --extended-app

        Name of the app with extensions folder e.g., AppName_extended

      • -au, --identity

        URL of Kony Fabric Identity Services (without context path), relevant for on-premise installation only. For e.g. http://10.10.24.79:8080

      • * -la, --locked-app

        Path of the locked app e.g., AppName_locked

      • -a, --merged app name

        Name of the new app with locked app and extended app

      • --mfa

        If specified, multi-factor authentication is enabled. The secret key for multi-factor authentication required for generating one time password (OTP) needs to be specified in the properties file.

        Default: false

      • -p, --password

        Password for the Kony user. This could be plain text or, encrypted using 'encrypt' command. This is mandatory.

      • -u, --user

        Kony user required for authentication, for e.g. abc@kony.com. This is mandatory.