SAP River Developer Guide

PUBLICSAP RiverDocument Version: 1.1 - 13-03-2014

SAP River Developer Guide

Table of Contents1 What is SAP River?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Enabling River. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.1 Deploying the SAP River Delivery Unit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Configuring the Server for SAP River. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.3 Setting Up Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3 Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.1 Opening the SAP HANA Studio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.2 Installing the SAP River Plug-In. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.3 Setting Up the Development Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3.3.1 Adding a System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.3.2 Creating a Repository Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.4 Creating HelloWorld. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183.4.1 Creating the HelloWorld Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183.4.2 Coding and Activating HelloWorld. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233.4.3 Testing HelloWorld. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

4 Coding in SAP River. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274.1 Creating an SAP River Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274.2 Creating an SAP River Source File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274.3 Editing SAP River Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284.4 Searching for Tables and Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304.5 Activating SAP River Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

5 Generating Test Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

6 Viewing Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366.1 Modifying Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376.2 Running Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

7 Debugging SAP River Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407.1 Debugging with Data Preview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417.2 Debugging without Data Preview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .437.3 Viewing Trace Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

8 Getting OData URLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

9 Important Disclaimers on Legal Aspects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

2P U B L I C 2014 SAP AG or an SAP affiliate company. All rights reserved.

SAP River Developer GuideTable of Contents

1 What is SAP River?SAP River is a development model for building SAP HANA applications, and includes a language for defining your data model and business logic, as well as a set of development tools.

NoteSAP River is available as part of SAP HANA SPS 07 under an Early Adoption program. For details about joining this program, contact your SAP sales account executive/relationship manager, or write to [email protected].

NoteFor the latest information about SAP River, see SAP Note 1910234 .

The SAP HANA studio comes with tools to help you create SAP River applications, which are made up of SAP River code files with extension .rdl. The tools also enable you to generate test data, to test your business code (actions) and check how they affect your data, and to debug the code. The tools are easily accessible in the SAP HANA Development perspective.

The SAP HANA studio enables you to create an SAP River project, which automatically includes one .rdl file. These code files open in the SAP River editor, which provides features that assist you in writing your code.The SAP HANA studio also includes several views for writing SAP River code, which can be opened using the following icons in the toolbar:Icon Description Context Menu

ItemOpens the data generator, which enables you to create data records for an entity.

Generate Data

Opens the data preview, which enables you to view the current data for an entity, and to run business code (actions).

Data Preview

Opens the OData Calls view, which gives you the URLs to the OData services that are created when you activate your code.

OData Calls

SAP River Developer GuideWhat is SAP River?

P U B L I C 2014 SAP AG or an SAP affiliate company. All rights reserved. 3

Enabling SAP River

For you to be able to build applications, SAP River must be enabled on your server, which includes setting parameters and importing the SAP River DU. In addition, you must be given an SAP HANA user that has developer permissions, including access to a package for saving your code files and activating them.These steps are generally done by an SAP HANA administrator.

Related Information

Generating Test Data [page 34]You can generate test data for your entities to make it easier to perform tests and see the effects of the actions that you developed.

Viewing Data [page 36]The Data Preview view enables you to see the current data for a specific entity, as well as to run actions on an entity instance and see how the actions affect the data.

Getting OData URLs [page 49]The SAP HANA studio provides a tool for displaying the URLs of the OData services that are created when you activate an SAP River file.

Enabling River [page 5]


SAP River Developer GuideWhat is SAP River?

2 Enabling RiverTo enable SAP River development in SAP HANA, an SAP HANA administrator must do the following:1. Import the SAP River delivery unit.2. Configure SAP HANA to enable SAP River.3. Create developer users and give them the required permissions.

2.1 Deploying the SAP River Delivery UnitMuch of the functionality on the server that is, what happens when you activate an .rdl file is handled by a delivery unit that you must deploy to your SAP HANA system.

Procedure

1. Download the SAP River delivery unit SAR file (SAP HANA RDL) from SAP Service Marketplace. The filename of the SAR starts with HANARDL.

2. Deploy the delivery unit with the SAP HANA Lifecycle Manager. For more information on using this tool, see the SAP HANA Update and Configuration Guide.

Results

After deploying the delivery unit, you can see the sap.hana.rdl package in the repository content.

SAP River Developer GuideEnabling River


