Rocket U2 Web Development Environment Getting Started with REST Services

Rocket U2 Web Development Environment

Getting Started with REST Services

Version 5.3.0

July 2017 WDE-530-RES-IM-01 Notices

Edition Publication date: July 2017 Book number: WDE-530-RES-IM-01 Product version: Version 5.3.0

Trademarks Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks go to: www.rocketsoftware.com/about/legal. All other products or services mentioned in this document may be covered by the trademarks, service marks, or product names of their respective owners.

Examples This information might contain examples of data and reports. The examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

License agreement This software and the associated documentation are proprietary and confidential to Rocket Software, Inc. or its affiliates, are furnished under license, and may be used and copied only in accordance with the terms of such license.

Note: This product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption technologies, and current use, import, and export regulations should be followed when exporting this product.

2 Corporate information

Rocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks, and compliance; database servers and tools; business information and analytics; and application development, integration, and modernization. Website: www.rocketsoftware.com Rocket Global Headquarters 77 4th Avenue, Suite 100 Waltham, MA 02451-1468 USA To contact Rocket Software by telephone for any reason, including obtaining pre-sales information and technical support, use one of the following telephone numbers.

Country Toll-free telephone number United States 1-855-577-4323 Australia 1-800-823-405 Belgium 0800-266-65 Canada 1-855-577-4323 China 400-120-9242 France 08-05-08-05-62 Germany 0800-180-0882 Italy 800-878-295 Japan 0800-170-5464 Netherlands 0-800-022-2961 New Zealand 0800-003210 South Africa 0-800-980-818 United Kingdom 0800-520-0439

Contacting Technical Support The Rocket Community is the primary method of obtaining support. If you have current support and maintenance agreements with Rocket Software, you can access the Rocket Community and report a problem, download an update, or read answers to FAQs. To log in to the Rocket Community or to request a Rocket Community account, go to www.rocketsoftware.com/support. In addition to using the Rocket Community to obtain support, you can use one of the telephone numbers that are listed above or send an email to [email protected].

3 Contents

Notices...... 2 Corporate information...... 3 Chapter 1: Rocket U2 Web Development Environment overview...... 5 Introduction...... 5 Chapter 2: Enabling Web DE REST Services...... 6 Using RBO RESTful web services...... 6 Creating REST servers...... 6 Starting, stopping, and restarting REST servers...... 7 Remote servers...... 7 Upgrading a REST server...... 8 Upgrading a single REST server...... 8 Upgrading all REST servers...... 8 Creating RBO services...... 8 Creating stateful or stateless RBO services...... 9 Creating uQuery RBO services...... 10 Editing RBO services...... 12 Chapter 3: Testing RBO services...... 13 Testing RPC services...... 13 Testing REST services...... 15 Testing uQuery RBO services...... 17 Chapter 4: Security...... 21 User Access Control...... 21 Securing REST services with UAC...... 21 Cross Origin Request Sharing (CORS) Access...... 22 Chapter 5: Logging and debugging...... 24 Chapter 6: Deployment...... 25 Importing and exporting REST servers...... 26 Deploying a REST server using the deployment tool...... 27 Starting the deployment tool...... 28 Defining server connection security...... 29 Defining user access...... 30 Defining resource folder properties...... 31 Deploying a REST server from the command line...... 32 Starting the deployment tool...... 32 Defining server connection security...... 34 Defining resource folder properties...... 34 Deploying a REST server from the command line...... 35 Deploying a REST server from a configuration file...... 36 Generating a configuration file...... 36 Updating the configuration file using the deployment tool...... 38 Disabling security protocols from the configuration file...... 38 Deploying a RESTful service as a Windows service...... 39 Starting a RESTful service...... 40 Stopping a RESTful service...... 40 Chapter 7: Troubleshooting...... 42 Server Response: 500 error...... 42

4 Chapter 1: Rocket U2 Web Development Environment overview

Rocket U2 Web Development Environment (Web DE) is an application development toolkit for building interactive client/server applications for deployment on the World Wide Web or on a corporate intranet. Introduction

Using U2 Web DE REST Services, you can create mobile applications that are built on your existing RedBack Objects (RBOs) and U2 data. The Web DE REST Services features built into the U2 Web Designer allow you to create RBO services, or RESTful RBOs, from your traditional RBOs. These RBO services can be called over HTTP, allowing them to be directly accessed from various devices and programming environments.

5 Chapter 2: Enabling Web DE REST Services

Web DE REST Services features are accessed from the RESTful RBO perspective in Web Designer. Once the perspective is open, you can create REST servers and RBO services, and then test the services and perform debugging tasks, if necessary. Before enabling and using Web DE REST Services, perform the following tasks: ▪ Install the UniVerse or UniData database. ▪ Install U2 Web DE. ▪ Install Web Designer. ▪ Set up the API server. ▪ Ensure you have access to Web DE REST Services, which is a non-chargeable add-on and part of your Web DE license. To add this option to your license, complete the appropriate step: ▫ Rocket partners: Add the services option via the RBC website. ▫ Rocket direct customers: Send a request to [email protected]. ▫ Rocket partners' customers: Contact your Rocket Software partner. Access to services is granted when the RedBack Object Server is authorized. For help with these tasks, see the UniVerse or UniData documentation, Web DE Installation and Configuration, and Administrator’s Guide. Using RBO RESTful web services

The RBO Services Perspective is the view you will access when using REST services. It is divided into four different panes, which are used to view information and perform a variety of tasks. In the Web Designer, click Window → Open Perspective → RBO Services Perspective. If the RBO Services Perspective option does not appear in the menu: ▪ Click Other and select the Show all check box. The RBO Services Perspective option displays in the list of available perspectives. Select it and click OK. If a Confirm Enablement dialog box displays, click OK. ▪ If the RBO Services Perspective option still does not appear, ensure the mobility add-on is part of your Web DE license. The Web Designer perspective changes to the RESTful RBO perspective, which is divided into four different panes: ▪ The upper-left pane displays the U2 Resource view, which shows accounts, files, and all resources of the account on the connected database server. ▪ The lower-left pane displays the U2 REST Servers view. You can create, edit, start, and stop servers from this view. ▪ The upper-right pane is an editor view for performing tasks, such as editing the properties and methods of an RBO. ▪ The lower-right pane contains different views, which depend on the process or action taking place. Creating REST servers

