Rocket U2 Web Development Environment

Transcription

1 Rocket U2 Web Development Environment Getting Started with REST Services Version 5.0 July 2017 WDE-530-RES-IM-01

2 Notices Edition Publication date: July 2017 Book number: WDE-530-RES-IM-01 Product version: Version 5.0 Copyright Rocket Software, Inc. or its affiliates All Rights Reserved. Trademarks Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks go to: 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

3 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: Rocket Global Headquarters 77 4th Avenue, Suite 100 Waltham, MA 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 Australia Belgium Canada China France Germany Italy Japan Netherlands New Zealand South Africa United Kingdom 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 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 to support@rocketsoftware.com. 3

4 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 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 User Access Control...21 Securing REST services with UAC...21 Cross Origin Request Sharing (CORS) Access Chapter 5: Logging and debugging Chapter 6: Deployment Importing and exporting REST servers Deploying a REST server using the deployment tool...27 Starting the deployment tool Defining server connection security...29 Defining user access Defining resource folder properties Deploying a REST server from the command line Starting the deployment tool Defining server connection security...34 Defining resource folder properties Deploying a REST server from the command line Deploying a REST server from a configuration file Generating a configuration file...36 Updating the configuration file using the deployment tool Disabling security protocols from the configuration file Deploying a RESTful service as a Windows service...39 Starting a RESTful service...40 Stopping a RESTful service Chapter 7: Troubleshooting Server Response: 500 error

5 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

6 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 RBC@rocketsoftware.com. 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

7 Starting, stopping, and restarting REST servers Prerequisites Using RBO RESTful web services, on page 6 Procedure In the U2 REST Servers view, right-click the REST Servers node, and select New REST Server. On the first page of the New REST Server wizard, enter a server name and accept the defaults for the other fields. Click Next. 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 docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html for Windows and for UNIX. Note that these URLs might change over time b. Enter the relevant passwords. Click Finish. 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

8 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 4. From the U2 REST Servers pane of the Web Designer, right-click the server and select Stop REST Server. Right-click the server that you want to upgrade, and select Upgrade Server. 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. 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 From the U2 REST Servers pane of the Web Designer, right-click REST Servers and select Upgrade Servers. 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. 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

9 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 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. 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. 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. Optional: If you are using SSL security, select the Use SSL check box and enter the applicable trust store information. Click Next. Click Finish. On the first page of the RBO Service Details wizard, complete the RBO service name and Account name fields, and click Next. On the RBO Service Properties page, select the properties that you want to use to define the service properties. 9

10 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. 1 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. 1 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 10 In the U2 Resource view, select a uquery RBO and drag it to the REST server in the U2 REST Servers view. Every server must have a resource folder that stores the services for a specific account.

11 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. 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. Optional: If you are using SSL security, select the Use SSL check box and enter the applicable trust store information. Click Next. Click Finish. On the first page of the RBO Service Details wizard, complete the RBO service name and Account name fields, and click Next. On the RBO Service Query Fields page, select the properties that you want to use to define the service parameters. 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 2: Field depth 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

12 Chapter 2: Enabling Web DE REST Services 1 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 From the U2 REST Servers view, right-click a service and select Edit. 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: 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. When you are finished making changes, click Save

13 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 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 RPCstyle 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

14 Chapter 3: Testing RBO services Figure 3: RPC test browser From the Method drop-down menu, select the method to invoke from the service. 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

15 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. 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 RESTstyle 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

16 Chapter 3: Testing RBO services Figure 5: REST test browser From the Method drop-down menu, select the method that you want to invoke from your service. 4. 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. Enter a value for the method in the ID field. 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

17 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

18 Chapter 3: Testing RBO services Procedure 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 uquerybased 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. 18 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.

19 Testing uquery RBO services 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 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

20 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: 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). 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

21 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 In the U2 REST Servers view, right-click the REST server and select Define HTTP Users. On the Define HTTP Users dialog box, click Add. 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. 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. On the Add New HTTP User dialog box, click OK. To add the user to the REST server, click Finish. Now, define server access for the user. In the U2 REST Servers view, right-click the REST server and select Define Access Control. On the Define Access Control dialog box, click Add. 21