2.2 Configuring the Server for SAP River

Context

You must indicate that the SAP HANA server is a development machine, which has the following effects on SAP River development: A developer with the DevRole role for a package automatically gets privileges to run an application defined in

that package. A developer with the DevRole role for a package can run any part of an SAP River application no matter the

access control (accessible by) defined in SAP River code.

Procedure

Run the script below in the SQL Console to configure SAP River.

ALTER SYSTEM ALTER CONFIGURATION('indexserver.ini', 'system' ) SET ('rdl','developerrole') = 'DevRole' WITH RECONFIGURE;

Results

You can check the results by opening the Administration editor and choosing the Configuration tag. The new parameter can be seen at indexserver.ini rdl developerrole .

2.3 Setting Up Permissions

An SAP HANA administrator must set up permissions so a developer can create River applications.



Context

Developers must be given design-time privileges to the repository packages where they create their design-time objects, as well as runtime permissions to the schema that holds the runtime objects created when activating a River file.

Procedure

1. Create a new user for the developer, as follows:a) In the SAP HANA Systems view, right-click on the Security Users node of your system, and

choose New User.b) In User Name, enter a name.c) In the Password and Confirm fields, enter a temporary password.

d) Choose in the upper-right part of the user editor.2. Create a package for the developers design-time objects, as follows.

a) In the SAP HANA Systems view, right-click on the Content node of your system, and choose NewPackage .

b) In Name, enter a name for the package.c) Choose OK.

3. Create a schema for the developers runtime objects. The schema must have the same name as the package, and must be owned by user _sys_repo.

NoteThe schema name must be different from the user name.You will not see the schema, and neither will the developer, because the schema will be owned by the _sys_repo user. The schema is visible to the developer as soon as the developer activates a River project.

This must be done by executing the following SQL statement:

create schema "mySchema" owned by _sys_repo;

Replace mySchema with the name of the new schema.4. Create a role with the name in the format $DevRole.For example, if you created for the

developer a package called myPackage, then create a role called myPackage$DevRole.The role enables the developer to access, in runtime, any River application that is activated from the package.a) In the SAP HANA Systems view, right-click on the Security Roles node of your system, and

choose New Role.b) In Role Name, enter the name in the correct format.

c) Choose in the upper-right part of the user editor.5. Give permissions to the developer to create, activate, and debug design-time objects in the package, as

follows:



a) In the SAP HANA Systems view, go to Security Users and open the new developer user.b) In Object Privileges, add the REPOSITORY_REST procedure in the SYS schema and give the developer the

EXECUTE privilege.c) In Granted Roles, give the developer the following roles:

sap.hana.xs.debugger::Debugger The role you created for the developer

d) In Package Privileges, add the package you created for the developer and give the developer the following privileges for the new package (both native and imported objects): REPO.READ REPO.EDIT REPO.ACTIVATE REPO.MAINTAIN

e) Choose Deploy.



3 Getting StartedA developer needs to set up the SAP River environment in the SAP HANA studio, and then can create a HelloWorld application to quickly understand the process for developing with SAP River.

Prerequisites

In order to use SAP River, you must do the following: Install the SAP HANA studio. Get a developer username and password, and be assigned a SAP HANA repository package. Both of these are

done by an SAP HANA administrator, as described in Enabling River [page 5].

3.1 Opening the SAP HANA StudioSAP HANA studio is the Eclipse-based development environment for building SAP HANA applications, including those using the SAP River language and tools.

Context

To build SAP River applications, use the SAP HANA Development perspective.

Procedure

1. Close all instances of Eclipse, and then open the SAP HANA studio.2. Open the SAP HANA Development perspective.

If this is your first time opening SAP HANA studio, the Welcome screen is displayed. Select Open Development.

SAP River Developer GuideGetting Started


If you have previously opened SAP HANA studio, then open the SAP HANA Development perspective by choosing Window Open Perspective Other SAP HANA Development .

Results

The developer workbench opens with the SAP HANA perspective (selected in the upper-right of the screen).

The perspective opens up the following views (on the left):



Project Explorer: A list of projects you are working on SAP HANA Repositories: A list of repository workspaces that enable you to sync your local development files

with a particular SAP HANA system SAP HANA Systems: A list of SAP HANA systems you are connected to

