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 amkdir
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
andxsi: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¶
-
Ensure that the
mvn
command is available in thePATH
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.
-
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.
-
Note that the following instructions refer to
CATALINA_BASE
andCATALINA_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
. -
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¤tschema=myschema username=SYSTEM password=MyHanaPassword
Alternatively for TomEE, but not for Tomcat, configure a Resource element in
$CATALINE_BASE/conf/tomee.xml
with the idjdbc/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&currentschema=myschema userName = SYSTEM password = MyHanaPassword maxActive = 100 maxIdle = 30 testOnBorrow = true validationQuery = select 1 from dummy </Resource> </tomee>
-
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.
-
Download and install Eclipse Virgo, or download and install SAP Mobile Platform (version 3.1+) which is based on Eclipse Virgo.
-
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 theconfiguration/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¤tschema=myschema username=SYSTEM password=MyHanaPassword
-
Copy the JDBC driver file(s) for your database (e.g.
ngdbc.jar
for SAP HANA) to Virgo'slib
folder. -
Edit the file
configuration/config.ini
and add (or edit) theorg.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.
-
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
andxsi: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.
-
-
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 thecsdl-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 thecsdl-to-war
script is determined by the installation location of the Visual Studio Code extension, for example in a Windows installation this may beC:/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 hasCATALINA_BASE
differing fromCATALINA_HOME
, specify theCATALINA_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 URLhttp://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 URLhttp://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'slogs
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'slogs
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 acf 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'starget
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.
-
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.
-
Set up external JARs:
-
Right-click the web project and click Properties. Select Java Build Path, click Libraries and then Add External JARs.
-
Browse to the
lib
folder of your Apache TomEE installation and selectservlet-api.jar
. Click Open. -
Browse to the
lib
folder of your Apache TomEE installation and select the library matchingslf4j-api-*.jar
. Click Open. -
Click Apply and Close.
-
-
Set up external tools:
-
From the Run menu, choose External Tools > External Tools Configurations....
-
Click Program, then click New (the icon near the top left of the dialog) to create a new launch configuration.
-
In the Name edit box, enter the name
csdl-to-war
. -
In the Location edit box, enter the full path to the
csdl-to-war.bat
(Windows) file orcsdl-to-war.sh
(Mac/Linux) script as appropriate to your environment. -
In the Arguments box, enter
"${selected_resource_loc}" "${project_loc}" -eclipse
as well as any other command-line options that you require. -
Click the Refresh tab, enable the checkbox Refresh resources upon completion, and then select the The project containing the selected resource radio button.
-
Click the Build tab and deselect the Build before launch check box.
-
Click the Common tab and, in the Display in favorites menu section, enable the External Tools check box.
-
Click Apply (the button near the bottom right of the dialog) to save the launch configuration, then click Close to close the dialog.
-
-
Generate your service:
-
Add an OData CSDL file to your project, e.g.
metadata.csdl.xml
. -
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
.
-
-
Create a server:
-
In the Servers tab (in the bottom-right pane of the Eclipse window), right-click, then from the pop-up menu choose New > Server.
-
Choose Apache > Tomcat v8.5 Server (which matches with TomEE version 7, assuming that is the TomEE version that you installed) then click Finish.
-
If Eclipse prompts you for the location of your Tomcat installation, provide the location of your TomEE installation.
-
Once the server is created, double-click on the server name to open the server Overview page.
-
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.
-
-
Configure database resources:
-
Right-click on your server and click Start.
-
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. -
Copy the
conf/tomee.xml
that was configured earlier into the embedded server'sconf
folder. -
Right-click on your server and then click Restart.
-
-
Configure web modules:
-
Right-click on your server and click Add and Remove.
-
From the Available section, select your project and click Add to move your project to the Configured section.
-
Click Finish.
-
-
Test your service:
The service root URL should be
http://localhost:8080/myapp
, wheremyapp
is your web project name.
Other Eclipse Deployment Options¶
-
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. -
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.