22 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. 1 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. 1 On the Add New Access Constraint dialog box, click OK. 1 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 makes an <img> src request for 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: <bean id="cors-filter" class="org.apache.cxf.rs.security.cors. CrossOriginResourceSharingFilter"> <property name="alloworigins"> <list value-type="java.lang.string"> 22

23 Cross Origin Request Sharing (CORS) Access <value> </list> </property> </bean> 23

24 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 \<servername>\<servername>. 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 In the U2 REST Servers view, right-click the REST server and select Start REST Server. Right-click the REST server and select Turn on REST Server Debug. Click Window Show View Other. 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. 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) Restart the server to implement your changes.

25 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) 8 must be installed on the target deployment platform. Currently, JRE 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

26 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: In the U2 REST Servers view, ensure the REST servers you plan to export are stopped. Right-click on the server (or the root node to export multiple servers) and select Export. 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: Locate the.zip file, right click it, and select Extract All. On the Extract Compressed (Zipped) Folders dialog box, browse to the folder where you want to store the extracted files and click Extract. On the U2 REST Servers view, right-click REST Servers and select Import. On the Import Server and Services dialog box, browse to the u2restdeploy folder and click OK. Select the server to which you want to import the compressed file.

27 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: 4. Starting the deployment tool Begin the deployment process by starting 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. Defining user access On the Access Control page, you can define user access and privileges, or click Finish to exit the wizard. 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

28 Chapter 6: Deployment Parent topic: Deployment Starting the deployment tool Begin the deployment process by starting the deployment tool. Prerequisites Export a REST Server. 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. Parameter Description rundeploytool[.sh.bat] The command to start the deployment tool. Use the.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. source_target_directory The directory where the deployable server will be located. For example: rundeploytool.bat. C:\temp\myservice Note: Do not deploy your REST servers to UniData/UniVerse home or bin installation locations. 28 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. 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:

29 Defining server connection security 4. 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 Pool Size Displays the minimum number of pooled connections. The minimum size default is Maximum Connection Pool Size Displays the maximum number of pooled connections. The 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. 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

30 Chapter 6: Deployment On the REST Server Connection Security dialog box, click the Specify Connection Security check box. 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 Password Reenter the password corresponding to the key store you defined in the Key Store field. 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 On the Define Access Control dialog box, click Add. On the Add New Access Constraint dialog box, select the server or RBO for which you want to require user authentication. In the Methods section of the dialog box, define the actions the user will be able to perform on the server or specified RBO. 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.

31 Defining resource folder properties On the Add New Access Constraint dialog box, click OK. On the Define Access Control dialog box, click Finish. 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. 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. Click Test Database Connection. A pop-up window opens and informs you when the connection is successful. 31

32 Chapter 6: Deployment 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, rightclick 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: 4. Starting the deployment tool To complete the deployment process using the command line, begin by starting the deployment tool. 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. 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. 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. 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

33 Starting the deployment tool Parameter Description rundeploytool[.sh.bat] The command to start the deployment tool. Use the.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 source_server_name The name of the source server. -t target_server_name The name of the target server on which the U2 REST server will 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. 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

34 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 7 Maximum Connection Pool Size. Sets the maximum number of connections in the connection pool. The minimum size defaults to 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) 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. 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. 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. 34 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:

35 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. 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

36 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. 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. Parameter Description rundeploytool[.sh.bat] The command to start the deployment tool. Use the.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. source_target_directory The directory where the deployable U2 RESTful web server will be located. For example: rundeploytool.bat. C:\temp\myservice 36

37 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: Expand the Deployable REST Servers node in the REST servers view. Right-click the REST server you to deploy, and select Generate configuration file. 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: 4. 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 Pool Size The minimum number of pooled connections. The minimum size defaults to Maximum Connection Pool Size The maximum number of pooled connections. The minimum 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. Click Next. The REST Server Connection Security dialog box opens. 37