Skip to content

Installing the Tools

SAP Business Application Studio

From the SAP Business Application Studio home page, click on the Create Dev Space button.

  • Enter a Dev Space name, e.g. test.

  • Select the SAP Mobile Services kind of application.

  • Click on the Create Dev Space button.

  • Wait while the Dev Space is STARTING.

  • When the Dev Space is RUNNING, click on the underlined Dev Space name.

  • From the Terminal menu, select the New Terminal option.

  • After the $ prompt in the Terminal window, enter a mkdir command to create a project folder. For example:

    mkdir ~/projects/test
    
  • From the File menu, select the Open... option, and use it to open the project folder that was created in the Terminal window in the previous step.

Note

The Visual Studio Code Extension, Java Development Kit, Apache Maven, Apache Tomcat and Cloud Foundry CLI are preinstalled in SAP Business Application Studio, so the corresponding installation sections in this document can be skipped. The subsequent sections for Visual Studio Code Commands and Visual Studio Code Tasks are also applicable to SAP Business Application Studio.

Visual Studio Code Extension

Visual Studio Code can be used to access the mobile back-end tools on a desktop computer system.

  • Install Visual Studio Code for Windows, Mac or Linux.

  • Install the Visual Studio Code extension for mobile back-end tools (vsc-extension-mbt).

  • You may wish to install the XML Language Support by Red Hat extension which enables enhanced editing of OData 4.0 CSDL XML documents. See also the Conventions for OData Metadata describing the xmlns:xsi and xsi:schemaLocation attributes.

  • You may wish to install the Code Map extension which enhances navigation within XML files.

    Here is a sample custom mapper for your reference; see also CodeMap Wiki page.

    "codemap.xml": [
        {
            "pattern": "Schema(\\s+)Namespace(\\s*)=(\\s*)\"[^\"]*\"",
            "clear": "<|>",
            "prefix": "",
            "icon": "level1"
        },
        {
            "pattern": "(ComplexType|EntityType|EnumType|TypeDefinition|Term|Action|Function|EntityContainer)(\\s+)Name(\\s*)=(\\s*)\"[^\"]*\"",
            "clear": "<|>",
            "prefix": "",
            "icon": "level2"
        }
    ],
    

Install Java Development Kit

  • Download and install the Java Development Kit (JDK). See SAP JVM Downloads (you may need to Install the SAPCAR Utility as well) or Java SE Downloads. Ensure that the JDK version that you download and install is not for a more recent version of Java than is used by your intended target Java application server, but is also at least Java 8 (JDK 1.8).

  • Ensure that the JAVA_HOME environment variable is set and that it refers to the correct JDK installation.

    Mac/Linux shell:

    $JAVA_HOME/bin/java -version
    

    Windows Command Prompt:

    %JAVA_HOME%\bin\java -version
    

Install Apache Maven

  • Download and install Apache Maven.

  • Ensure that the mvn command is available in the PATH by issuing the following command in a Windows Command Prompt or Mac/Linux shell.

    mvn -help
    

Install Apache TomEE

