Service Generator Tool¶

Command-Line Tool¶

The service generator command-line tool (csdl-to-war) is delivered as a Mac/Linux shell script (csdl-to-war.sh)and a Windows batch file (csdl-to-war.bat) in the resources/server-odata-sdk/bin subfolder within the Visual Studio Code extension for mobile back-end tools.

Mac/Linux: Using Terminal window, locate with:

find ~/.vscode -name csdl-to-war.sh -print

SAP Business Application Studio: Using Terminal window, locate with:
```
find /extbin -name csdl-to-war.sh -print
```

Windows: using Command Prompt, locate with:

dir "%USERPROFILE%\.vscode\csdl-to-war.bat" /s /a

The command-line tool accepts an OData CSDL XML file as input (for OData version 2.0 or 4.0) and generates a Java/Maven web application project that can build a deployable WAR file for the implementation of an OData service.

Command-Line Tool Usage¶

The minimum required command-line tool parameters are an OData Common Schema Definition Language (CSDL) XML input file name and a target project folder name. The target project folder will be created if it does not already exist.

Mac/Linux Terminal example:

csdl-to-war.sh ~/test/example.csdl.xml ~/projects/myapp

Windows Command Prompt example:

csdl-to-war.bat c:\test\example.csdl.xml c:\projects\myapp

The above example command generates a Java/Maven project for an OData service. The files generated in the project folder and subfolders include Java source files, associated XML files, and other files required for WAR file generation and deployment.

The command also runs the mvn package command, which compiles the Java sources and builds an initial deployable WAR file.

To determine the generated WAR file name in the project's deploy folder, check the command output for a line like this:

Building war: c:\projects\myapp\deploy\odata-service-1.0.0.war

You can specify multiple + separated OData CSDL XML files as the metadata file parameter to generate multiple OData services servers. Once you specify multiple OData CSDL XML files, you can also specify multiple Java package names and multiple context paths.

Note

The service generator is typically invoked by a Visual Studio Code Task. Invoking it from other kinds of build script may be useful, for example as part of a CI build pipeline.

Command-Line Tool Options¶

Options can be specified on the command-line after the CSDL file name and the output folder name.

Minimally, apart from the metadata file and project folder arguments, one of -bind, -h2db, -imdb or -nodb should be specified to indicate where OData entity sets are stored. If none of those options is specified, then -bind DefaultDB is assumed.

Note

Options are usually placed within one of the project's Generated Options Files. Any line in an options file starting with a "#" sign is treated as a comment.

Option: `-application <name>`¶

Specifies the application name. The default is derived from the Java package name.

Option: `-auth <service-instance-name>`¶

For Cloud Foundry deployment, specifies the name of an authentication/authorization service instance (e.g. an XSUAA instance in SAP Business Technology Platform Cloud Foundry) to be bound to the generated OData service in manifest.yml.

If this option is specified, the service instance must already exist.

Option: `-bind [<db-type>:]<db-name>`¶

Specifies a binding of JDBC DataSource reference jdbc/DefaultDB (in the generated MainServletBase.java) to a named database service instance.

Example:

-bind hana:testdb

The type of database (if indicated) must be one of: ase (SAP ASE), db2 (IBM Db2), derby (Apache Derby), h2 (H2 database), hana (SAP HANA), mssql (Azure SQL or Microsoft SQL Server), oracle (Oracle Database), pgsql (PostgreSQL) or sqlany (SAP SQL Anywhere). Otherwise it defaults to hana.

The named database service instance should already exist in the target runtime environment.
Apache Derby and H2 database are supported for local testing only. Note that the -h2db option can be used instead to obtain an Embedded H2 Database for testing. Using the -bind option requires a non-embedded server database.
For SAP Business Technology Platform Cloud Foundry environment (using the -sap:cf option), the supported database types are hana, mssql (Azure SQL) and pgsql (PostgreSQL).
- HDI container based HANA databases are not supported, as they don't allow the server runtime to dynamically change the database schema. In the Cloud Foundry environment a binding with schema plan is therefore required.
  
  The -bind option value should be formatted as hana:*hana-service-instance-name*.
  
  Example:
  
  In your space, create a service instance of type "SAP HANA Schemas & HDI Containers", plan schema.
```
cf create-service hana schema mbt-demo-hana
```
  The -bind parameter corresponding to this example schema should be hana:mbt-demo-hana.
