Migrating the SHINE Purchase Order Worklist Applic...

René · ‎2018 Jul 12

Hi folks,

I am a User Assistance Developer at SAP. One of my topics is the migration from XS classic to XS advanced. To be precise, it is SAP HANA extended application services, classic model and SAP HANA extended application services, advanced model. I am not going into details of the differences between the two. Just one thing is important: XS advanced is a microservice-based approach of application development. The same is valid for applications designed to run on Cloud Foundry, so these two worlds are compatible, at least from the on-premise world to the cloud. The other way around depends and might become tricky at some point.

So, why am I writing this blog and where is it different to the one I wrote before?

That is, because my team and I started to think about use cases for an XS classic to XS advanced migration. Quite naturally, we thought about how to migrate an XS classic application from the Neo environment in SAP Cloud Platform to an XS advanced application running in the Cloud Foundry environment. So, we took the challenge to give it a try and share our knowledge.

The difference hence is the different environments or worlds, as I called them before. Before, we used to look at on-premise systems and this time the focus is on the cloud. This has some different challenges and these are worth mentioning.

What I am about to show you, is the overall process and the pitfalls we found going through that process. We used the XS classic version of SHINE, a Multi-target Application (MTA) that is available in the trial environment. If you are using the Neo environment productively, you might have SHINE available on your system anyway. If you want to migrate one of your applications, there might be different challenges depending on your application and its architecture.

My call to action to you is: Familiarize yourself with the Cloud Foundry environment and plan enough time for that step, to find out which functionality in Neo matches to which capability in Cloud Foundry.

Before we start

We need the Neo and the Cloud Foundry environment of SAP Cloud Platform for this scenario. We had a production-near setup in the Cloud Foundry environment because the deployment of a migrated SHINE application does not work with a trial account.

For more information on how to get a productive account, see Getting Started with a Customer Account

As we could not find a way to provide the stored procedure SYS.GET_OBJECTS_IN_DDL_STATEMENT in SAP HANA in the cloud, we used an on-premise system as parser system. You could also use a recent SAP HANA Express system.

Hint: We used the trial space on the Neo environment. Potentially other setups allow this. Please give it a try and maybe share your experience in the comments.

Create a SHINE application on Neo

The first step was to create a SHINE application in the Neo environment. This was pretty easy and straight forward.

Hint: You need to remember user and password in this process, so be prepared for that.

Login to the Cloud Platform cockpit: https://account.hanatrial.ondemand.com

Go to your trial space in the Neo environment.

Go to SAP HANA / SAP ASE -> Databases & Schemas and create a new database.
- Enable "Configure a User for SHINE".
- You must remember all the information you enter in this dialogue. This is needed in later steps.

Select "Overview" and go to your newly created database.

Prepare your SHINE application user on Neo

If you are not familiar with such operations, the process might seem complicated. However, it really isn't. We did notice that it is cumbersome to click every single object to grant a privilege. There is no multiselection possible. Please be aware of that!

Enter the SAP HANA Cockpit and login with the System user you created earlier.

Go to "Manage Roles and Users".

Expand "Users" and select the user for SHINE you created earlier.

Grant him the following roles and privileges:
- Roles
  - sap.hana.democontent.epm.roles::Admin
  - sap.hana.democontent.epm.roles::User
- SELECT privilege for these objects
  - ACTIVE_CONTENT_TEXT (_SYS_REPO)
  - ACTIVE_CONTENT_TEXT_CONTENT (_SYS_REPO)
  - ACTIVE_OBJECT_TEXT (_SYS_REPO)
  - ACTIVE_OBJECT_TEXT_CONTENT (_SYS_REPO)
  - ACTIVE_TAGS (_SYS_REPO)
  - CATALOG_OBJECTS_CREATED_BY_REPOSITORY_ACTIVATIONS (_SYS_REPO)
  - CDS_ANNOTATION_VALUE (_SYS_RT)
  - CDS_ARTIFACT (_SYS_RT)
  - GRANTED_PRIVILEGES (SYS)
  - GRANTED_ROLES (SYS)
  - M_DATABASE (SYS)
  - M_SCHEMA_MAPPING (_SYS_BI)
  - OBJECTS (SYS)
  - OBJECT_DEPENDENCIES (SYS)
  - PROCEDURES (SYS)
  - SYNONYMS (SYS)
  - TABLES (SYS)
  - TABLE_COLUMNS (SYS)