3.2 Installing the SAP River Plug-InThe SAP River plug-in contains all the Eclipse tools that you need to create SAP River applications.

Prerequisites

You must install the SAP HANA studio. You must install the SAP HANA database clients. You must download the SAP River plug-in from SAP Service Marketplace. The plug-in must be the same

version as the SAP HANA system or higher. You must get a developer username and password from your SAP HANA administrator.

Procedure

1. Open the SAP HANA studio.2. In the SAP HANA studio, go to Help Install New Software .

3. Next to the Work with field, choose Add, and then do the following:



a) For Name, enter River.b) For Location, choose Archive, and then navigate to the SAP River archive file, and select it.c) Choose OK.

4. Select SAP HANA Studio River Features, and select Next.

If you don't see SAP HANA Studio River Features, make sure to select Group items by category.5. In the Install Details window, choose Next.6. In the Review Licenses window, accept the license and choose Finish.7. If you get the following warning, choose OK.



8. If you get the following request to restart the SAP HANA studio, choose Yes.

3.3 Setting Up the Development EnvironmentSAP HANA includes a repository for managing design-time objects, including SAP River code files.The workflow is as follows:1. You create development objects as files on your workstation.2. You commit the files to the repository. Committed files are saved in the repository but are not visible to other

developers. By default, whenever you save your development files locally, they are automatically committed to the repository.

3. You activate the files, which creates runtime objects, and the development objects are now visible to other developers.

To manage the development process, you create the following within the SAP HANA studio: System: A connection to an SAP HANA server. Repository Workspace: A place on your local workstation for holding development files to be activated on a

specific system. Project: A collection of related development files. Every project is associated with a repository workspace so

that you can activate the development files in the project on the associated SAP HANA server.



3.3.1 Adding a SystemAdd a system, which makes a connection from the SAP HANA studio to the SAP HANA server that you want to work with.

Procedure

1. Select the SAP HANA Systems view.2. In the white space of the view, right-click and choose Add System.

3. In the Specify System window, enter the following: Hostname: The name of your SAP HANA server Instance Number: The instance number of your SAP HANA server Description: Dev SystemChoose Next.



4. In the Connection Properties window, enter the following: User Name: The developer user that was created for you Password: The password for your user nameChoose Finish.



NoteYou may be asked to change your initial password before you can proceed.

ResultsThe system is added to the SAP HANA Systems view:



The Catalog node includes all the existing schemas for which you have permission, and for each schema you can see all its tables, views, procedures, sequences, and other database objects.The Content node includes all the existing packages for which you have permission. Packages contain design-time files for your development project.The Security node includes all the existing users and roles in the system. As a developer user, you may not be able to see all users and roles.

3.3.2 Creating a Repository WorkspaceAfter connecting to an SAP HANA system, you need to create a folder on your local workstation to hold your development files, and then create a repository workspace, which associates the folder with the repository for a specific SAP HANA system.

Procedure

1. Choose the Repositories view.2. Select the Create Repository Workspace button.

3. In the Create Workspace window: Under SAP HANA System, select the that system you just created. In Workspace Name, enter DevWorkspace. In Workspace Root, enter C:\SAPHANAworkspaces.Choose Finish.

NoteYou can set the workspace root to any location on your workstation, and set the workspace name to any name that you like.

Results

In the Repositories view, you can now see an entry for this workspace, and you can browse the existing packages in the repository for which you have permission.



All design-time development files are contained in packages in the repository. Packages enable you to group your files by project or by type of file. Packages are used to: Enable easy transport of related content to other SAP HANA systems. Enable the setting of different permissions for different development files.Now you are ready to create an SAP River project in an SAP HANA system.

3.4 Creating HelloWorldLets create a HelloWorld application to make sure that the SAP River tools are installed and working properly, and that you can activate an SAP River file to your SAP HANA system.

3.4.1 Creating the HelloWorld ProjectCreate an SAP River project, which automatically includes an .rdl file, which holds your code.

Prerequisites

Before creating an SAP River project, you need to: Add a system to the SAP HANA studio. Create a repository workspace in the SAP HANA studio.

Procedure

1. Select the Project Explorer view.2. Create an SAP River project by choosing File New Project .3. Select SAP HANA River Application Development River Project and choose Next.