To work with RESTful web services, you must first create a REST server. A wizard guides you through the process of creating this type of server.

6 Starting, stopping, and restarting REST servers

Prerequisites Using RBO RESTful web services, on page 6

Procedure

1. In the U2 REST Servers view, right-click the REST Servers node, and select New REST Server. 2. On the first page of the New REST Server wizard, enter a server name and accept the defaults for the other fields. Click Next. 3. Optional: It is strongly recommended that you enable SSL for all REST servers. If you do not use SSL, your data is vulnerable to spying whenever you make calls to your RBO services over HTTP. You can further enhance your security by following the steps in Securing REST services with UAC, but UAC does not protect data in transit. a. In the Key Store field, enter the full path to the keystore that contains your certificate, or click Browse to navigate to it.

Note: You can use tools such as Rocket Software U2 Extensible Administration Tool to create a certificate, and you can use the Oracle keytool to import the certificate into a keystore. To use U2 Extensible Administration Tool to generate a certificate, follow the instructions in the UniData Security Features manual or the UniVerse Security Features manual. The Oracle keytool utility is installed with Oracle JDK. For more information about keytool, see the Oracle documentation on keytool, currently at http:// docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html for Windows and https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html for UNIX. Note that these URLs might change over time.

b. Enter the relevant passwords. 4. Click Finish. 5. After the wizard closes, click the arrow to expand the REST Servers node and view your new REST server.

Starting, stopping, and restarting REST servers

You can start, stop, or restart REST servers at any time. To start a REST server, right-click the server name in the REST Servers pane. Select Start REST Server, Stop REST Server, or Restart REST Server. The Restart REST Server menu option only displays if the REST server is running.

Remote servers

U2 RESTful Web Services allows for limited remote RESTful server monitoring. You can use this functionality to stop a remote server, but you cannot restart the server remotely. You can also turn the REST Server Debug on or off remotely.

7 Chapter 2: Enabling Web DE REST Services

Upgrading a REST server

When a REST server is first created, a number of class files and other server-side artifacts are created for the server. When you upgrade to a new version of Web DE, you must also upgrade your U2 REST servers with the latest code and artifacts from the current version of Web DE. You can upgrade existing Web DE REST servers in two ways: ▪ Upgrading a single REST server. ▪ Upgrading all REST servers.

Upgrading a single REST server

Prerequisites ▪ Creating REST servers, on page 6

Procedure

1. From the U2 REST Servers pane of the Web Designer, right-click the server and select Stop REST Server. 2. Right-click the server that you want to upgrade, and select Upgrade Server. 3. Optional: In the U2 RESTful Web Services Developer dialog, click Back up if you want to create a backup zip file to be made of the existing server in the location specified. 4. Click Upgrade. A success message notifies you when the upgrade is complete.

Upgrading all REST servers

Prerequisites ▪ Creating REST servers, on page 6

Note: Before you can upgrade all of the REST servers, stop each server by right-clicking it and selecting Stop Server.

Procedure

1. From the U2 REST Servers pane of the Web Designer, right-click REST Servers and select Upgrade Servers. 2. Optional: In the U2 RESTful Web Services Developer dialog, click Back up if you want to create a backup zip file to be made of the existing servers in the location specified. 3. Click Upgrade. A success message notifies you when the upgrade is complete.

Creating RBO services

You can create RBO services out of any type of RBO: uQuery, stateful, or stateless. Stateful RBOs and uQuerys maintain their session state via a Session-Id custom HTTP header. A REST-style API is available for your RBO services along with the default RPC-style API.

8 Creating stateful or stateless RBO services

Creating stateful or stateless RBO services

A wizard guides you through the process of creating an RBO service for a stateful or stateless RBO. When finished, the new RBO service displays under the RBO Resources node in the U2 REST Servers view.

Prerequisites Creating REST servers, on page 6

About this task By creating an RBO service from a stateful RBO, you can store runtime data that is related to your RBO on the U2 server. With a stateful RBO service, you can also take advantage of the optimistic locking functionality that is built into the RedBack Object Server. Basing your RBO service on a stateless RBO can be beneficial for the same reasons that stateless RBOs are useful in Web DE, in general. Stateless RBOs place less load on the U2 server and are therefore faster. They can be useful if application state is to be stored elsewhere, for example in the middle tier, or where the RBO does not actually require any state to be stored. With either a stateful or stateless RBO service, you can use a REST-style API. The REST-style API treats the RBO as a resource that can be operated upon with the standard HTTP verbs (GET, PUT, POST, DELETE). These verbs are mapped to RBO methods that represent create, read, update, and delete (CRUD) operations. The intended functionality of some RBOs is not well suited for CRUD operations. In those cases, an RPC-style API might be more appropriate.

Procedure

1. From the U2 Resource view in the Web Designer, select an RBO and drag it to the REST server node in the U2 REST Servers view. 2. Every server must have a resource folder that stores the services for a specific account. ▪ If a resource folder does not yet exist, the wizard prompts you to create a new one. Continue to the next step. ▪ If a resource folder exists, the wizard prompts you to provide information about the RBO service. Continue to step 6. 3. In the Create a New Resource Folder dialog, enter a name for the resource folder in the Name field, accept the defaults for the other fields, and click Next. 4. Optional: If you are using SSL security, select the Use SSL check box and enter the applicable trust store information. Click Next. 5. Click Finish. 6. On the first page of the RBO Service Details wizard, complete the RBO service name and Account name fields, and click Next. 7. On the RBO Service Properties page, select the properties that you want to use to define the service properties.

9 Chapter 2: Enabling Web DE REST Services

8. Select the correct depth for each property using one of the following methods: ▪ For an individual row, click the Depth field and select a depth option from the drop-down menu. ▪ Ctrl or Shift + click to select multiple rows, right-click and select a depth option from the Change depth context menu. ▪ Ctrl or Shift + click to select multiple rows, and below the table, select a depth option from the Change depth of selected items to: drop-down menu.