This step is optional, but may be helpful for local testing, or on-premise production deployment, of your generated OData service.

  1. Download and install Apache TomEE webprofile version 7 or later. TomEE is recommended as it is the preferred web application container for use in SAP Business Technology Platform, enabling your local testing to be in an environment similar to the production deployment environment.

    Alternatively, you can use Apache Tomcat version 8 or later. Tomcat is preinstalled in SAP Business Application Studio, so it can be convenient for testing in that environment.

  2. Note that the following instructions refer to CATALINA_BASE and CATALINA_HOME which are described in Tomcat Directories and Files.

    For the preinstalled Tomcat in SAP Business Application Studio, CATALINA_BASE is /home/user/.tomcat/default.

  3. Configure TomEE (or Tomcat) as appropriate to your local environment. To enable generated OData services to access your target database, create the $CATALINA_BASE/conf/jdbc/DefaultDB.properties file with configuration parameters as defined by Apache Commons DBCP. You might need to create the $CATALINA_BASE/conf/jdbc folder if it doesn't already exist.

    The following example configures TomEE (or Tomcat) to access a local SAP HANA Express Edition database.

    driverClassName=com.sap.db.jdbc.Driver
    url=jdbc:sap://hxehost:39013?autocommit=true&currentschema=myschema
    username=SYSTEM
    password=MyHanaPassword
    

    Alternatively for TomEE, but not for Tomcat, configure a Resource element in $CATALINE_BASE/conf/tomee.xml with the id jdbc/DefaultDB. For example:

    <tomee>
        <Resource id="jdbc/DefaultDB" type="javax.sql.DataSource">
            jdbcDriver = com.sap.db.jdbc.Driver
            jdbcUrl = jdbc:sap://hxehost:39013?autocommit=true&amp;currentschema=myschema
            userName = SYSTEM
            password = MyHanaPassword
            maxActive = 100
            maxIdle = 30
            testOnBorrow = true
            validationQuery = select 1 from dummy
        </Resource>
    </tomee>
    
  4. Copy the JDBC driver file(s) for your database (e.g. ngdbc.jar for SAP HANA) to the $CATALINA_HOME/lib folder (or the $CATALINA_BASE/lib folder (/home/user/.tomcat/default/lib) in SAP Business Application Studio).

Note

Steps 3 and 4 above can be deferred if you will initially use the -h2db option for an Embedded H2 Database (for testing only).

Install Eclipse Virgo

This step is optional, but may be helpful for local testing, or on-premise production deployment, of your generated OData service.

  1. Download and install Eclipse Virgo, or download and install SAP Mobile Platform (version 3.1+) which is based on Eclipse Virgo.

  2. Configure Virgo as appropriate to your local environment. To enable generated OData services to access your target database, create the configuration/jdbc/DefaultDB.properties file with configuration parameters as defined by Apache Commons DBCP. You might need to create the configuration/jdbc folder if it doesn't already exist.

    The following example configures Virgo to access a local SAP HANA Express Edition database.

    driverClassName=com.sap.db.jdbc.Driver
    url=jdbc:sap://hxehost:39013?autocommit=true&currentschema=myschema
    username=SYSTEM
    password=MyHanaPassword
    
  3. Copy the JDBC driver file(s) for your database (e.g. ngdbc.jar for SAP HANA) to Virgo's lib folder.

  4. Edit the file configuration/config.ini and add (or edit) the org.osgi.framework.system.packages.extra property to specify the Java package name(s) for your JDBC driver.

Note

Steps 3 and 4 above can be deferred if you will initially use the -h2db option for an Embedded H2 Database (for testing only).

Install Cloud Foundry CLI

If you wish to enable command-line deployment to SAP Business Technology Platform (Cloud Foundry environment), including when using Visual Studio Code Tasks, install the Cloud Foundry Command Line Interface.

Ensure that the cf command is available in the PATH by issuing the following command in a Windows Command Prompt or Mac/Linux shell.

cf help

Note

Before attempting deployment to Cloud Foundry, you should use the cf login command to connect and login to your Cloud Foundry space.

Install Neo Console Client

If you wish to enable command-line deployment to SAP Business Technology Platform (Neo environment), install the Console Client for the Neo Environment.

Ensure that the neo command is available in the PATH by issuing the following command in a Windows Command Prompt or Mac/Linux shell.

neo help

Visual Studio Code Commands

Note

This section is also applicable to SAP Business Application Studio.