4. In the Project Name field, enter HelloWorld.



5. Choose Finish.A new SAP River project is added to the Project Explorer view. An .rdl file is created with the same name as the project, and is opened in the code editor on the right.



NoteThe project also contains an .xsapp file, which enables the runtime objects that are created when SAP River is compiled to be run. You do not need to modify this file.

6. Share the project with the repository of your SAP HANA system by right-clicking the project and choosing Team Share Project .

7. In the Share Project window, specify where you want to place the project in the repository, as follows:a) Under Repository workspaces, select RiverWorkspace (the repository workspace that you created

earlier).b) In Repository package, browse to and select the package that was created for your development.c) Deselect the Add project folder as sub-package checkbox.d) Choose Finish.



Results

Your project is now associated with a specific SAP HANA system, which enables you to commit and activate your files to the repository on that system. You will commit and activate your files in the next step.

Once your project is shared with a repository workspace, the icon for each file indicates the status of the file, as follows:

Indicates that the version of the file on your workstation has been modified but not committed to the repository.



Indicates that the version of the file on your workstation has been committed to the repository, but has not been activated (and, therefore, cannot be run or viewed by other developers).Indicates that the version of the file on your workstation has been activated in the repository and can be run.

By default, all changes to your files are automatically committed to the repository. You can change this in the settings with the menu Window Preferences SAP HANA Development Repository Access .

3.4.2 Coding and Activating HelloWorld

To create an SAPRiver application, simply add code to the .rdl file and activate the file in the SAP HANA system.

Context

The code below creates an entity called MyEntity with one data element (name), and an action (greeting) that returns a greeting using the contents of name from the current instance of the entity.

Procedure

1. In the HelloWorld.rdl file, delete all text and copy and paste the following code into the file:

@ODataapplication HelloWorld { entity MyEntity { key element name: String; action greeting() : String { return 'Hello ' + this.name + '. Welcome to SAP River!'; } }}

2. Save the file.This saves the file on your workstation and commits it to the repository on the server. But it is still not compiled, you cannot run it, and nobody can see your changes.

3. Right-click the project and choose Team Activate (or CTRL-F3).This compiles the River code into runtime objects, and you can now make OData calls to retrieve data and execute actions.



3.4.3 Testing HelloWorldLets make sure everything activated OK. You can check that you can make OData calls based on the SAP River code that you just activated, and you can check that tables were created for your entity.

Procedure

1. Make an an OData call to retrieve the instances in your new entity (so far there are none). You do this to retrieve the X-CSRF-TOKEN, which you need in order to later perform a POST call to add a row to the table.Make the following OData call (make sure to change the server name and port for your installation, to change the package DevUser to the package you are using, and provide the credentials for your new developer user): URL: http://myserver:8000/sap/hana/rdl/odata/v1/DevUserPackage/HelloWorld/

MyEntity Method: GET Request Body: None Request Headers:

Header ValueX-CSRF-TOKEN Fetch

Response Body:{ "d": { "results": [] }}

You should also receive a response cookie X-CSRF-TOKEN, which you have to send along with its value with every non-GET request during the current session.

2. Now lets make another OData call to add a record to the entity MyEntity (again, make sure to change the server name and port for your installation, and provide the credentials for your new developer user): URL: http://myserver:8000/sap/hana/rdl/odata/v1/DevUserPackage/HelloWorld/

MyEntity Method: POST Request Body:

{ "name": "Rachi"}

Request Headers:Header ValueX-CSRF-TOKEN The value returned in the previous OData call.

Response Body:{ "d": {



"results": { "__metadata": { "uri": "/odata/v1/DevUserPackage/HelloWorld/MyEntity('Rachi')", "type": "HelloWorld.MyEntity" }, "name": "Rachi" } }}

The response shows details about the record that was just created.3. Finally, you can call the action to get back a greeting.

URL: http://myserver:8000/sap/hana/rdl/odata/v1/DevUserPackage/HelloWorld/MyEntity('Rachi')/greeting

Method: POST Request Body: None (Make sure to delete the request body from the previous call.) Response Body:

{ "d": "Hello Rachi. Welcome to SAP River!"}

The response shows the return value of the action.4. After deploying your SAP River file, you can check in the SAP HANA studio to see that a table was created for