Note: Depending on how the original RBO was created, incorrect depths might appear in the Depth column by default. Ensure each property is correctly specified as Single-valued, Multivalued, or Multi-subvalued fields.

Figure 1: Field depth

9. Click Next. 10. On the RBO Service Methods page, select the RBO methods to expose in the service. Click Next. 11. Choose an API style for your RBO service by selecting the appropriate option. ▪ RPC-style API: Uses the HTTP POST to call the RBO method specified. ▪ REST-style API: Supports CRUD (create, read, update and delete) operations. If you select this option, complete the associated fields, as appropriate. 12. Click Finish to create the RBO service, which displays under the RBO Resources node in the U2 REST Servers view.

Creating uQuery RBO services

A wizard guides you through the process of creating uQuery RBO services. When finished, the new uQuery RBO displays under the RBO Resources node in the U2 RESTServers view.

Procedure

1. In the U2 Resource view, select a uQuery RBO and drag it to the REST server in the U2 REST Servers view. 2. Every server must have a resource folder that stores the services for a specific account.

10 Creating uQuery RBO services

▪ If a resource folder does not yet exist, the wizard prompts you to create a new one. Continue to the next step. ▪ If a resource folder exists, the wizard prompts you to provide information about the RBO service. Continue to step 6. 3. In the Create a New Resource Folder dialog, enter a name for the resource folder in the Name field, accept the defaults for the other fields, and click Next. 4. Optional: If you are using SSL security, select the Use SSL check box and enter the applicable trust store information. Click Next. 5. Click Finish. 6. On the first page of the RBO Service Details wizard, complete the RBO service name and Account name fields, and click Next. 7. On the RBO Service Query Fields page, select the properties that you want to use to define the service parameters. 8. Select the correct depth for each property using one of the following methods: ▪ For an individual row, click the Depth field and select a depth option from the drop-down menu. ▪ Ctrl or Shift + click to select multiple rows, right-click and select a depth option from the Change depth context menu. ▪ Ctrl or Shift + click to select multiple rows, and below the table, select a depth option from the Change depth of selected items to: drop-down menu.

Figure 2: Field depth

9. If you want your uQuery service to be able to change its select_criteria property at runtime, select the Enable selection criteria check box. 10. Indicate the maximum number of items you want to see in your search results on each page in the Maximum items per page section of the dialog. This setting cannot be overridden once the RBO service is created.

11 Chapter 2: Enabling Web DE REST Services

11. Click Finish to create the uQuery RBO, which displays under the RBO Resources node in the U2 REST Servers view.

Editing RBO services

The RBO Services Editor allows you to make changes to existing RBO services.

Procedure

1. From the U2 REST Servers view, right-click a service and select Edit. 2. In the dialog box that displays, enter your credentials to the U2 Web DE repository. Access to the repository allows the editor to retrieve the current definition of the RBO that is backing the service being edited. If you do not enter your credentials (by clicking Cancel at the dialog), you can still work with the service as it is currently defined. However, you will not be shown the full set of RBO properties and methods for the backing RBO. A dialog will appear indicating this before the editor is ultimately opened. After you enter your credentials or click Cancel, the editor displays:

3. Click the relevant tab at the bottom of the screen for the part of the service that you want to edit and make changes. The tabs available depend on the type of RBO service you are editing. You can make changes in the same way you created the service, as described in the previous sections. 4. When you are finished making changes, click Save.

12 Chapter 3: Testing RBO services

Web DE provides a testing tool that you can use to test your RBOs without leaving the development environment. Test the RBO services you create to verify that the service works before you write mobile applications. Testing your method calls provides a mechanism for isolating problems. For example, if there is a problem when calling a method from a RedBeans or RedPages.NET form, but the method call works from the testing tool, the problem points to the client code, rather than the RBO or the RedBack Object Server code. Refer to the following: • Testing RPC services To test stateful and stateless RPC services, access the testing tool, specify the method that you want to invoke from the service, and determine if the appropriate results display. • Testing REST services To test stateful and stateless RESTful services, access the testing tool, specify the method that you want to invoke from the service, and determine if the appropriate results display. • Testing uQuery RBO services To test uQuery RBO services, access the testing tool, add selection parameters to the query string if appropriate, and determine if the appropriate results display. Testing RPC services

To test stateful and stateless RPC services, access the testing tool, specify the method that you want to invoke from the service, and determine if the appropriate results display.

Procedure

1. From the U2 REST servers view, double-click the RBO to test. Use this browser to run your RBO service. The following example shows the testing of an RPC- style RBO service, created from the Customers RBO, found in the rbexamples account. If the test browser returns an error, wait a few seconds and refresh the browser.

13 Chapter 3: Testing RBO services

Figure 3: RPC test browser

2. From the Method drop-down menu, select the method to invoke from the service. 3. If the RBO you are testing is stateful, the test page contains a Use Session Id check box. Select this option to have the test page automatically copy the session ID from the result into the session ID header of subsequent requests. RBO Services that are backed by stateful RBOs use a session ID to reference the RBO state that is stored on the server in between requests.

14 Testing REST services

4. Enter the values required for the method call in the Request Body pane and click Send. The service is invoked, and the results are displayed in the Response pane:

Figure 4: Test result

Parent topic: Testing RBO services Testing REST services

To test stateful and stateless RESTful services, access the testing tool, specify the method that you want to invoke from the service, and determine if the appropriate results display. 1. From the U2 REST servers view, double-click the RBO to test. Use this browser to run your RBO service. The following example shows the testing of an REST- style RBO service created from the Employee RBO, found in the rbexamples account. If the test browser returns an error, wait a few seconds and refresh the browser.

15 Chapter 3: Testing RBO services

Figure 5: REST test browser

2. From the Method drop-down menu, select the method that you want to invoke from your service. The entries in the drop-down menu are the HTTP verbs GET, PUT, POST, and DELETE, and they map to the RBO methods you assigned to the CRUD operations in the RBO service. 3. Enter a value for the method in the ID field. 4. If the RBO you are testing is stateful, the page contains a Use Session Id check box. Select this option to have the test page automatically copy the session ID from the result into the session ID header of subsequent requests. RBO Services that are backed by stateful RBOs use a session ID to reference the RBO state that is stored on the server in between requests.

16 Testing uQuery RBO services