The mobile back-end tools extension provides two additional commands in the Command Palette, accessed by View > Command Palette... in Visual Studio Code, or by View > Find Command... in SAP Business Application Studio.

  1. MBT: New OData CSDL document (metadata)

    • Command parameters:

      • OData version
      • Schema namespace
      • Namespace alias
      • Metadata file name
    • You might already have a CSDL document, in which case place a copy of it into your project's root folder instead of creating a new document, and refer to the Conventions for OData Metadata describing the xmlns:xsi and xsi:schemaLocation attributes which enable the XML Language Support by Red Hat extension to locate the XML Schema files for OData CSDL validation.

    • Use the file extension .csdl.xml for OData CSDL XML files. When using SAP Business Application Studio, files with this extension can be viewed or edited with the graphical CSDL Editor, accessed via the context menu.

    • Once you have created the CSDL document you can use the tasks.json creator.

  2. MBT: Create tasks.json file

    • Command parameters:

      • Target platform
      • Local server path
      • Application name
      • Semantic version
      • OData service style
      • Database type
      • Database name
      • Target folder
      • Metadata file name
    • Within SAP Business Application Studio, you can specify the local server path /home/user/.tomcat/default to access the preinstalled Apache Tomcat for local testing.

    • Once you have created tasks.json, you can use Terminal > Run Task to invoke the csdl-to-war tool for generation, deployment and monitoring of the OData service. You can make changes to the service metadata or customize previously generated code, then run the same task again to regenerate and redeploy the service.

Visual Studio Code Tasks

Note

This section is also applicable to SAP Business Application Studio.

You can access the service generator tool through tasks.

To manually define tasks, or alter existing task definitions, from the Terminal menu, choose Configure Tasks... > Create tasks.json from template > Others.

Example for target platform which is local server:

{
      // See https://go.microsoft.com/fwlink/?LinkId=733558
      // for the documentation about the tasks.json format
      "version": "2.0.0",
      "tasks": [
          {
              "label": "csdl-to-war",
              "type": "shell",
              "command": "$HOME/.vscode/extensions/sapse.vsc-extension-mbt-`*X.Y.Z*`/resources/server-odata-sdk/bin/csdl-to-war.sh",
              "args": [
                "${workspaceFolder}/metadata.csdl.xml",
                "${workspaceFolder}",
                "-workspace", "${workspaceFolder}",
                "-application", "myapp",
                "-version", "1.0.0",
                "-h2db",
                // "-login", "BASIC",  // uncomment this line for Basic Authentication,
                "-local:server", "<-- Define local server path HERE -->",
                "-local:deploy", "ROOT.war",
                "-vs:code",
                "-local:run",
                // "-csrf:token", // uncomment out this line to enable csrf token
                "-console:log", // comment out this line for production deployment
                "-log:trace" // comment out this line for production deployment
              ],
              "problemMatcher": [
                  {
                      "severity": "error",
                      "pattern": {
                          "regexp": "com\\.sap\\.xscript\\..*Exception: (...+):(\\d+) (.+)",
                          "file": 1,
                          "line": 2,
                          "message": 3
                      },
                      "fileLocation": ["absolute"]
                  },
                  {
                      "severity": "warning",
                      "pattern": {
                          "regexp": ".+ WARN .+ProxyCompiler.+ (...+):(\\d+) (.+)",
                          "file": 1,
                          "line": 2,
                          "message": 3
                      },
                      "fileLocation": ["absolute"]
                  }
              ],
              "group": {
                    "kind": "build",
                    "isDefault": true
               }
          }
      ]
}