your entity, in the SAP HANA Systems view. The table that holds the data for your entity is called DevUserPackage::HelloWorld.MyEntity..

The tables are created in a schema with the same name as your package. The name of each table is the name of the package (DevUserPackage), followed by a double-colon (::), followed by the fully qualified name of the entity (HelloWorld.MyEntity).If youve added an instance via the OData call, then you can right-click the table DevUserPackage::HelloWorld.MyEntity and select Open Data Preview to view the new data.



4 Coding in SAP RiverThe SAP HANA studio includes tools for making it easy to code in SAP River.The following are among the tools that help you to code in SAP River: New project wizard, which enables you to create new SAP River projects SAP River editor, which includes features to help you navigate and format the code Search wizard, which lets you make references to existing SAP HANA tables and views

Note You can create only one project in a package. You can add a project to a subpackage, but then either there must not be an .xsapp file in any package

above the subpackage, or you must delete the .xsapp file from your project.

4.1 Creating an SAP River ProjectTo create applications with SAP River, you create an SAP River project and write your code in an .rdl file in the project.

Procedure

1. Choose File New Project .2. Select SAP HANA River Application Development River Project , and choose Next.3. In Project Name, enter a name for the project.4. Choose Finish.

Results

An .rdl file with the same name is added to the project. You can write your SAP River code in this file.

4.2 Creating an SAP River Source FileYou can divide your code into several .rdl files within the same project.

SAP River Developer GuideCoding in SAP River


Procedure

1. Highlight your project and choose File New Other .2. Select SAP HANA River Application Development River Source File , and choose Next.3. In File Name, enter a name for the file.4. Choose Finish.

Results

An .rdl file is added to the project.

4.3 Editing SAP River Code

SAP River code files are, by default, opened in the SAP River code editor, which provides many features that help you to edit the code.

Procedure

Syntax Highlighting: The editor highlights different parts of the code with different colors and fonts. For example, by default, keywords are shown in bold and purple.

You can change the default settings by choosing Windows Preferences SAP HANA River Application Development Editor Syntax Coloring .

Error Checking: The editor checks for syntax mistakes, and shows them with a red mark in the margin.

Hover over the red error mark to display a tooltip that describes the error. Code Completion: The editor suggests ways to automatically complete the code you are typing. For example,

whenever a type is needed in the code, a list of valid types is displayed.



In addition, you can type part of a keyword or identifier, and then press Control-Space, and the editor will try to complete the code.

Navigation Links: You can navigate from any reference to an entity, type, element, or other SAP River object by hovering over the reference and holding down the Control key.For example, you put the cursor on element name and click, the editor moves to and highlights the definition for the element.

Outlining: The SAP River editor comes with an outline of the code, so that you can navigate within the code. You can view the outline in the following ways: Quick Outline: A pop-up dialog box within the code editor that shows an outline of the major parts of your

code, for example, namespaces, entities, views, and elements.



To view the quick outline, either right-click anywhere in the editor and choose Quick Outline, or go to the menu Navigate Quick Outline .

Outline View: Open the Outline view to keep the outline open at all times. Indenting: The editor automatically indents your code, skipping four spaces when a new indent is needed. For