- EXECUTE privilege for these objects
  - GET_OBJECT_DEFINITION (SYS)
  - REPOSITORY_REST (SYS)
- System privileges
  - CATALOG READ
- Package privileges either on ROOT Package or on the specific package you want to migrate
  - REPO.READ

Save your configuration.

Create a tunnel

At first, I struggled with the question which SDK to download and then my Java configuration did not work. So when I tried this for the first time, the process took me quite a while. But if you do not have Java 9 on your path you are almost good to go.

I followed the instructions from the documentation. This is pretty straight forward, but be aware of the Java version you are using. Java 9 does not work. Set your JAVA_HOME accordingly.

When you have installed all the tools, you call this command with your data instead of all these placeholders:

neo open-db-tunnel -a <subaccount_name> -h <host> -u <user> -i <schema_ID>

It might look somehow like this:

neo open-db-tunnel -a <subaccount_name> -h eu1.hana.ondemand.com -u <user> -i HCO_DEMOCONTENT

Download the migration assistant

The migration assistant is the central tooling for doing the migration. We used version 1.1.24 of the migration assistant.

Go to https://launchpad.support.sap.com

Select "Downloads" in the drop-down list box at the top.

Enter search term: XSAC Migration 1 ; and start the search.

Download and unpack the archive in a directory close to your root directory.

Create environment configuration

We created an .env file in the folder we unpacked the migration assistant to. I created such a file on Windows, by creating a new file in the File Explorer and naming the file ".env.".

HANA_HOST=

HANA_SQL_PORT=

HANA_USER=

HANA_PASSWD=

HANA_CERTIFICATE=

HANAEXT_HOST=

HANAEXT_SQL_PORT=

HANAEXT_USER=

HANAEXT_PASSWD=

HANAEXT_CERTIFICATE=

For more information, see the documentation on how to configure a connection (Step 2).

Run the migration assistant

I opened the Windows Command Prompt and navigated to the directory where I unpacked the migration assistant.

Note: When running the migration assistant, you have to add options. Have a look at the documentation for options you might need.

These two option are the ones we used.

```
--target-directory
```
- Defines where the migration result should be saved to. The migration assistent creates the directory during runtime.

```
--zip
```
- Makes it easier if you want to use SAP Web IDE Full-Stack for the code corrections.

```
--target-release
```
- Defines the release version of your SAP HANA in your target environment.

This is how I started the migration assistant:

xs-migration --target-dir path/to/my/target-directory --zip --target-release 2.0SP00 HCO_DEMOCONTENT

Make manual corrections: Focus Purchase Order Worklist

The amount of changes is due to concept changes, that did not support a migration path. For some cases there are manual migration steps available, to show you how you can switch to the new concept. However, we decided to stay within our focus application and only makes fixes there.

According to our focus on the Purchase Order Worklist application, a handful of steps in the following procedure are about deleting files or folders. We minimized effort for the other parts of SHINE and in these cases it was easier to delete things, than to make detailed fixes without impact on our focus.

To better visualize paths and folders/files in the following procedure each gets a distinct color. I keep the steps in this procedure as short as possible but I hope you will still be able to follow. If there are difficulties, please leave a comment.

Delete folders:
- db/cfg/roles
- db/cfg/uis

Go to folder db/cfg and delete all synonym-grantor-service files.

Delete folders:
- db/src/roles
- sb/src/ui
- db/src/uis
- db/src/defaults

Go to folder db/src and delete synonym-grantor-service.hdbsynonym.

We do this as a workaround because cross-schema access is not possible. The tables are available locally and we need the synonyms to access them withz the same reference as before. Otherwise we would need to adapt all references to the new location.

Create a folder synonyms in db/src and in this new folder create two files.

synonyms.hdbsynonym