When defining your tasks:

  • The "command" path for the csdl-to-war script is determined by the installation location of the Visual Studio Code extension, for example in a Windows installation this may be C:/Users/<user>/.vscode/extensions/sapse.vsc-extension-mbt-X.Y.Z/resources/server-odata-sdk/bin/csdl-to-war.bat.

  • The first command argument (shown in the above example as "metadata.csdl.xml"), should be varied to match your OData CSDL metadata file name.

  • The above example illustrates the use of the "-h2db" option for an Embedded H2 Database (for testing only), but this should be changed to use the "-bind" option once you are ready to test with a production database server.

  • The "-local:server" and "-local:deploy" options enable automatic deployment to a local server, which will be restarted if needed to enable safe deployment, avoiding issues with locked files. Omit these options if you will be doing non-local or manual deployment.

  • The value for the "-local:server" option is the installation folder of your local Apache TomEE or Eclipse Virgo. When using a Tomcat/TomEE server that has CATALINA_BASE differing from CATALINA_HOME, specify the CATALINA_BASE value, e.g. /home/user/.tomcat/default for the preinstalled Apache Tomcat in SAP Business Application Studio. See also the "-catalina:home" option.

  • The value for the "-local:deploy" option is a file name that determines the context path of the deployed service. For example with a standard TomEE installation, using "test.war" will result in your service being available for testing with URL http://localhost:8080/test. You can vary the file name to obtain a different context path. Using the name "ROOT.war" with TomEE will result in your service being available at URL http://localhost:8080.

  • The optional "-console:log" and "-log:debug" / "-log:trace" options force DEBUG-level or TRACE-level log messages from your service to be captured in a file in your project's logs folder. For production systems, the use of "-console:log" and "-log:debug" / "-log:trace" options might be inappropriate, because it sidesteps the regular SLF4J log level configuration. However using these options for testing purposes can be helpful as they enable an easy-to-read debug/trace log output with a minimum of configuration. If these options are not used then the usual logging configuration will apply.

  • The "-local:run" option starts the local server after deployment. Alternatively, use "-local:debug" to start the server enabled for local debugging, then use the Run > Start Debugging menu option in Visual Studio Code (or Debug > Start Debugging menu option in SAP Business Application Studio) to attach the Java debugger to the running service.

  • Remove the "-local:*" options and add the "-sap:cf" option . Also check the applicability of the "-bind" and "-login" options. Define a separate task for generation of services for cloud deployment so that it is easy to switch back and forth between local and cloud deployment, simply by choosing the appropriate task.

Example for target platform which is Cloud Foundry:

{
      // See https://go.microsoft.com/fwlink/?LinkId=733558
      // for the documentation about the tasks.json format
      "version": "2.0.0",
      "tasks": [
          {
              "label": "csdl-to-war",
              "type": "shell",
              "command": "$HOME/.vscode/extensions/sapse.vsc-extension-mbt-`*X.Y.Z*`/resources/server-odata-sdk/bin/csdl-to-war.sh",
              "args": [
                "${workspaceFolder}/metadata.csdl.xml",
                "${workspaceFolder}/srv",
                "-workspace", "${workspaceFolder}",
                "-application", "myapp",
                "-version", "1.0.0",
                "-bind", "postgresql:mydatabase",
                "-login", "XSUAA",
                "-spring:boot",
                "-path", "odata",
                "-sap:mta",
                "-module", "srv",
                "-cf:push",
                "-sap:cf",
                "-cf:logs",
                // "-csrf:token", // uncomment out this line to enable csrf token
                "-console:log", // comment out this line for production deployment
                "-log:trace" // comment out this line for production deployment
              ],
              "problemMatcher": [
                  {
                      "severity": "error",
                      "pattern": {
                          "regexp": "com\\.sap\\.xscript\\..*Exception: (...+):(\\d+) (.+)",
                          "file": 1,
                          "line": 2,
                          "message": 3
                      },
                      "fileLocation": ["absolute"]
                  },
                  {
                      "severity": "warning",
                      "pattern": {
                          "regexp": ".+ WARN .+ProxyCompiler.+ (...+):(\\d+) (.+)",
                          "file": 1,
                          "line": 2,
                          "message": 3
                      },
                      "fileLocation": ["absolute"]
                  }
              ],
              "group": {
                    "kind": "build",
                    "isDefault": true
               }
          }
      ]
}

For options:

  • For convenience, the "-cf:push"option will push (deploy) your service to Cloud Foundry, and the "-cf:logs"option will capture the Cloud Foundry application log from your running service to in a file in your project's logs folder. See also the notes above about the "-console:log" and "-log:debug" / "-log:trace" options. The "-cf:debug"option enables debugging of Cloud Foundry-deployed services via a cf ssh tunnel.

  • For post-generation cloud deployment, you may wish to define additional tasks using the Cloud Foundry CLI. The generated WAR file odata-service-X.Y.Z.war is located in your project's target folder.

Invoke your task to generate (and optionally deploy) your service by adding your OData CSDL file to your Visual Studio Code workspace folder, selecting your OData CSDL file, and choosing csdl-to-war from the Terminal > Run Task... menu option. One of your tasks can be designated as the default build task, which may enable convenient task execution by a keyboard shortcut.