example, if you type in namespace myNamespace { and then press Enter, the editor will automatically format the code as follows:

The editor inserts the closing brace, and indents the cursor.If you typed in code and deleted code and the indenting is no longer correct, you can fix the indentation by right-clicking in the editor and choosing Source Correct Indentation .

Toggling Comments: You can comment and uncomment a line of code by selecting one or more lines of code, and then right-clicking and choosing Source Toggle Comments .

You can expand and collapse sections of your code, for example, collapse the definition of an entity, so you see only the name of the entity and not all its elements.

You can select which sections of your code can be collapsed by choosing Windows Preferences SAP HANA River Application Development Editor Folding .

4.4 Searching for Tables and ViewsYou can search for existing SAP HANA tables and views and add a reference to them in your SAP River code. For example, you can create an SAP River view that returns data from an existing SAP HANA table and then use that data in your application.



Prerequisites

Periodically, when tables and views are added or removed, you need to re-index by choosing RiverSearch in SAP HANA Re-index .

To search for tables and views, you must be assigned the Modeling role. To view the data of the selected tables and views, you need to have the appropriate permissions to the schema that contains the tables and views.

As with any SAP HANA table that you want to use in your SAP River code, the _SYS_REPO user must have select, execute, delete, insert, and update privileges for the schema that contains the table.

Procedure

1. In the SAP River editor, right-click where you want to add the name of a table or view in your code (or press Control-Shift-V), and choose River Search in SAP HANA Tables / Views .

2. In the Table/View Search window, enter a search term, and choose Search.



The search tries to match the search term with one or more of the following: Table name or description View name or description Column name or description

3. Select a table or view.4. Choose OK.



Results

The name of the table or view is inserted into the code at the position of the cursor.

4.5 Activating SAP River CodeActivating is the act of compiling your code, which creates all the corresponding SAP HANA objects, including tables, procedures, and OData services.Whenever you make a change to the code, it is best to activate your entire project. Select the project in the Project Explorer, and choose .Whenever you make a change to an entity, it is reflected in changes in the underlying database tables. And if there is data in the table, a change in the data structure could result in loss of data. For example, if your entity has data and you change a String(20) element to a String(10) element, or eliminate an element altogether, you may lose data and you will not be able to activate your project.To get around this, you must remove the data from the underlying table, for example, by running the following SAP River code:

apply delete() to select * from MyEntity;

To delete the data, you can also run a truncate table SQL statement on the table.The name of the underlying table is ::. The schema name is the same as the package name, and the fully qualified name is the path from the top-level application through any namespaces to the entity.



5 Generating Test DataYou can generate test data for your entities to make it easier to perform tests and see the effects of the actions that you developed.

Context

Test data for each element is created in one of the following ways: Fixed: You specify a value for the element, and all instances for the entity contain that value for that element. Random: The data is generated randomly, but based on one of the following rules:

Dates: You can generate random dates, or dates within a specified range. Integers: You can generate random integer values, or integers within a specified range. Decimals: You can generate random decimal values. String: You can generate random strings, based on one of the following:

Each string begins with the name of the field, followed by a random number. Each string is a name made up of randomly selected common words (for example, Orange

Doorknob). Each string is a randomly selected name of a person. Each string is randomly selected from a text file that contains all possible values, separated by

commas. Enumerations: You can generate random values from the list of valid enumeration values. Associations: You can generate random values from the existing instances of the associated entity. You

must first create instances for the associated entity.You also specify how many instances to create for the entity.

Procedure

1. Select an entity in the code, right-click within the entity, and choose River Generate Data .The Generate Test Data window opens, showing the rules for generating data for each of the elements of the entity.


SAP River Developer GuideGenerating Test Data

NoteIf the entity has an element that is a custom type, then there is a row for each element of the custom type. For example, if you define a type:

type PersonName { element FirstName: String; element LastName: String;}

and you define an entity based on this type:

entity Person { element Name : PersonName;}

then there is a row for defining a rule for Person.FirstName and Person.Lastname.

2. If you want to change the rule for an element, choose the button for that element, change the rule, and choose OK.

3. In Records to Generate, enter the number of records to create.4. When you are done changing the rules, choose Next.

A set of of data is generated and displayed so that you can review it before it is added to the database.5. If you are happy with the sample data, choose Next. The data is geerated and added to the database.

If you want to change the rules, choose Back.

SAP River Developer GuideGenerating Test Data


6 Viewing DataThe Data Preview view enables you to see the current data for a specific entity, as well as to run actions on an entity instance and see how the actions affect the data.

Prerequisites

You must have Microsoft Internet Explorer 9 or above installed on your workstation to use the Data Preview view.

Procedure

Select an entity in the code, right-click within the entity, and choose River Data Preview . The Data Preview view opens, showing the current data for the entity.

If one of the fields is an association to another entity, then you can click on the fields value to see the

associated instance. Click to return to the original instance.


SAP River Developer GuideViewing Data

6.1 Modifying DataYou can create, modify, and delete instances of an entity with the Data Preview view.

Context

To create an instance, choose Create, add the data for the instance, and choose Save. To modify an instance, select the instance in the table, choose Update, modify the data for the instance, and

choose Save. To delete an instance, select the instance in the table, and choose Delete.

6.2 Running ActionsYou can test an entity's actions by running them and checking the results.



Context

Test an action by selecting an instance of your entity in the Data Preview view, and then choosing Run Action and the name of your action.

If the action requires you to pass a parameter, you are prompted for the parameter.



Select Run in Debugger to run the action and start a debugging session, where you can stop execution and check the value of entities and variables in your action.

Related Information

Debugging SAP River Code [page 40]The SAP River debugger lets you view the execution of your action code. You can run the code line-by-line, and examine entities, variables, and expressions.



7 Debugging SAP River CodeThe SAP River debugger lets you view the execution of your action code. You can run the code line-by-line, and examine entities, variables, and expressions.

Prerequisites

For you to debug: You must have the role sap.hana.xs.debugger::Debugger. The SAP HANA XS JavaScript debugger must be enabled by the SAP HANA administrator.

Context

The SAP River debugger is integrated into the standard SAP HANA Eclipse-based debugging tools, which include: Debug perspective The following views:

Debug Variables Breakpoints

NoteIn the SAP HANA studio, the Debug perspective does not automatically open when debugging begins. If you want it to open automatically, choose Window Preferences Run/Debug Perspectives , and set the setting Open the associated perspective when launching to Prompt.

For debugging to work, it must be enabled by setting the server configuration. You must have administrator rights.

Procedure

1. In the SAP HANA Systems view, right-click your system and choose Administration.2. In the Configuration tab, add a section called xsengine.ini debugger (if it does not exist) and add (or

set) the following parameter: enabled = true


SAP River Developer GuideDebugging SAP River Code

Related Information

Debugging with Data Preview [page 41]The easiest way to debug is by using the Data Preview view, which lets you debug your code even before you have created a UI that sends OData calls.

Debugging without Data Preview [page 43]You can also run the SAP River debugger without the Data Preview view. You may want to do this because you want to debug an action that is not within an entity, or you already created a UI and would like to start the debugging process by making your own OData calls.

SAP HANA Developer Guide

7.1 Debugging with Data PreviewThe easiest way to debug is by using the Data Preview view, which lets you debug your code even before you have created a UI that sends OData calls.

Prerequisites

For you to debug: You must have the role sap.hana.xs.debugger::Debugger. The debugger must be enabled by the SAP HANA administrator.

Context

The Data Preview view lets you see the data of your entities and run actions to check how the data is affected. The view also lets you run the actions with the debugger, essentially creating a debug session for you when you do not have a UI or REST client to make OData calls. The Data Preview view automatically creates the debug configuration and starts a debug session.

Procedure

1. Open the Debug perspective.2. Add breakpoints in the SAP River actions that you want to debug.

To add a breakpoint, double-click in the left vertical ruler where you want to add a breakpoint.



3. Select an entity in your code.4. Open the Data Preview view by right-clicking within the entity, and choosing River Data Preview .

The existing data for your entity is displayed.5. In the Data Preview view, select an instance.6. Choose Run Action, and then select the action to run.

7. Enter any required parameters.8. Select the Run in Debugger checkbox.



9. Choose Run.

Results

The debugger now stops at the breakpoints that you set.

Related Information

Viewing Data [page 36]The Data Preview view enables you to see the current data for a specific entity, as well as to run actions on an entity instance and see how the actions affect the data.


7.2 Debugging without Data PreviewYou can also run the SAP River debugger without the Data Preview view. You may want to do this because you want to debug an action that is not within an entity, or you already created a UI and would like to start the debugging process by making your own OData calls.

Prerequisites

For you to debug: You must have the role sap.hana.xs.debugger::Debugger. The debugger must be enabled by the SAP HANA administrator.



Procedure

1. Write SAP River code and activate it.2. Open a REST client.3. Execute any OData call (for example, a call that retrieves an entitys instances):

Specify the URL. Add the username and password as a header.

4. Take note of the value of the xsSessionId cookie.You will need the cookie to specify the name of the session that you want to debug.

5. In the SAP HANA studio, choose Debug Configurations.

6. Right-click River, and choose New.



A new debug configuration is created for SAP River debugging, with all of the connection details automatically inserted, based on the currently selected file.

7. In the Name field, enter a name for the configuration, and choose Debug.

8. In the Select Session dialog box, select the session to debug, and choose Select.The session name is the same as the xsSessionId cookie that appeared in your REST client. You can filter the sessions by user.



9. Open the Debug perspective.10. Add breakpoints in the SAP River actions that you want to debug.

To add a breakpoint, double-click in the left vertical ruler where you want to add a breakpoint.

11. Execute the OData call to run your action.You must define the following header for all calls that you want to debug: Header Name: DEBUG_MODE Header Value: trueThe debugger should now stop at the breakpoint that you set.



NoteMake sure to include the X-CSRF-Token header, since you are making a POST call.

Related Information


7.3 Viewing Trace FilesSAP River writes diagnostic messages to the SAP HANA XS trace file, which you can view in the SAP HANA studio. You can also write from your applications to this file using the SAP River logging built-in library.Open the Administration editor (by double-clicking your system in the SAP HANA Systems view), and select the Diagnosis Files tab. Here you can see all trace files. SAP River logs are located in the xsengine trace file.Filter for the xsengine trace files by entering xsengine in the Filter field. Check the xsengine trace file with the most recent date.

To view a file, double-click it.

Changing the Log Level

By default, only SAP River error messages are logged. If you want to log additional messages, you can change the log level.Open the Administration editor (by double-clicking your system in the SAP HANA Systems view), and select the

Trace Configuration tab. Under Database Trace, select the button.



In the Trace Configuration window, select Show All Components, and then filter by sap.hana.rdl.

Now you can change the System Trace Level, and choose Finish.



8 Getting OData URLsThe SAP HANA studio provides a tool for displaying the URLs of the OData services that are created when you activate an SAP River file.

Prerequisites

For you to view the OData URLs: You must expose your SAP River code via the @OData keyword, and activate your code. Your browser must support HTML5.

Procedure

1. Select an entity in the code, right-click within the entity, and choose River OData Calls .The OData Calls view is displayed, showing the URLs for all the OData calls that are exposed for your SAP River code.

2. Find the URL that you want to use, and choose Select Text. You can now copy and paste the URL into a REST client.

SAP River Developer GuideGetting OData URLs


9 Important Disclaimers on Legal AspectsThis document is for informational purposes only. Its content is subject to change without notice, and SAP does not warrant that it is error-free. SAP MAKES NO WARRANTIES, EXPRESS OR IMPLIED, OR OF MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.Coding SamplesAny software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP intentionally or by SAP's gross negligence.AccessibilityThe information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a binding guideline on how to ensure accessibility of software products. SAP specifically disclaims any liability with respect to this document and no contractual obligations or commitments are formed either directly or indirectly by this document.Gender-Neutral LanguageAs far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible.Internet HyperlinksThe SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. Regarding link classification, see: http://help.sap.com/disclaimer


SAP River Developer GuideImportant Disclaimers on Legal Aspects

SAP River Developer GuideImportant Disclaimers on Legal Aspects


www.sap.com/contactsap

2014 SAP AG or an SAP affiliate company. All rights reserved.No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice.Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. National product specifications may vary.These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries.Please see http://www.sap.com/corporate-en/legal/copyright/index.epx for additional trademark information and notices.

SAP River Developer GuideTable of Contents1 What is SAP River?2 Enabling River2.1 Deploying the SAP River Delivery Unit2.2 Configuring the Server for SAP River2.3 Setting Up Permissions

3 Getting Started3.1 Opening the SAP HANA Studio3.2 Installing the SAP River Plug-In3.3 Setting Up the Development Environment3.3.1 Adding a System3.3.2 Creating a Repository Workspace

3.4 Creating HelloWorld3.4.1 Creating the HelloWorld Project3.4.2 Coding and Activating HelloWorld3.4.3 Testing HelloWorld

4 Coding in SAP River4.1 Creating an SAP River Project4.2 Creating an SAP River Source File4.3 Editing SAP River Code4.4 Searching for Tables and Views4.5 Activating SAP River Code

5 Generating Test Data6 Viewing Data6.1 Modifying Data6.2 Running Actions

7 Debugging SAP River Code7.1 Debugging with Data Preview7.2 Debugging without Data Preview7.3 Viewing Trace Files

8 Getting OData URLs9 Important Disclaimers on Legal AspectsCopyright and Trademarks

SAP River Developer Guide

Documents

Transcript of SAP River Developer Guide