- For Azure SQL (if available from hyperscaler), it may be necessary to define the connectivity/credentials information using a Cloud Foundry User-Provided Service definition in SAP Business Technology Platform Cockpit. In such cases, the -bind option value should be formatted as mssql:user-provided:*user-provided-service-name* and the Credentials in the User-Provided Service Instance definition should be defined using property naming conventions of Apache Commons DBCP.
  
  Example:
```
{
    "driverClassName": "com.microsoft.sqlserver.jdbc.SQLServerDriver",
    "url": "jdbc:sqlserver://<db-host>:<db-port>;databaseName=<db-name>",
    "username": "<db-username>",
    "password": "<db-password>"
}
```
  The db-host should look like "xxx.database.windows.net". To create an Azure SQL Database, please refer to: Quickstart: Create a single database in Azure SQL Database.
- For PostgreSQL (if available from hyperscaler), it may be necessary to define the connectivity/credentials information using a Cloud Foundry User-Provided Service definition in SAP Business Technology Platform Cockpit.
  
  In such cases, the -bind option value should be formatted as pgsql:user-provided:*user-provided-service-name* and the Credentials in the User-Provided Service Instance definition should be defined using property naming conventions of Apache Commons DBCP.
  
  Example:
```
{
    "driverClassName": "org.postgresql.Driver",
    "url": "jdbc:postgresql://<db-host>:<db-port>/<db-name>",
    "username": "<db-username>",
    "password": "<db-password>"
}
```
  The db-host should look like "xxx.rds.amazonaws.com". To create an AWS PostgreSQL DB, please refer to: Create and Connect to a PostgreSQL Database with Amazon RDS.
For local testing or on-premise production deployment, the supported database types are: ase, db2, hana, mssql, pgsql, oracle, sqlany. The relevant web application server documentation for configuration and binding of JDBC resources should be reviewed (see Tomcat). This usually requires installation of an appropriate JDBC driver into the application server's lib folder.
- Additional privileges may need to be granted to the database user for mssql, db2, oracle.
  - For mssql
```
USE MASTER
GO
GRANT VIEW SERVER STATE TO <db-username>
```
  - For db2
```
GRANT EXECUTE ON FUNCTION SYSPROC.MON_GET_TRANSACTION_LOG TO <db-username>
GRANT EXECUTE ON FUNCTION SYSPROC.MON_GET_UNIT_OF_WORK TO <db-username>
```
  - For oracle
```
grant select on gv_$transaction to <db-username>;
grant select on gv_$locked_object to <db-username>;
grant select on gv_$session to <db-username>;
```

Option: `-catalina:home <folder>`¶

Specify the home folder where the local Tomcat application server software has been previously installed.

When using a Tomcat server that has CATALINA_BASE differing from CATALINA_HOME, specify the CATALINA_HOME value.

Note

When using a Tomcat server that has CATALINA_BASE matching CATALINA_HOME, this option does not need to be specified.

Option: `-cf:debug`¶

Enable debugging of a Cloud-Foundry-deployed service via ssh tunneling.

Once the service is deployed and running, use the Run > Start Debugging menu option in Visual Studio Code or SAP Business Application Studio to attach the Java debugger to the running service.

Note

The performance of Cloud Foundry debugging from a desktop computer system can be poor, due to network latency. Consider using SAP Business Application Studio which has better performance for debugging Cloud Foundry-deployed services. Or alternatively, use Logging for debugging purposes.

Option: `-cf:logs`¶

Capture Cloud Foundry runtime logs from the running OData service to the logs project subfolder.

Option: `-cf:push`¶

Push (deploy) the generated WAR file to Cloud Foundry, and start the service.

Option: `-cf:ssh`¶

If the btp-cf-setup setup logs <appname> command is used with an options file including this option, the generated logs/cf-logs scripts will assume that ssh is enabled for the deployed Cloud Foundry app. See Logging.

Option: `-clean <subfolder>`¶

Delete the previous contents of the specified target project subfolder before generation.

Warning

If the -clean option is used with the subfolder name src, any prior customizations will be lost.

Option: `-console:log`¶

Enables logging to the application server's console, bypassing the usual SLF4J configuration of the target application server.

Particularly for testing, this will simplify logging configuration and enable more readable log messages.

If the -console:log option is not used, then you need to consult the documentation for your target application server in regard to the configuration of SLF4J logging. For SAP Business Technology Platform deployments, see Monitoring Generated Services.