5. Click Send to invoke the service and display the results in the Response pane.

Figure 6: Test result

Parent topic: Testing RBO services Testing uQuery RBO services

To test uQuery RBO services, access the testing tool, add selection parameters to the query string if appropriate, and determine if the appropriate results display.

17 Chapter 3: Testing RBO services

Procedure

1. From the U2 REST servers view, double-click the RBO to test. Use this browser to run your uQuery RBO. The following example shows the testing of a uQuery- based RBO service that is created from the EmployeeList uQuery RBO, found in the rbexamples account. If the test browser returns an error, wait a few seconds and refresh the browser.

Figure 7: uQuery test browser

The URL text box is automatically populated with the URL of your uQuery RBO. In addition to the matching records, the result set includes metadata for the query at the top of the results:

▪ items_per_page: The number of items displayed per page. You can edit the number of items displayed per page, but you cannot exceed the maximum number of items displayed per page established when the service was created. For example, if the maximum number of items displayed per page was set to 100 when the service was created, you can change the number of items to display per page to 80, but you cannot change it to 120.

▪ num_items: The total number of matching records. ▪ page_no: The page number, which can be useful to know when developing a user interface with paging support.

▪ max_pages: The number of pages in the result set.

18 Testing uQuery RBO services

2. Navigate through the pages by selecting a page number. You can also add the page number to the URL to advance to the next page of data in the result set by adding ?page_no=2 to the end of the URL. In the following example, the uQuery RBO is advanced to page 3 of the result set.

Figure 8: uQuery metadata

3. If the RBO you are testing is stateful, the page contains a Use Session Id check box. Select this option to have the test page automatically copy the session ID from the result into the session ID header of subsequent requests.

19 Chapter 3: Testing RBO services

4. If the uQuery RBO contains a select_criteria clause with “?” placeholders that can be filled in at runtime, add selection parameters to the query string by adding select_params to the end of the URL.

In the following example, the EmployeeList uQuery has a select_criteria of DEPT = “?”. By specifying a select_params value of "5" in the query string of the URL, you cause your service to return only employees in department 5.

For example: http://localhost:9191/api/svcs/rbexamples/EmployeeList? select_params=5

Figure 9: Select criteria and parameters

Note: If the uQuery service definition has the Enable selection criteria check box checked, then you can also set the select_criteria. In the following example, the select_criteria is set to DEPT = "5" (url-encoded). http://localhost:9191/api/svcs/rbexamples/EmployeeList? select_criteria=DEPT+%3D+%225%22 You can select this check box during creation of the uQuery RBO service, as described in Creating uQuery RBO services, on page 10, or by editing it.

Parent topic: Testing RBO services

20 Chapter 4: Security

User Access Control

Implement User Access Control (UAC) to define user roles and access to specific RBO services or an entire REST server. While adding UAC can help restrict access from unwanted users, implementing SSL security is also highly recommended. SSL prevents your data from being vulnerable when running RBO services over HTTP. Refer to … for additional information.

Securing REST services with UAC

Set up UAC to secure specific RBO services or an entire REST server. Once secure, users will need to provide valid credentials to access the RBO service or REST server.

Prerequisites Creating RBO services, on page 8

Procedure

1. In the U2 REST Servers view, right-click the REST server and select Define HTTP Users. 2. On the Define HTTP Users dialog box, click Add. 3. On the Add New HTTP User dialog box, Enter a user name and password for the HTTP user. The name and password entries are independent from user names and passwords stored in other configuration files in the product and can be created here. 4. Choose a role for the new user or create a new one. To create a new role, click Add Role, name the new role, and click OK. Note that a user can have multiple roles. 5. On the Add New HTTP User dialog box, click OK. 6. To add the user to the REST server, click Finish. 7. Now, define server access for the user. In the U2 REST Servers view, right-click the REST server and select Define Access Control. 8. On the Define Access Control dialog box, click Add.

21 Chapter 4: Security

9. On the Add New Access Constraint dialog box, select the server or RBO for which you want to require user authentication.

10. In the Methods section of the dialog box, define the actions the user will be able to perform on the server or specified RBO. 11. To associate user permissions with a role, select an existing role from the list or create a new role by clicking Add Role. To apply these permissions to all users, select the Any Role option. 12. On the Add New Access Constraint dialog box, click OK. 13. On the Define Access Control dialog box, click Finish. 14. Restart the REST Server. 15. To ensure the server or RBO service now requires user authentication to access it, double-click on it. If the UAC implementation was successful, a dialog box opens and asks for a user name and password. Cross Origin Request Sharing (CORS) Access

Cross-origin resource sharing (CORS) defines a way in which a browser and server can interact to determine whether or not it is safe to allow the cross-origin request. A resource makes a cross-origin HTTP request when it requests a resource from a domain or port which is different from the one which the first resource itself serves.

For example, an HTML page served from http://domain-a.com makes an src request for http://domain-b.com/image.jpg. Many web pages load resources such as CSS stylesheets, images, and scripts from separate domains. The following example shows how you would add allowed origins to the CORS policy:

22 Cross Origin Request Sharing (CORS) Access

http://example.com:9999

23 Chapter 5: Logging and debugging

There are a variety of ways to troubleshoot activity. Web DE contains web server-specific log files, which are located in the following directory: C:\U2\U2WDEnnn\U2 Web Designer \\. You can use these log files to perform debugging directly from the Web Designer. You might also review the RedBeans and Java Scheduler log files, stored in the U2 Web DE installation directory by default. These log files contain lower-level Web DE information that might be pertinent if your RBO service fails because of a Web DE-level problem not specific to Web DE REST Services. To debug a server and view the log, complete the following steps:

Procedure

1. In the U2 REST Servers view, right-click the REST server and select Start REST Server. 2. Right-click the REST server and select Turn on REST Server Debug. 3. Click Window → Show View → Other. 4. On the Show View dialog box, expand the U2 Views folder and select U2 REST Server Log. Click OK. The view is updated with the U2 REST Server Log tab with additional log entries in real time. 5. To change the amount of information written to the log file, open the logging properties file and change the log level: a. Right-click the server and select Open log properties. b. On logging.properties, set the java.util.logging.FileHandler.level property to the appropriate level and click Save. The log levels are listed from least fine logging level to finest logging level: ▪ OFF (no logging) ▪ SEVERE ▪ WARNING ▪ INFO ▪ CONFIG ▪ FINE ▪ FINER ▪ FINEST (lowest value) ▪ ALL (enables logging of all messages) 6. Restart the server to implement your changes.