Integration with Eclipse IDE

You can optionally integrate the service generator tool with the Eclipse IDE.

The following instructions are for Eclipse Oxygen. For other versions of Eclipse, the instructions may need to be altered.

  1. Download the Eclipse installer, start it, select Eclipse IDE for Java EE Developers, and click Install. Once installed, start Eclipse and use the start screen (or File > New) to create a new Dynamic Web Project.

  2. Set up external JARs:

    1. Right-click the web project and click Properties. Select Java Build Path, click Libraries and then Add External JARs.

    2. Browse to the lib folder of your Apache TomEE installation and select servlet-api.jar. Click Open.

    3. Browse to the lib folder of your Apache TomEE installation and select the library matching slf4j-api-*.jar. Click Open.

    4. Click Apply and Close.

  3. Set up external tools:

    1. From the Run menu, choose External Tools > External Tools Configurations....

    2. Click Program, then click New (the icon near the top left of the dialog) to create a new launch configuration.

    3. In the Name edit box, enter the name csdl-to-war.

    4. In the Location edit box, enter the full path to the csdl-to-war.bat (Windows) file or csdl-to-war.sh (Mac/Linux) script as appropriate to your environment.

    5. In the Arguments box, enter "${selected_resource_loc}" "${project_loc}" -eclipse as well as any other command-line options that you require.

    6. Click the Refresh tab, enable the checkbox Refresh resources upon completion, and then select the The project containing the selected resource radio button.

    7. Click the Build tab and deselect the Build before launch check box.

    8. Click the Common tab and, in the Display in favorites menu section, enable the External Tools check box.

    9. Click Apply (the button near the bottom right of the dialog) to save the launch configuration, then click Close to close the dialog.

  4. Generate your service:

    1. Add an OData CSDL file to your project, e.g. metadata.csdl.xml.

    2. To generate Java servlets and other artifacts from your CSDL file, click the CSDL file to select it, then from the Run menu, choose External Tools > csdl-to-war.

  5. Create a server:

    1. In the Servers tab (in the bottom-right pane of the Eclipse window), right-click, then from the pop-up menu choose New > Server.

    2. Choose Apache > Tomcat v8.5 Server (which matches with TomEE version 7, assuming that is the TomEE version that you installed) then click Finish.

    3. If Eclipse prompts you for the location of your Tomcat installation, provide the location of your TomEE installation.

    4. Once the server is created, double-click on the server name to open the server Overview page.

    5. Click Open launch configuration, select the Arguments tab, and then in the VM arguments edit box, add -Dsap.xs.logger=console, and then click OK. This enables simple logging to the Eclipse Console.

  6. Configure database resources:

    1. Right-click on your server and click Start.

    2. Check the Eclipse server Console output for a line starting with "INFO: Command line argument: -Dcatalina.base=". This indicates the folder containing the embedded TomEE server.

    3. Copy the conf/tomee.xml that was configured earlier into the embedded server's conf folder.

    4. Right-click on your server and then click Restart.

  7. Configure web modules:

    1. Right-click on your server and click Add and Remove.

    2. From the Available section, select your project and click Add to move your project to the Configured section.

    3. Click Finish.

  8. Test your service:

    The service root URL should be http://localhost:8080/myapp, where myapp is your web project name.

Other Eclipse Deployment Options

  1. Create a new server in Eclipse with server type Cloud Foundry > Cloud Foundry to deploy your service to the SAP Business Technology Platform - Cloud Foundry environment. See also the -sap:cf option.

  2. Create a new server in Eclipse with server type SAP > SAP Business Technology Platform to deploy your service to the SAP Business Technology Platform - Neo environment. For detailed instructions, consult the SAP Business Technology Platform documentation section Development > Applications in the Neo Environment > Java: Development > Deploying and Updating Applications > Deploy on the Cloud from Eclipse IDE. Choose the Java EE 7 Web Profile TomEE 7 runtime. See also the -sap:neo option.


Last update: January 25, 2022