Option: `-csrf:token`¶

Enables CSRF tokens for the generated OData Service, to prevent Cross-site request forgery.

The token generation requirements (for the client) are the same as with ABAP REST X-CSRF-Token.

Option: `-debug:host`¶

Specify a non-default JPDA host name for -local:debug.

Option: `-debug:port`¶

Specify a non-default JPDA port number for -local:debug.

Option: `-dest <service-instance-name>`¶

For Cloud Foundry deployment, specifies the name of a destination service instance to be bound to the generated OData service in manifest.yml.

If this option is specified, the service instance must already exist.

Option: `-dev:mode`¶

Enables dev mode, where the generated server allows client-provided keys. This can be useful for simulation of arbitrary back-end systems, possibly with composite keys. By default (without this option), a generated server will attempt to use server-side key generation, which might fail for entity types with composite keys or unexpected key property data types.

Option: `-h2db`¶

Specifies that an Embedded H2 database should be used for entity set storage. An embedded database is only suitable for testing, and only in a single-node application server deployment.

This option can be used for end-to-end validation of the generated OData service with a real SQL database, while deferring the final target database configuration.

The generated Maven project will fetch the H2 database JAR file from the Maven Central Repository. You can modify the selected <version> of the h2 Maven dependency in pom.xml.

Note

The contents of the embedded H2 database will survive restart of a local web application server.

Caution

The contents of the embedded H2 database will not survive redeployment in a Cloud Foundry environment.

Option: `-hc5`¶

For a generated service that must interact with a REST back-end system, the generated Java code should use Apache HTTP Client version 5.X. (Default for newly generated projects).

Option: `-http`¶

Configures the generated service to accept HTTP (unencrypted) requests even if the -login option is specified.

This may simplify local testing by enabling authentication/authorization testing without having to configure transport-level security in a local server.

Note

It is not recommended to use this option when generating a service for production deployment.

Option: `-https`¶

Configures the generated service to require HTTPS (encrypted) requests even if the -login is not specified.

This may simplify local testing by enabling confidentiality testing without having to configure authentication or authorization in a local server.

Note

It is not recommended to use this option when generating a service for production deployment.

Option: `-imdb`¶

Specifies that an embedded in-memory (non-SQL) database should be used for entity set storage. An embedded in-memory database is only suitable for testing, and only in a single-node application server deployment.

This option can be used for end-to-end validation of the generated OData service with a non-SQL database, while deferring the final target database selection/configuration. However the -h2db option is generally preferred for testing.

Note

The -imdb option cannot be used with a cache database service.

Caution

The contents of the embedded in-memory database will not survive restart of the web application server.

Option: `-jakarta`¶

Specifies that the service generation is being invoked for a Jakarta EE web container. By default, a Jakarta EE web container will be assumed.

Option: `-javax`¶

Specifies that the service generation is being invoked for a Java EE web container. By default, a Jakarta EE web container will be assumed.

Note

Java EE is no longer being maintained. Jakarta EE is recommended for new projects.

Option: `-local:debug`¶

Debug the local application server after WAR file deployment.

Once the service is deployed and running, use the Run > Start Debugging menu option in Visual Studio Code or SAP Business Application Studio to attach the Java debugger to the running service.

Option: `-local:deploy <file>`¶

Specify a WAR file name (e.g. test.war) for local deployment.

For Apache Tomcat, you can use the name ROOT.war to deploy the service with an empty context path.

Option: `-local:run`¶

Run the local application server after WAR file deployment.

Option: `-local:server <folder>`¶

Specify the base folder where the local application server software has been previously installed. See also Tomcat.

When using a Tomcat server that has CATALINA_BASE differing from CATALINA_HOME, specify the CATALINA_BASE value.

Option: `-login <method>`¶

Specifies the authentication method to be used (in the generated web.xml) for configuration of authentication for users and administrators of the OData service. The valid authentication methods are determined by the target application server. Please refer to the relevant application server documentation.

Example for the SAP Business Technology Platform Cloud Foundry Environment:

-login xsuaa

Example for a local Apache Tomcat server:

-login basic

A special case is the HTTP login method, specified either as -login http@destination, or as -login https://some.host/some.path. The named destination or HTTP URL specifies another server (and resource path) to which incoming HTTP Authorization headers will be forwarded for verification.