24 Chapter 6: Deployment

To deploy a RESTful server and its associated RBO web service for other developers to use, create and export a compressed deployment package file. Then, import this compressed file to another deployment computer or environment by using the U2 REST deployment tool, by using the command line, or by generating a configuration file.

Prerequisites Before deploying U2 RESTful web services, ensure the deployment computer meets the following requirements: ▪ Java Runtime Environment (JRE) 1.8 must be installed on the target deployment platform. Currently, JRE 1.8 is the only version supported by U2 REST. Problems may occur if other versions are used. ▪ The JRE_HOME environment variable must point to the location of the JRE installation directory. ▪ At least 1GB of memory must be available prior to running the development environment. ▪ The memory requirements for the deployment environment depend on a variety of variables, including number of connections, tasks performed, and work load. ▪ Connection pooling licenses on the database server if connection pooling is enabled. ▪ If you are using Windows 7 or Windows 2008, you must run the Windows Command Prompt as an administrator. To do this, click Start → Accessories → Command Prompt. Right-click the Command Prompt option, and then select Run as administrator. Refer to the following:

• Importing and exporting REST servers In Web DE, you can create a deployment package and export a RESTful server to another computer or environment for other developers to use. A deployment package is a compressed file that contains script files for Windows (.bat), and UNIX/Linux (.sh) files, which allow you to deploy RESTful web services on most platforms. • Deploying a REST server using the deployment tool One of the ways you can deploy a REST server from a development computer to another deployment computer or environment is by using the deployment tool. • Deploying a REST server from the command line Another way to deploy a REST server from a development computer to a deployment environment is to use the command line. • Deploying a REST server from a configuration file REST servers can also be deployed onto a deployment environment using a generated configuration file. The configuration file is an XML file, server_name_deploy_config.xml, that contains configuration information, such as server name, port number, and connection pool information. This file also specifies values that can be changed during deployment, such as login credentials. • Deploying a RESTful service as a Windows service Use the u2restservice.exe executable program to create or remove a RESTful web service as a Windows service. This program is located in the compressed file, which was created during the export process. • Starting a RESTful service After exporting the U2 RESTful web project and running it through the deployment tool, start the RESTful web services in the deployment environment. • Stopping a RESTful service

25 Chapter 6: Deployment

You can stop any of the U2 RESTful web services running in the deployment environment. Importing and exporting REST servers

In Web DE, you can create a deployment package and export a RESTful server to another computer or environment for other developers to use. A deployment package is a compressed file that contains script files for Windows (.bat), and UNIX/Linux (.sh) files, which allow you to deploy RESTful web services on most platforms.

Exporting a REST server To create a deployment package and export a REST server: 1. In the U2 REST Servers view, ensure the REST servers you plan to export are stopped. 2. Right-click on the server (or the root node to export multiple servers) and select Export. 3. In the Export REST Servers for Deployment dialog box, select the servers you want to export, designate the name and location of the .zip compressed file, and click Finish.

Note: Some machines, such as those running Unix/Linux cannot use .zip files. In such cases, compress the files with a non-zip extraction tool, such as 7-Zip, into a GZ-type (.gz) type file.

The compressed file containing the following files: ▪ rundeploytool.bat ▪ rundeploytool.sh ▪ runrestserver.bat ▪ runrestserver.sh ▪ runtime ▪ stoprestserver.bat ▪ stoprestserver.sh ▪ u2rest ▪ U2REST_deploy.conf ▪ u2rest_workspace ▪ u2restservice.exe ▪ vcredist_x86.exe

Importing a REST server To import a deployment package to another computer or environment:

1. Locate the .zip file, right click it, and select Extract All. 2. On the Extract Compressed (Zipped) Folders dialog box, browse to the folder where you want to store the extracted files and click Extract. 3. On the U2 REST Servers view, right-click REST Servers and select Import. 4. On the Import Server and Services dialog box, browse to the u2restdeploy folder and click OK. 5. Select the server to which you want to import the compressed file.

26 Deploying a REST server using the deployment tool

6. Click Finish.

Note: You cannot change the name of the RESTful server after importing a web service. If a REST server with the same name already exists, it will be overwritten when a new web service is imported.

Parent topic: Deployment Deploying a REST server using the deployment tool

One of the ways you can deploy a REST server from a development computer to another deployment computer or environment is by using the deployment tool. Refer to the following:

1. Starting the deployment tool Begin the deployment process by starting the deployment tool. 2. Defining server connection security Next, you can define security between the client and the REST server, or bypass this step by clicking Next. 3. Defining user access On the Access Control page, you can define user access and privileges, or click Finish to exit the wizard. 4. Defining resource folder properties On the Resource Folder Properties dialog box, you can define the properties for the selected resource folder, or bypass this step by clicking Finish. Then, you can deploy the server to the appropriate computer or deployment environment.

27 Chapter 6: Deployment

Parent topic: Deployment

Starting the deployment tool

Begin the deployment process by starting the deployment tool.

Prerequisites Export a REST Server.

1. Navigate to the directory where you extracted the compressed file and locate u2restdeploy. Run the rundeploytool command, shown in the following example: rundeploytool[.sh | .bat]deployable_server_dir source_target_directory The following table describes each parameter of the syntax.

For example: rundeploytool.bat . C:\temp\myservice

Note: Do not deploy your REST servers to UniData/UniVerse home or bin installation locations.

2. On the U2 REST Service Deployment dialog box, expand the Deployable REST Servers node in the REST servers pane. Right-click the REST server you want to deploy and click Deploy.

3. On the REST Server Configuration dialog box, specify the environment for the new REST server by changing information in any of the fields, as described in the following table:

28 Defining server connection security