{

 "TCURF": {

       "target": {

           "object": "sap.hana.democontent.epm.data::Conversions.TCURF"

       }

   },

   "TCURN": {

       "target": {

           "object": "sap.hana.democontent.epm.data::Conversions.TCURN"

       }

   },

   "TCURR": {

       "target": {

           "object": "sap.hana.democontent.epm.data::Conversions.TCURR"

       }

   },

   "TCURV": {

       "target": {

           "object": "sap.hana.democontent.epm.data::Conversions.TCURV"

       }

   },

   "TCURX": {

       "target": {

           "object": "sap.hana.democontent.epm.data::Conversions.TCURX"

       }

   },

   "sap.hana.democontent.epm::DUMMY": {

    "target": {

      "object": "DUMMY",

      "schema": "SYS"

    }

  },

  "VIEWS": {

    "target": {

      "object": "VIEWS",

      "schema": "SYS"

    }

  },

  "TABLES": {

    "target": {

      "object": "TABLES",

      "schema": "SYS"

    }

  },

  "M_TABLES": {

    "target": {

      "object": "M_TABLES",

      "schema": "SYS"

    }

  },

  "sap.hana.democontent.epm::SERIES_GENERATE_TIMESTAMP": {

    "target": {

      "object": "SERIES_GENERATE_TIMESTAMP",

      "schema": "SYS"

    }

}

}

.hdinamespace

{

    "name": "",

    "subfolder": "ignore"

}

Go to db/src/models
1. Delete .hdbanalyticprivilege files.
2. Fix calculationviews
  - Affected files:
    - BUYER.hdbcalculationview,
    - PO_ITEM.hdbcalculationview,
    - PROD.hdbcalculationview,
    - PRODUCT.hdbcalculationview,
    - SUPPLIER.hdbcalculationview
  - The screenshots below, help to understand the following text. The colors help you to recognize the section in the code.
  - If the <input> section contains a <mapping> with property target that has a "JOIN$[...]" in it, add the following line in the <viewattributes> section as the last entry in that section:
```
<viewAttribute hidden="true" id="PLACEHOLDER"/>
```
  - Exchange PLACEHOLDER with the value from the property target in the <input> section of the corresponding calculationview.
  - Before
  - After

Open the mta.yaml and replace the existing code with this code:

_schema-version: 2.0

ID: HCO_DEMOCONTENT

description: 

version: 1.12.1

modules:

  - name: HCO_DEMOCONTENT-app

    path: web

    type: html5

    requires:

      - name: uaa

      - name: xsjs

        group: destinations

        properties:

          name: xsjs

          url: ~{url}

      - name: ui5

        group: destinations

        properties:

          name: ui5

          url: ~{url}

  - name: HCO_DEMOCONTENT-db

    type: hdb

    path: db

    requires:

      - name: HCO_DEMOCONTENT-hdi

        properties:

            TARGET_CONTAINER: ~{service-name}

  - name: HCO_DEMOCONTENT-xsjs-service

    path: xsjs

    type: nodejs

    requires:

      - name: HCO_DEMOCONTENT-hdi

      - name: HCO_DEMOCONTENT-db

      - name: uaa

    provides:

      - name: xsjs

        properties:

           url: ${default-url}

 

resources:

  - name: HCO_DEMOCONTENT-hdi

    type: com.sap.xs.hdi-container

    properties:

        service-name: ${service-name}

  - name: ui5

    properties:

      url: "https://sapui5.netweaver.ondemand.com"

  - name: uaa

    type: com.sap.xs.uaa-space

    parameters:

      config-path: xs-security.json

In comparison, some services have been deleted, like the synonym-grantor service or the job scheduler.

Open the xs-security.json and replace the existing code with this code:

{

    "xsappname": "HCO_DEMOCONTENT",

    "tenant-mode": "dedicated",

    "scopes": [

        {

            "name": "$XSAPPNAME.sap.hana.democontent.epm.Basic",

            "description": "Basic usage privilege"

        },

        {

            "name": "$XSAPPNAME.sap.hana.democontent.epm.Admin",

            "description": "Administration privilege"

        }

    ],

    "role-templates": [

        {

            "name": "sap_hana_democontent_epm_roles_Admin",

            "scope-references": [

                "$XSAPPNAME.sap.hana.democontent.epm.Admin"

            ]

        },

        {

            "name": "sap_hana_democontent_epm_roles_User",

            "scope-references": [

                "$XSAPPNAME.sap.hana.democontent.epm.Basic"

            ]

        }

    ]

}

Go to the xsjs folder.

Delete the file images.xshttpdest.