See Securing the Generated Service for more information.

Caution

If the -login option is not specified, the service will be generated without authentication/authorization checks.

Option: `-log:debug`¶

Enables DEBUG-level log messages when used together with the -console:log option.

Some additional specialized debug-level options (not enabled by default with -log:debug) are:

-debug:connections - Extra debug logs for database connection usage.
-debug:destinations - Extra debug logs for destination service calls (this could reveal access tokens and/or credentials in the log).

Option: `-log:debug:<subsystem>`¶

Enables DEBUG-level log messages for a server subsystem when used together with the -console:log option.

Option: `-log:file <file>`¶

Specifies the absolute file name or relative file name (relative to the project's logs subfolder) when the -console:log option is used.

Option: `-log:size <size>`¶

Specifies the maximum size of the log file when the -console:log option is used.

When the specified log size is reached, output to the log file will cease (but output to the console window will continue, if the server process is attached to a console window).

Option: `-log:trace`¶

Enables TRACE-level log messages when used together with the -console:log option.

Some additional specialized trace-level options (not enabled by default with -log:trace) are:

-trace:failures - Trace incoming HTTP requests that fail (with HTTP 4XX or 5XX status), even if tracing wasn't otherwise enabled.
-trace:rollbacks - Trace outgoing JDBC requests that result in transaction rollback, even if tracing wasn't otherwise enabled.
-trace:connections - Detailed trace logs of database connection usage (this will log a stack trace for each connection call).
-trace:destinations - Detailed trace logs of destination service calls (this could reveal access tokens and/or credentials in the log).

Option: `-log:trace:<subsystem>`¶

Enables TRACE-level log messages for a server subsystem when used together with the -console:log option.

Option: `-nodb`¶

Specifies that no database should be used for entity set storage.

In this case, all OData operations must be implemented using customization of handler classes.

Option: `-overwrite`¶

Overwrite any previously-generated files, discarding their previous contents.

By default, if the csdl-to-war tool is used to regenerate an existing project, it will skip regeneration of any files that may be customized by the developer, so as not to lose any customizations.

Warning

If the -overwrite option is used, any customized files will be overwritten and any prior customizations will be lost.

Option: `-package <name>`¶

Specifies the base Java package name for the generated Java source files. If not specified, it is derived from the OData CSDL Schema Namespace (converted to lowercase).

Specify multiple Java package names separated with + when multiple OData CSDL XML files are provided.

Example:

-package com.example.myapp

-package com.example.myapp1+com.example.myapp2

Option: `-path <path>`¶

Specifies the URL context path for accessing the OData service if different from /.

The context path must be specified after the host name (and optional port number) in the client-provided URL.

Specify multiple context paths separated with + when multiple OData CSDL XML files are provided.

Example:

-path /service1

-path /sevice1+/service2

Option: `-sap:bas`¶

Specifies that the service generation is being invoked from SAP Business Application Studio. This facilitates optimal interaction with the Terminal.

Option: `-sap:cf`¶

Specifies that the generated WAR file is intended for deployment in SAP Business Technology Platform - Cloud Foundry Environment.

Option: `-tenant:<header>`¶

Enables multi-tenancy for the generated service.

The specified HTTP header name (if present) will be used to identify the tenant for incoming requests, but usually the tenant will be identified by the ext_attr/zdn field of the client-provided Bearer token JWT payload (within the Authorization header). If both are specified in a request, they must match.

Option: `-test:mode`¶

Enables test mode, which results in automatic generation of test data in the resources/test-data folder and automatic population of the database tables with this test data.

Note

Test data is reloaded into the SQL database whenever the server is restarted.

Option: `-version <number>`¶

Specifies the application version number. The default is 0.1.0.

It is recommended to use Semantic Versioning, e.g. three numbers in the format MAJOR.MINOR.PATCH.

Option: `-vs:code`¶

Specifies that the service generation is being invoked from Visual Studio Code. This facilitates optimal interaction with the Terminal.

Option: `-workspace <folder>`¶

Specifies an IDE workspace folder, if it is different from the project folder. For example, the workspace folder for Visual Studio Code or SAP Business Application Studio.

Logging Subsystem Names¶

When logging is enabled using the -console:log option, then -log:debug:<subsystem> or -log:trace:<subsystem> can be selectively enabled for each subsystem. Available subsystem names are:

odata:cache - to log cache refresh activity.
odata:online - to log outgoing OData requests.
odata:server - to log incoming OData requests.
odata:sql - to log SQL database interactions.

Additionally when using cache databases, logging of interactions with particular back-end subsystems can be selectively enabled using the following subsystem names:

odata:http:<destination-name> - to log HTTP communication with a REST back-end for a particular named destination.
odata:jco:<destination-name> - to log JCo communication with an SAP back-end for a particular named destination.
odata:jdbc:<data-source-name> - to log JDBC communication with a SQL back-end for a particular named data source.

Using subsystem name odata:http, odata:jco or odata:jdbc without a suffix will enable the logging for all back-end systems of the respective type.

Log settings configured as above are propagated to the running OData service via the file src/main/resources/system.properties, with the properties XS_LOG_*.

For a local (on-premise) server such as Apache Tomcat which explodes the deployed WAR file into a folder within the webapps folder, the system.properties file can be manually edited to make logging configuration changes (followed by server restart) without re-running the csdl-to-war tool. This might be helpful for quick enablement of logging in a production or test system where the OData service is already deployed.

Instead of editing the system.properties file in the exploded WAR file folder, system-level environment variables XS_LOG_* can also be set to true (followed by server restart).

Last update: July 23, 2026

Service Generator Tool¶

Command-Line Tool¶

Command-Line Tool Usage¶

Command-Line Tool Options¶

Option: -application <name>¶

Option: -auth <service-instance-name>¶

Option: -bind [<db-type>:]<db-name>¶

Option: -catalina:home <folder>¶

Option: -cf:debug¶

Option: -cf:logs¶

Option: -cf:push¶

Option: -cf:ssh¶

Option: -clean <subfolder>¶

Option: -console:log¶

Option: -csrf:token¶

Option: -debug:host¶

Option: -debug:port¶

Option: -dest <service-instance-name>¶

Option: -dev:mode¶

Option: -h2db¶

Option: -hc5¶

Option: -http¶

Option: -https¶

Option: -imdb¶

Option: -jakarta¶

Option: -javax¶

Option: -local:debug¶

Option: -local:deploy <file>¶

Option: -local:run¶

Option: -local:server <folder>¶

Option: -login <method>¶

Option: -log:debug¶

Option: -log:debug:<subsystem>¶

Option: -log:file <file>¶

Option: -log:size <size>¶

Option: -log:trace¶

Option: -log:trace:<subsystem>¶

Option: -nodb¶

Option: -overwrite¶

Option: -package <name>¶

Option: -path <path>¶

Option: -sap:bas¶

Option: -sap:cf¶

Option: -tenant:<header>¶

Option: -test:mode¶

Option: -version <number>¶

Option: -vs:code¶

Option: -workspace <folder>¶

Logging Subsystem Names¶

Option: `-application <name>`¶

Option: `-auth <service-instance-name>`¶

Option: `-bind [<db-type>:]<db-name>`¶

Option: `-catalina:home <folder>`¶

Option: `-cf:debug`¶

Option: `-cf:logs`¶

Option: `-cf:push`¶

Option: `-cf:ssh`¶

Option: `-clean <subfolder>`¶

Option: `-console:log`¶

Option: `-csrf:token`¶

Option: `-debug:host`¶

Option: `-debug:port`¶

Option: `-dest <service-instance-name>`¶

Option: `-dev:mode`¶

Option: `-h2db`¶

Option: `-hc5`¶

Option: `-http`¶

Option: `-https`¶

Option: `-imdb`¶

Option: `-jakarta`¶

Option: `-javax`¶

Option: `-local:debug`¶

Option: `-local:deploy <file>`¶

Option: `-local:run`¶

Option: `-local:server <folder>`¶

Option: `-login <method>`¶

Option: `-log:debug`¶

Option: `-log:debug:<subsystem>`¶

Option: `-log:file <file>`¶

Option: `-log:size <size>`¶

Option: `-log:trace`¶

Option: `-log:trace:<subsystem>`¶

Option: `-nodb`¶

Option: `-overwrite`¶

Option: `-package <name>`¶

Option: `-path <path>`¶

Option: `-sap:bas`¶

Option: `-sap:cf`¶

Option: `-tenant:<header>`¶

Option: `-test:mode`¶

Option: `-version <number>`¶

Option: `-vs:code`¶

Option: `-workspace <folder>`¶