Field Description Server Name Contains a unique name for your REST server. Site URL Displays the valid URL for the REST server. You cannot change the information in this field. Port Number Displays the port number on which the server will listen. Root Path Displays the path to the root directory where the definitions to the web service are stored. You cannot change the information in this field. Debug On Select this option if you want to capture debugging information in the log file. Log File Name Displays the name of the log file. Connection Pooling On Select this option if you want to use connection pooling. Minimum Connection Displays the minimum number of pooled connections. The Pool Size minimum size default is 1. Maximum Connection Displays the maximum number of pooled connections. The Pool Size maximum size default is 10. Authentication Type Displays the type of HTTP-based user authentication and authorization used. This feature is used only when UAC is enabled. The default type is http-digest. 4. Click Next. The REST Server Connection Security dialog box opens. Next topic: Defining server connection security Parent topic: Deploying a REST server using the deployment tool

Defining server connection security

Next, you can define security between the client and the REST server, or bypass this step by clicking Next.

29 Chapter 6: Deployment

1. On the REST Server Connection Security dialog box, click the Specify Connection Security check box.

2. Enter the appropriate security connection details, as described in the following table:

Field name Action Key Store Browse to the full path to the key store on the REST server. Key Store Password Enter the password corresponding to the key store you defined in the Key Store field. Confirm Key Store Reenter the password corresponding to the key store you defined Password in the Key Store field. 3. Click Next to add user access controls to your project, or click Finish to exit the wizard. Next topic: Defining user access Previous topic: Starting the deployment tool Parent topic: Deploying a REST server using the deployment tool

Defining user access

On the Access Control page, you can define user access and privileges, or click Finish to exit the wizard.

Note: The user access control parameters you define here are not transferable and are typically used for testing purposes. You must define new user access parameters when you deploy RESTful services to other computers.

1. On the Define Access Control dialog box, click Add. 2. On the Add New Access Constraint dialog box, select the server or RBO for which you want to require user authentication. 3. In the Methods section of the dialog box, define the actions the user will be able to perform on the server or specified RBO. 4. To associate user permissions with a role, select an existing role from the list or create a new role by clicking Add Role. To apply these permissions to all users, select the Any Role option.

30 Defining resource folder properties

5. On the Add New Access Constraint dialog box, click OK. 6. On the Define Access Control dialog box, click Finish. 7. On the HTTP Users dialog box, click Next. The Resource Folder Properties dialog box opens. Next topic: Defining resource folder properties Previous topic: Defining server connection security Parent topic: Deploying a REST server using the deployment tool

Defining resource folder properties

On the Resource Folder Properties dialog box, you can define the properties for the selected resource folder, or bypass this step by clicking Finish. Then, you can deploy the server to the appropriate computer or deployment environment. 1. When the Resource Folder Properties dialog box opens, it displays the properties for the resource folder you defined for your REST server. You can edit the resource properties, as defined in the following table:

Field Description

Name Displays the name of the resource folder. You cannot edit this field.

U2 Data Server The name of the U2 data server to which you are connecting.

U2 Account The name of the U2 account to which you are connecting.

UniRPC Service Name The name of the UniRPC service to which you are connecting.

UniRPC Port The port number to which you are connecting.

User ID The correct user name.

Password The correct password.

SSL Select the check box if you want to use SSL.

Client Encoding The type of encoding, if any, you want to use for this web service from the Client Encoding list.

SB+ System Id The abbreviation code, or system ID, for your SB+ System. Refer to the SB+ manuals and the SB/XA manuals for more information on using systems.

SB+ User Id The user ID for the SB+ system to which you are connecting.

SB+ Password The password for the SB+ system to which you are connecting.

2. Click Test Database Connection. A pop-up window opens and informs you when the connection is successful.

31 Chapter 6: Deployment

3. Click OK to close the window. Click Finish to accept the folder properties. Focus returns to the REST Server Configuration dialog box.

Tip: If you find that you need to make additional changes to your deployment server, right- click the server name you want to change from the list of available REST servers and select the Update option.

The RESTful service is deployed on the deployment computer. Previous topic: Defining user access Parent topic: Deploying a REST server using the deployment tool Deploying a REST server from the command line

Another way to deploy a REST server from a development computer to a deployment environment is to use the command line. Refer to the following: 1. Starting the deployment tool To complete the deployment process using the command line, begin by starting the deployment tool. 2. Defining server connection security Next, you can define security between the client and the U2 REST server, or bypass this step by exiting the screen. 3. Defining resource folder properties In the next step of the deployment process, you can define the properties for the selected resource folder, or bypass this step by exiting the screen. 4. Deploying a REST server from the command line In the final step of the process, you deploy the REST server to the appropriate deployment computer or environment. Parent topic: Deployment

Starting the deployment tool

To complete the deployment process using the command line, begin by starting the deployment tool.

Prerequisites Export a REST server.

1. Navigate to the server directory where you extracted the compressed file and locate U2RESTdeploytool. Run the rundeploytool command, shown in the following example: rundeploytool[.sh | .bat] deployable_server_dir [target_server_dir]-s server_name [-t target_server] [-f config_file [-u] ] The following table describes each parameter of the syntax:

32 Starting the deployment tool

Parameter Description rundeploytool[.sh The command to start the deployment tool. Use the .bat | .bat] extension for Windows applications and the .sh extension for UNIX/Linux applications. deployable_server_dir The directory to which you extracted the compressed file. This can be the full path or a period (.) for the current directory. target_server_dir The target directory where you will deploy the U2 RESTful service. -s The name of the source server. source_server_name -t The name of the target server on which the U2 REST server will target_server_name be deployed. -f config_file (Optional) Add this parameter to input all data from the configuration file. -u The parameter used to manually change the database connection credentials and requires using the -f parameter If the -u parameter is not included in the command, they will not be editable even though they will be visible.

For example:

rundeploytool.bat . C:\temp\myservice -s testserver -t prodserver

Note: Do not deploy your REST servers to UniData/UniVerse home or bin installation locations.

2. The U2 RESTful server configuration options open in the command-line window. Select the appropriate command-line option, as described in the following table:

Command line option Description

X Exit.

A Accept. When all of the configuration options are set correctly, enter A to continue to the next set of configuration options.

1 Server name. A unique name for your REST server. The Site URL field displays the valid URL for the REST server. You cannot change the information in this field.