Open the package.json file and check if it looks like this:

{

  "name": "HCO_DEMOCONTENT-xsjs-service",

  "description": "",

  "version": "1.0.0",

  "main": "main.js",

  "scripts": {

    "start": "node main.js",

    "stop": ""

  },

  "files": [],

  "dependencies": {

    "@sap/xsenv": "1.2.8",

    "@sap/xsjs": "3.0.0",

    "@sap/cds": "1.14.1"

  },

  "devDependencies": {

    "@sap/xsjs-test": "2.0.13"

  },

  "engines": {

    "node": "8.x"

  }

}

Go to folder xsjs/lib/sap/hana/democontent/epm/services.

Open the file LazyPost.xsjslib and replace the existing code with this code:

var conn = $.db.getConnection();  

var XSDS = $.require("@sap/cds").xsjs(conn); // “sap-cds” refers to node-cds 

var entity = XSDS.importEntity('sap.hana.democontent.epm.data','Util.Messages');

Open the file session.xsjslib.

Locate this code

var XSProc = $.import("sap.hana.xs.libs.dbutils", "procedures");

var proc = XSProc.allProcedures("SAP_HANA_DEMO", "sap.hana.democontent.epm.procedures");

Replace it with this code:

var connection = $.hdb.getConnection();

var proc = {

    get_session_variable: connection.loadProcedure("sap.hana.democontent.epm.Procedures::get_session_variable"),

    set_session_variable: connection.loadProcedure("sap.hana.democontent.epm.Procedures::set_session_variable"),

    get_application_variable: connection.loadProcedure("sap.hana.democontent.epm.Procedures::get_application_variable"),

    set_application_variable: connection.loadProcedure("sap.hana.democontent.epm.Procedures::set_application_variable")

};

Go to the web folder.
- Open the file xs-app.json and change the value for welcomeFile to sap/hana/democontent/epm/ui/index.html.
- Add a file default-env.json to the web folder and add this code (remember to replace [region] with your region like eu10 or else) to the file:
```
{

   "TENANT_HOST_PATTERN": "^(.*)-hco-democontent-app.cfapps.[region].hana.ondemand.com"

}
```
- Open the file sap/hana/democonten/epm/admin/ui/global.js and replace in line 19 messages.hdbtextbundle with messages.properties.
- Open the file sap/hana/democontent/epm/ui/poworklist/js/global.js and replace in line 11 messages.hdbtextbundle with messages.properties.
- Open the file sap/hana/democontent/epm/ui/salesDashboard/js/app.js and replace in line 9 messages.hdbtextbundle with messages.properties.

Build and deploy on Cloud Foundry

We used these tools:

the Cloud Foundry command line interface (CF CLI),

the Multi-target application archive builder and

the MTA plugin for CF CLI for deployment.

You can find and download all of them here: https://tools.hana.ondemand.com/#cloud

You will find there references to more detailed information and documentation.

Build your MTA using Multi-target application archive builder.
- The command line tool uses your mta.yaml file to create an mtad.yaml file, that describes the deployment of your archive in the Cloud Foundry environment.
- In addition every used module will be build and packed in the archive for deployment.
- The result is an .mtar archive file

Manipulate the archive
- Open the .mtar.
- Copy the xs-security.json in the root of your archive.
- Add this code to the MANIFEST.MF file in the META-INF folder
```
Name: xs-security.json

MTA-Resource: uaa

Content-Type: application/json
```

Login to Cloud Foundry and navigate to the space you want to deploy your application to.
- ```
cf l -a <the api url to your environment>
```

Deploy your .mtar archive with the MTA plugin for the Cloud Foundry command line interface.
- This tool takes care of the orchestrated deployment of the included modules with its dependencies.
- ```
cf deploy <path to your mtar>
```

You can now open your HCO_DEMOCONTENT_app from the cockpit or get the URL from CF CLI with

cf a

I

I hope, you got an idea of how such a migration looks like and about the challenges you might face with your own application. Being familiar with the concepts of XSC, XSA and CF is maybe more important than fiddling about tools and environments.

And now we've come to an end. Start discussing and sharing your experiences. Share your learning journey with us, let us know if you tried it yourself and what your experience was. If you have, in addition, experience with the on-premise migration, tell us about it and about the differences you experienced.

-René