2 Port number. The port number on which the server will listen. Root Path. Displays the path to the root directory where the definitions to the Web service are stored. You cannot change the information in this field.

3 Debug on. Set this value to true to turn on the debug log. Set this value to false to turn the log off. By default, this value is set to false. 4 Log file name. Edit the name of the log file. By default, the name of the log file is defined by the name of the target server.

5 Connection Pooling On. Set this value to true to enable connection pooling.

33 Chapter 6: Deployment

Command line option Description

6 Minimum Connection Pool Size. Sets the minimum number of connections in the connection pool. The minimum size defaults to 1.

7 Maximum Connection Pool Size. Sets the maximum number of connections in the connection pool. The minimum size defaults to 10.

8 Authentication Type. Set the type of HTTP-based user authentication and authorization. This feature is used only when UAC is enabled. ▪ http-digest (Default) ▪ http-basic (Not recommended)

3. After making any changes to the deployment configuration options, enter A to continue. Next topic: Defining server connection security Parent topic: Deploying a REST server from the command line

Defining server connection security

Next, you can define security between the client and the U2 REST server, or bypass this step by exiting the screen. 1. The U2 RESTful connection security options open in the command line window. Select the appropriate action from the options presented in the window, as described in the following table:

Command line option Description

X Exit.

A Accept. Accepts the options as defined.

S Specify the connection security parameters.

D Do not specify connection security. Select this option if connection security is not required.

1 Enter the name of the key store.

2 Enter the password for the key store.

3 Enter the password for the key.

2. After defining connection security settings for the server, enter A to continue. Next topic: Defining resource folder properties Previous topic: Starting the deployment tool Parent topic: Deploying a REST server from the command line

Defining resource folder properties

In the next step of the deployment process, you can define the properties for the selected resource folder, or bypass this step by exiting the screen. 1. The U2 RESTful Resource folder property options open in the command line window. Select the appropriate action from the options presented in the window, as described in the following table:

34 Deploying a REST server from the command line

Command line option Description

X Exit.

A Accept. Accepts the options as defined.

T Test. Tests the database connection.

1 The name of the U2 data server to which you are connecting.

2 The name of the U2 account to which you are connecting.

3 The name of the UniRPC service to which you are connecting.

4 The port number to which you are connecting.

5 The user name.

6 The password.

7 Select the check box if you want to use SSL.

8 The type of encoding, if any, you want to use for this web service from the Client Encoding list.

9 The abbreviation code, or system ID, for your SB+ System. Refer to the SB+ manuals and the SB/XA manuals for more information on using systems.

10 The user ID for the SB+ system to which you are connecting.

11 The password for the SB+ system to which you are connecting.

2. After making any changes to the resource folder properties, enter A to continue. Next topic: Deploying a REST server from the command line Previous topic: Defining server connection security Parent topic: Deploying a REST server from the command line

Deploying a REST server from the command line

In the final step of the process, you deploy the REST server to the appropriate deployment computer or environment. The resource folder property options open in the command line window. Select the appropriate action from the options presented in the window, as described in the following table:

Option Description

X Exit.

G Generate configuration file. This option generates an XML file, server_name_deploy_config.xml, that contains all of the configuration information. Select this option to make changes to the configuration file before deploying.

C Continue. This option deploys the server to the deployment environment.

35 Chapter 6: Deployment

The REST server is deployed to the deployment computer or environment. Previous topic: Defining resource folder properties Parent topic: Deploying a REST server from the command line Deploying a REST server from a configuration file

REST servers can also be deployed onto a deployment environment using a generated configuration file. The configuration file is an XML file, server_name_deploy_config.xml, that contains configuration information, such as server name, port number, and connection pool information. This file also specifies values that can be changed during deployment, such as login credentials. Refer to the following: • Generating a configuration file You can use the U2 RESTful deployment tool to generate a configuration file, which can be used to deploy the U2 RESTful server from the development computer to the deployment environment. • Updating the configuration file using the deployment tool After you generate a configuration file, you can update it before you deploy it. The configuration file holds information such as server name, port number, connection pool information, and user login information. • Disabling security protocols from the configuration file To disable security protocols, modify the configuration file. This is a manual process, which can only be done from the configuration file. Parent topic: Deployment

Generating a configuration file

You can use the U2 RESTful deployment tool to generate a configuration file, which can be used to deploy the U2 RESTful server from the development computer to the deployment environment. Export a REST server.

1. Navigate to the server directory where you extracted the compressed file and locate u2restdeploy. Run the rundeploytool command, shown in the following example: rundeploytool[.sh | .bat] deployable_server_dir source_target_directory The following table describes each parameter of the syntax.

For example: rundeploytool.bat . C:\temp\myservice

36 Generating a configuration file

Note: Do not deploy your REST servers to UniData/UniVerse home or bin installation locations.

Running the command opens the deployment tool:

2. Expand the Deployable REST Servers node in the REST servers view. Right-click the REST server you to deploy, and select Generate configuration file. 3. Click Browse to select a different configuration file or accept the default configuration file. Click Next. The REST Server Configuration dialog box opens. You can specify the environment for the new REST server by changing any of the fields, as described in the following:

Field Description Server Name Enter a unique name for your REST server. Site URL Displays the valid URL for the REST server. You cannot change the information in this field. Port Number The port number on which the server will listen. Root Path Displays the path to the root directory where the definitions for the web services are stored. You cannot change the information in this field. Debug On Use this option if you want to capture debugging information. Log File Name The name of the log file. Connection Pooling On Use this option if you want to use connection pooling. Minimum Connection The minimum number of pooled connections. The minimum size Pool Size defaults to 1. Maximum Connection The maximum number of pooled connections. The minimum size Pool Size defaults to 10. Authentication Type The type of HTTP-based user authentication and authorization used. This feature is used only when UAC is enabled. The default type is http-digest. 4. Click Next. The REST Server Connection Security dialog box opens.

37 Chapter 6: Deployment

5. Select the Specify Connection Security check box to make changes to the security settings. Click Next to continue. 6. Click Add to add user access controls to the REST server. When you are done making changes, click Next to continue. 7. Make any necessary changes to the resource folder properties and click Finish to deploy the server to the deployment computer or environment. Parent topic: Deploying a REST server from a configuration file

Updating the configuration file using the deployment tool

After you generate a configuration file, you can update it before you deploy it. The configuration file holds information such as server name, port number, connection pool information, and user login information.

Prerequisites Generate a configuration file.

1. Open the deployment tool by running the rundeploytool command, shown in the example below: rundeploytool[.sh | .bat] deployable_server_dir source_target_directory 2. Expand the Deployable REST Servers node in the REST servers view. Right-click the REST server you to deploy, and select Update. 3. Select the appropriate target sever from the list and then click Update. 4. On the REST Server Configuration dialog box, change any of the editable fields by following the wizard prompts. 5. Click Finish to save your changes. Parent topic: Deploying a REST server from a configuration file

Disabling security protocols from the configuration file

To disable security protocols, modify the configuration file. This is a manual process, which can only be done from the configuration file.

Prerequisites Generate a configuration file.

1. Open the generated U2REST.config file in a text editor like Notepad. This file is located in the deployed REST service directory. 2. Navigate to the Security section, and modify the excludeProtocols and excludeCipherSuites parameters, as shown in the following example. In this example, all security protocols are excluded except TLSv1.2 and the SSL_RSA_WITH_NULL_SHA and SSL_RSA_WITH_RC4_128_MD5 cipher suites.

38 Deploying a RESTful service as a Windows service

In the excludecipher, zero-bit encryption null ciphers and 128-bit anonymous ciphers are excluded. 3. Save and close the file. Parent topic: Deploying a REST server from a configuration file Deploying a RESTful service as a Windows service

Use the u2restservice.exe executable program to create or remove a RESTful web service as a Windows service. This program is located in the compressed file, which was created during the export process.

Prerequisites ▪ Start the U2 REST deployment tool. ▪ On Windows 7 and Windows 2008, you must run the Windows Command Prompt as an administrator. To do this, click Start → Accessories → Command Prompt. Right-click the Command Prompt option and select Run as administrator.

Note: A Windows service can only be created on a deployed package.

The syntax for installing a REST server is as follows:

U2restservice.exe –i u2rest-server-name [-s u2rest-service-name] [-d "u2rest-service-description"]

The following table lists the options available for deploying a RESTful web service as a Windows service.

Option Description -i Installs a new RESTful web service as a Windows service. -s Lists the name of the RESTful web service. -d Provides a description of the RESTful web service. The default value is "U2 RESTful service to start and stop U2 RESTful server". The text of the description must be enclosed in quotation marks (“”). -r Removes the U2 RESTful web service.

After installing the RESTful web service, it can be started and stopped as a Windows service from the Windows Control Panel. When the service starts, it runs the runrestserver.bat u2rest-server program and waits until this .bat file exits. When the service stops, it runs the stoprestserver.bat u2rest-server program. Additional arguments can be passed to the runrestserver.bat by specifying the start parameters to the service.

39 Chapter 6: Deployment

Note: If you are creating a Windows service using the u2restservice.exe program and you get an error similar to the one shown below, you must run the vcredist_x86.exe program supplied with Web DE to ensure the Windows platform has the compatible Microsoft Visual C++ 2005 redistributable runtime environment:

Error: The application has failed to start because its side-by-side configuration is incorrect. Please see the application event log for more detail.

To remove the service, use the following syntax:

U2restservice.exe –r u2rest-server

Parent topic: Deployment Starting a RESTful service

After exporting the U2 RESTful web project and running it through the deployment tool, start the RESTful web services in the deployment environment. 1. Use the following command to start a U2 RESTful service: runrestserver[.sh | .bat] rest_server_name . [rest_server_directory] The following table describes each parameter of the syntax:

Parameter Description runrestserver[.bat | .sh] The command to run the REST server in the deployed environment. Use the .bat extension for Windows applications and the .sh extension for UNIX/Linux applications. . The current directory. You must include this parameter. rest_server_name The name of the REST server to which you are connecting. source_target_directory The target directory where the RESTful service will be deployed.

For example:

runrestserver.bat myrestserver . C:\temp\mynewservice 2. Your can check to ensure that the RESTful service is running by opening a browser window and navigating to the URL where the service is running.

Note: UNIX users may want to run the runrestserver command as a background process, using a NOHUP command when the terminal session exits. For example: nohup runrestserver.sh rest_server_name path_to_U2REST.config directory &

Parent topic: Deployment Stopping a RESTful service

You can stop any of the U2 RESTful web services running in the deployment environment. Use the following command to stop a U2 RESTful service:

40 Stopping a RESTful service stoprestserver[.sh | .bat] rest_server_name . source_target_directory The following table describes each parameter of the syntax:

Parameter Description stoprestserver[.bat | .sh] The command to stop the REST server in the deployed environment. Use the .bat extension for Windows applications and the .sh extension for UNIX/Linux applications. . The current directory. You must include this parameter. rest_server_name The name of the REST server to which you are connecting. source_target_directory The target directory where the RESTful service will be deployed.

For example: stoprestserver.bat myrestserver . C:\temp\mynewservice Parent topic: Deployment

41 Chapter 7: Troubleshooting

You might run into several common problems in this version of Web DE REST Services. You can address them with the tips that are found in this section. Server Response: 500 error

Description

When testing RBO services with Web DE REST Services, “Server Response: 500 error” might appear.

Explanation

The “Server Response: 500 error” error appears because the server encountered an unexpected condition, which prevented it from fulfilling the request that was sent to it.

Resolution

Make sure that the rgw5.ini and JavaScheduler.ini files have the correct configuration, such as the correct user ID and password. Check the RedBeans_accountname.log and the JavaScheduler.log file in the Web DE installation directory. If the rgw5.ini file was not configured after installation, a log entry is written that indicates that an invalid user name or password is being used.

If you configured the rgw5.ini and JavaScheduler.ini files and still get a “Server Response: 500” error from the test page, check the u2restserver.log file from the C:/U2/ U2WDEnnn/U2 Web Designer/u2rest/u2restserver directory, where u2restserver is the name of the U2 Web DE REST server that you created. You might need to increase the level of logging to see more detail. For help with increasing the logging level, see Logging and debugging, on page 24 or see Administrator’s Guide.