Version 5.2.1 Environmentdocs.rocketsoftware.com/nxt/gateway.dll/RKBnew20... · Environment...

Rocket U2 Web DevelopmentEnvironment

Getting Started with REST Services

Version 5.2.1

October 2015WDE-521-RES-IM-01

2

NoticesEdition

Publication date: October 2015Book number: WDE-521-RES-IM-01Product version: Version 5.2.1

Copyright© Rocket Software, Inc. or its affiliates 1996-2015. All Rights Reserved.

Trademarks

Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks goto: www.rocketsoftware.com/about/legal. All other products or services mentioned in this documentmay 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 ofindividuals, companies, brands, and products. All of these names are fictitious and any similarity tothe 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 withthe terms of such license.

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

http://www.rocketsoftware.com/about/legal

3

Corporate informationRocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks,and compliance; database servers and tools; business information and analytics; and applicationdevelopment, integration, and modernization.

Website: www.rocketsoftware.com

Rocket Global Headquarters77 4th Avenue, Suite 100Waltham, MA 02451-1468USA

To contact Rocket Software by telephone for any reason, including obtaining pre-sales informationand technical support, use one of the following telephone numbers.

Country Toll-free telephone number

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

Contacting Technical Support

The Rocket Customer Portal is the primary method of obtaining support. If you have currentsupport and maintenance agreements with Rocket Software, you can access the Rocket CustomerPortal and report a problem, download an update, or find answers to in the U2 Knowledgebase.To log in to the Rocket Customer Portal or to request a Rocket Customer Portal account, go towww.rocketsoftware.com/support.

In addition to using the Rocket Customer Portal to obtain support, you can send an email [email protected] or use one of the following telephone numbers.

Country Telephone number

North America +1 800 729 3553United Kingdom/France +44 (0) 800 773 771 or +44 (0) 20 8867 3691Europe/Africa +44 (0) 20 8867 3692Australia +1 800 707 703 or +61 (0) 29412 5450New Zealand +0800 505 515

http://www.rocketsoftware.com

http://www.rocketsoftware.com/support

mailto:[email protected]

4

Contents

Notices................................................................................................................................................................................... 2

Corporate information......................................................................................................................................................... 3

Chapter 1: Rocket U2 Web Development Environment overview..................................................................................... 5Introduction...............................................................................................................................................................5

Chapter 2: Enabling Web DE REST Services....................................................................................................................... 6Opening the RESTful RBO perspective................................................................................................................... 6Creating a U2 REST server....................................................................................................................................... 7

Starting or stopping a U2 REST server........................................................................................................8Upgrading a U2 REST server....................................................................................................................................8

Upgrading a single U2 REST server.............................................................................................................9Upgrading all U2 REST servers.................................................................................................................... 9

Creating RBO services.............................................................................................................................................. 9Creating a stateful or stateless RBO service...............................................................................................9Creating a uQuery RBO service................................................................................................................. 13Editing RBO services...................................................................................................................................15

Chapter 3: Testing RBO services........................................................................................................................................17Testing a service with RPC.....................................................................................................................................17Testing a service with REST...................................................................................................................................19Testing a uQuery RBO service............................................................................................................................... 22

Chapter 4: User Access Control......................................................................................................................................... 26Securing Web DE REST Services with UAC........................................................................................................... 26

Chapter 5: Logging and debugging................................................................................................................................... 27

Chapter 6: Troubleshooting............................................................................................................................................... 28Server Response: 500 error....................................................................................................................................28

5

Chapter 1: Rocket U2 Web DevelopmentEnvironment overview

Rocket U2 Web Development Environment (Web DE) is an application development toolkit for buildinginteractive client/server applications for deployment on the World Wide Web or on a corporateintranet.

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

6

Chapter 2: Enabling Web DE REST ServicesWeb DE REST Services features are accessed from the RESTful RBO perspective in Web Designer. Oncethe perspective is open, you can create U2 REST servers and RBO services, and then test the servicesand perform debugging tasks, if necessary.

Before enabling and using Web DE REST Services, you must perform the following tasks:

▪ Install the UniVerse or UniData database.

▪ Install U2 Web DE.

▪ Install Web Designer.

▪ Request an authorization code for Web DE REST Services by sending an email [email protected], and then license the RedBack Object Server with the authorizationcode supplied by Rocket.

For help with these tasks, see the UniVerse or UniData documentation, Web DE Installation andConfiguration, and Administrator’s Guide.

Opening the RESTful RBO perspectiveWeb DE REST Services features are hidden by default in Web DE. Once Web DE is authorized for Web DEREST Services, you can access a previously unavailable perspective in Web Designer to make the newfeatures visible.

From the Web Designer toolbar, select Window > Open Perspective > RESTful RBO Perspective.If you do not see the perspective from the Open Perspective menu, click Other and select the Showall check box. The RESTful RBO Perspective option appears. Select it and click OK. If a ConfirmEnablement dialog box appears, click OK.

The Web Designer perspective changes to the RESTful RBO perspective. This perspective is the mainview for Web DE REST Services. It is divided into four panes where various views are displayed.

Figure 1: RBO Enabled U2 REST Servers pane

mailto:[email protected]

Creating a U2 REST server

7

The upper-left pane displays the U2 Resource view, which shows accounts, files, and all resources ofthe account on the connected database server.

The lower-left pane displays the RBO Enabled U2 REST Servers view. You can create, edit, start, andstop servers from this view.

The upper-right pane is an editor view for performing tasks such as editing the properties andmethods of an RBO.

The lower-right pane contains different views, mainly properties and other views depending on theprocess or action taking place.

Creating a U2 REST serverYou must create a U2 REST server in order to deploy RESTful RBOs. A wizard guides you through theprocess of creating a REST server.

Prerequisites

Opening the RESTful RBO perspective, on page 6

Procedure

1. From the U2 REST Servers pane of the Web Designer, right-click REST Servers and select NewREST Server.

2. On the first page of the New REST Server wizard, enter a server name and accept the defaults forthe other fields. Click Next.

Note: The preview release of Web DE REST Services supports U2 Data Services and U2Subroutine Services in addition to the new U2 Web DE REST Services. The pooling parameterson the first wizard page apply only to U2 Data Services and U2 Subroutine Services, andnot to Web DE REST Services. Web DE REST Services uses the standard Web DE connectionpooling mechanisms that are configured through the rgw5.ini and JavaScheduler.iniconfiguration files. For information about U2 Data Services and U2 Subroutine Services, seethe U2 RESTful Web Services Help manual available at http://docs.rocketsoftware.com. ExpandRocket U2 > DBTools to get the latest version.

3. Optional: On the second page of the wizard, select the Use SSL check box only if you want toperform actions outside the scope of Web DE REST Services.

Important: It is strongly recommended that you enable SSL for all Web DE REST servers. Ifyou do not use SSL, your data is vulnerable to spying whenever you make calls to your RBOservices over HTTP. You can further enhance your security by following the steps in SecuringWeb DE REST Services with UAC, on page 26, 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, orclick Browse to navigate to it.

Note: You can use tools such as Rocket Software U2 Extensible Administration Toolto create a certificate, and you can use the Oracle keytool to import the certificateinto a keystore. To use U2 Extensible Administration Tool to generate a certificate,follow the instructions in the UniData Security Features manual or the UniVerse SecurityFeatures manual. The Oracle keytool utility is installed with Oracle JDK. For moreinformation about keytool, see the Oracle documentation on keytool, currently at http://

http://docs.rocketsoftware.com

http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html

Chapter 2: Enabling Web DE REST Services

8

docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html. Note that theURL might change over time.

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

Figure 2: New REST server

Starting or stopping a U2 REST server

You can start and stop REST servers at any time. When the REST server is running, you can onlyperform some actions such as using the REST Server Debug log, To start or stop a REST server, followthese steps.

▪ To start a REST server, right-click the server in the RBO Enabled U2 REST Servers pane, and selectStart REST server.

▪ To stop a REST server, right-click the server in the RBO Enabled U2 REST Servers pane, and selectStop REST Server.

Upgrading a U2 REST serverWhen a U2 REST server is first created, a number of class files and other server-side artifacts arecreated for the RESTful server. When you upgrade to a new version of Web DE, you must also upgradeyour 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 U2 REST server, on page 9

▪ Upgrading all U2 REST servers, on page 9

http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html

Upgrading a single U2 REST server

9

Upgrading a single U2 REST server

Prerequisites▪ Creating a U2 REST server, on page 7

Procedure

1. From the U2 REST Servers pane of the Web Designer, right-click the server and select Stop RESTServer.

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 appears when the upgrade is complete.

Upgrading all U2 REST servers

Prerequisites▪ Creating a U2 REST server, on page 7

Note: Before you can upgrade all of the U2 REST servers, you must right-click each server andselect Stop Server to disconnect them.

Procedure

1. From the U2 REST Servers pane of the Web Designer, right-click REST Servers and selectUpgrade Servers.

2. Optional: In the U2 RESTful Web Services Developer dialog, click Back up if you want to create abackup zip file to be made of the existing servers in the location specified.

3. Click Upgrade.A success message appears when the upgrade is complete.

Creating RBO servicesYou can create RBO services out of three types of RBOs: uQuery, stateful, and stateless RBOs.Additionally, a REST-style API is available for your RBO services along with the default RPC-style API.

Creating a stateful or stateless RBO service

Create an RBO service for a stateful or stateless RBO by following the steps in this section.

Prerequisites

Creating a U2 REST server, on page 7


10

About this task

By creating an RBO service from a stateful RBO, you can store runtime data that is related to your RBOon the U2 server. With a stateful RBO service, you can also take advantage of the optimistic lockingfunctionality 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 RBOsare useful in Web DE, in general. Stateless RBOs place less load on the U2 server and are thereforefaster. 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 treatsthe 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, anRPC-style API might be more appropriate.

Creating a stateful or stateless RBO service

11

Procedure

1. From the U2 Resource view in the Web Designer, select a stateful or stateless RBO, and drag it tothe REST server in the RBO Enabled U2 REST Servers pane.If a resource folder was not already created, the New Resource Folder dialog box appears.

Figure 3: New Resource Folder

Every REST server must have a resource folder to contain the defined services for a specificaccount.

If a folder exists, proceed to step 6. If not, continue to the next step.2. In the New Resource Folder window, in the Name field, enter a name for the resource folder.

Accept the defaults in the other fields. Click Next.

Note: The UniRPC Service Name, UniRPC Port, User ID, Login Password, SSL, Client Encoding,and SB+ fields on this wizard page apply only to U2 Data Services and U2 Subroutine Services.Web DE REST Services uses the standard Web DE connection pooling mechanisms that areconfigured through the rgw5.ini and JavaScheduler.ini configuration files. Forinformation about U2 Data Services and U2 Subroutine Services, see the U2 RESTful WebServices Help manual available at http://docs.rocketsoftware.com. Expand Rocket U2 >DBTools to get the latest version.

3. Optional: Select the Use SSL check box only if you want to perform actions outside the scope ofWeb DE REST Services, and enter the applicable trust store information. Click Next.

4. Click Test Database Connection to make sure that the database connection is valid and active.5. Click Finish.

http://docs.rocketsoftware.com


12

If the REST Server is running, a message appears saying that the REST Server must be stoppedbefore proceeding. Click Yes.

The resource folder is created, and the RBO Service Details wizard opens.6. Enter information as prompted on the first page of the RBO Service Details wizard, and then click

Next.7. On the RBO Service Properties 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-downmenu.

▪ Ctrl or Shift + click to select multiple rows, right-click and select a depth option from theChange depth context menu.

▪ Ctrl or Shift + click to select multiple rows, and below the table, select a depth option from theChange depth of selected items to: drop-down menu.

Note: Depending on how the original Web DE RBO was created, incorrect depths mightappear in the Depth column by default. You must correctly specify Single-valued,Multivalued, or Multi-subvalued for each property.

Figure 4: Field depth

9. Click Next.10. On the RBO Service Methods page, select the RBO methods to expose in the service. Click Next.11. If you want to use the REST-style API, select the Support REST-style API check box and proceed

to the next step.The REST API CRUD Methods section appears when you select this check box.

To use the RPC-style API, leave the check box cleared and click Finish.12. From the REST API CRUD Methods section, select the RBO methods that will be used in the create,

read, update, and delete operations.13. From the Key field drop-down menu, specify the RBO property that represents the key field.14. Click Finish to create the RBO service.

Results

The RBO service appears under the WEBDE RBO Resources node in the RBO Enabled U2 REST Serverspane. The following figure shows the Customers RBO service.

Creating a uQuery RBO service

13

Figure 5: New service result

Next step

You can now perform the following tasks:

▪ Edit your RBO. See Editing RBO services, on page 15.

▪ Test your RBO service. See Testing RBO services, on page 17.

▪ Enhance the security of your RBO service. See Securing Web DE REST Services with UAC, on page26.

Creating a uQuery RBO service

uQuery RBOs provide query capabilities on a U2 file and return matching records in a result setstructure. To create a uQuery RBO service, follow the steps in this section.

Prerequisites

Creating a U2 REST server, on page 7

Procedure

1. From the U2 Resource view in the Web Designer, select a uQuery RBO and drag it to the RESTserver in the RBO Enabled U2 REST Servers pane.If a resource folder was not already created, the New Resource Folder dialog box appears. EveryREST server must have a resource folder to contain the defined services for a specific account.

If a folder exists, proceed to the next step. If not, see steps 2-5 in Creating a stateful or statelessRBO service, on page 9.

2. Enter information as prompted on the first page of the RBO Service Details wizard, and then clickNext.

3. On the RBO Service Query Fields page, select the properties that you want to use to define theservice parameters.


14

4. 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-downmenu.

▪ Ctrl or Shift + click to select multiple rows, right-click and select a depth option from theChange depth context menu.

▪ Ctrl or Shift + click to select multiple rows, and below the table, select a depth option from theChange depth of selected items to: drop-down menu.

Note: Depending on how the original Web DE RBO was created, incorrect depths mightappear in the Depth column by default. You must correctly specify Single-valued,Multivalued, or Multi-subvalued for each property.

Figure 6: Field depth

5. If you want to use the select_criteria property with your RBO, select the Enable selectioncriteria check box.You must select this check box if you want your uQuery service to be able to change itsselect_criteria property at runtime.

6. Click Finish to create the uQuery RBO service.

Results

The RBO service appears under the WEBDE RBO Resources node in the RBO Enabled U2 REST Serverspane. The following figure shows the EmployeeList RBO service.

Editing RBO services

15

Figure 7: New service result

Next step

You can now perform the following tasks:

▪ Edit your RBO. See Editing RBO services, on page 15.

▪ Test your RBO service. See Testing RBO services, on page 17.

▪ Enhance the security of your RBO service. See Securing Web DE REST Services with UAC, on page26.

Editing RBO services

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

Procedure

1. From the RBO Enabled U2 REST Servers pane, right-click a service that you have created andselect Edit.

2. In the dialog box that appears, enter your credentials to the U2 Web DE repository.Access to the U2 Web DE repository allows the editor to retrieve the current definition of the RBOthat is backing the service being edited. If you do not enter your credentials (by hitting cancelat the dialog), you can still work with the service as it is currently defined. However, you will notbe shown the full set of RBO properties and methods for the backing RBO. A dialog will appearindicating this before the editor is ultimately opened.After you enter your credentials or click cancel, the Editor appears as shown in the followingfigure.


16

3. Click the relevant tab for the part of the service that you want to edit and make changes. You canmake changes in the same way you did during the creation, as described in the previous sections.The available tabs are dependent on the type of RBO service that you are editing.When editing a uQuery-based service, a Fields tab is available.

4. When are you finished making changes, click the Save icon from the icon toolbar.

17

Chapter 3: Testing RBO servicesYou can test the RBO services that you create with Web DE REST Services by opening a test browserfrom within the Web Designer. The test browser allows you to verify that your RBO service is workingcorrectly before you begin writing your mobile application.

The test browser and methods for testing your RBO service vary slightly depending on whether youare testing a stateless RBO service, a stateful RBO service, or a uQuery RBO service. Testing of statelessand stateful RBO services also varies depending on whether the service was created with a REST-styleAPI or an RPC-style API.

▪ To test a stateless or stateful RBO service with an RPC-style API, see Testing a service with RPC, onpage 17.

▪ To test a stateless or stateful RBO service with a REST-style API, see Testing a service with REST, onpage 19.

▪ To test a uQuery RBO service, see Testing a uQuery RBO service, on page 22.

Testing a service with RPCTest the RBO service with RPC by following the steps in this section.

Prerequisites

Creating a stateful or stateless RBO service, on page 9

Chapter 3: Testing RBO services

18

Procedure

1. From the RBO Enabled U2 REST servers pane, double-click the RBO that you want to test.

The RBO Service Test Browser appears in Web Designer. If the test browser returns an error, waita few seconds and then refresh the browser.

Tip: Double-click the RBO Service Test Browser tab to maximize it.

Figure 8: RPC test browser

Use this browser to run your RBO service. This example shows the testing of an RPC-style RBOservice that is created from the Employee RBO found in the rbexamples account.

2. From the Method drop-down menu, select the method that you want to invoke from your service.3. Enter values that are required for your method call in the fields on the left, and then click Submit.

Note: Entering values in these fields causes the Payload text area to change appropriately.You also can manually edit the payload.

4. Add multivalued and multi-subvalued information for the fields as needed.

If a field was defined as multivalued, a set of edit controls appears to the right of that field asshown beside the Interests field in the previous figure. If a field was defined as multi-subvalued,additional controls appear. Use these controls to insert values above or below the correspondingvalue, or to delete the value.

Testing a service with REST

19

5. If the RBO you are testing is stateful, the test page has a Use Session Id check box. Select the UseSession Id check box to have the test page automatically copy the session ID from the result backinto the service URL.

RBO Services that are backed by stateful RBOs use a session ID to reference the RBO state that isstored on the server in between requests.

6. After you have entered all pertinent values, click Submit.

The service is invoked, and the results are displayed in the Result text area, as shown in thefollowing figure.

Figure 9: Test result

Testing a service with RESTTest the RBO service with REST by following the steps in this section.

Prerequisites



20

Procedure



Figure 10: REST test browser

Use this browser to run your RBO service. This example shows the testing of an REST-style RBOservice created from the Customers RBO found in the rbexamples account.

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 theymap to the RBO methods you assigned to the CRUD operations in the RBO Service.

3. Enter values that are required for your method call in the fields on the left, and then click Submit.

Note: Entering values in these fields causes the Payload text area to change appropriately.You also can manually edit the payload.

4. Add multivalued and multi-subvalued information for the fields as needed.

Testing a service with REST

21

If a field was defined as multivalued, a set of edit controls appears to the right of that field asshown beside the Orders field in the previous figure. If a field was defined as multi-subvalued,additional controls appear. Use these controls to insert values above or below the correspondingvalue, or to delete the value.



6. After you have entered all pertinent values, click Submit.

The service is invoked, and the results are displayed in the Result text area, as shown in thefollowing figure.

Figure 11: Test result


22

Testing a uQuery RBO serviceTest the uQuery RBO service by following the steps in this section.

Prerequisites


Procedure



Figure 12: uQuery test browser

Use this browser to run your RBO service. This example shows the testing of a uQuery-based RBOservice that is created from the EmployeeList uQuery RBO found in the rbexamples account.

The URL text box is automatically populated with the URL of your uQuery RBO.

Testing a uQuery RBO service

23

2. Click Submit.

Figure 13: uQuery test results

In addition to the matching records, the result set includes additional metadata for the query atthe bottom of the results:

▪ max_pages: number of pages in the result set.

▪ jsessionid: session ID that represents the uQuery instance in the U2 Web DE Object Serverholding the cached results.

▪ page_no: page number, which can be useful to know when developing a user interface withpaging support.

▪ items_per_page: number of items per page.

▪ num_items: total number of matching records.


24

3. Navigate through the pages by clicking Next Page, Previous Page, or 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 setby adding ?page_no=2 to the end of the URL.

In the following example, the uQuery instance is advanced to page 2 of the result set.

Figure 14: uQuery metadata



Testing a uQuery RBO service

25

5. If the uQuery contains a select_criteria clause with “?” placeholders that can be filled in atruntime, add selection parameters to the query string by adding select_params to the end ofthe URL.

In the following example, the EmployeeList uQuery has a select_criteria of DEPT = “?”and select_params of 5. By entering a select_params of 5, you cause your service toreturn only employees in department 5.

Figure 15: Select criteria and parameters

Note: The select_criteria property can only be changed if the uQuery service definitionhas the Enable selection criteria check box selected. You can select this check box duringcreation of the uQuery service as described in Creating a uQuery RBO service, on page 13 or byediting it.

You can add multiple selection parameters by using %FD, the URL-encoded value of ASCIIcharacter 253, as a delimiter. If you are using a system with UniVerse NLS or UniData I18Nenabled, and where value marks have been mapped to a value other than the ASCII character253, use the URL-encoded value of the value mark character used by the system.

26

Chapter 4: User Access ControlUser Access Control (UAC) provides security for your RBO services by limiting different users todifferent access levels and assigning specific roles. This security is greatly compromised, however, ifyou do not use SSL. Using SSL prevents your data from being vulnerable to spying when you makecalls on your RBO services over HTTP. It is therefore advisable to use both SSL and UAC.

For more information about how to configure SSL, follow the steps in Creating a U2 REST server, onpage 7.

Securing Web DE REST Services with UACSecuring RBO services is important because otherwise they are open to anyone with access to the WebDE REST server. Follow the steps in this section to set up UAC.

Prerequisites

Creating RBO services, on page 9

Procedure

1. From the RBO Enabled U2 REST Servers pane, right-click the REST server and select Define HTTPUsers.

2. On the Define HTTP Users dialog box, click Add.3. Enter a user name and password for the HTTP user.

These entries are independent from user names and passwords stored in other configuration filesin the product; they can be created here.

4. Click Add Role to create a role, for example, “user.” Click OK.The user is added to the role.

5. Optional: Continue adding roles for the user.The roles defined here are kept when you open this dialog box again. You can add multiple rolesto a user.

6. On the Add New HTTP User dialog box, click OK.7. Optional: On the Define HTTP Users dialog box, continue adding users.

You can also edit or delete a user from this dialog box.8. Click Finish to add the user to the Web DE REST server.9. To secure your Web DE REST server with the new role that you defined, from the RBO Enabled U2

REST Servers pane, right-click the REST server and select Define Access Control.10. On the Define Access Control dialog box, click Add.11. From the Add New Access Constraint dialog box, select the Web DE REST server to secure the

entire site, and click Check All to secure all HTTP verbs.

You can also select individual RBO services to secure rather than the entire site.12. Select the role that you defined in step 4, and then click OK.13. On the Define Access Control dialog box, click Finish.14. Restart your U2 Web DE REST Server.15. Test that your site now requires authentication by double-clicking one of the RBO services that

you created.An authentication dialog box where you can log into the service is displayed.

27

Chapter 5: Logging and debuggingWeb DE REST Services has web server-specific log files, which are located in the following directory: C:\U2\U2WDEnnn\U2 Web Designer\<servername>\<servername>. You can use these logfiles to perform debugging directly from the Web Designer.

Prerequisites

Creating RBO services, on page 9

Procedure

1. In Web Designer, from the RBO Enabled U2 REST Servers pane, right-click the REST server andselect Start REST Server if it is not already started.

2. Right-click the REST server and select Turn on REST Server Debug.3. From the toolbar, select Window > Show View > Other.

The Show View dialog box appears.4. 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.

a. To increase the amount of information that is written to the log file, edit thelogging.properties file for the server. You can edit this file directly in Web Designer byright-clicking the server and selecting Open log properties, or opening it from the followinglocation:C:\U2\U2WDEnnn\U2 Web Designer\u2rest\<servername>\WebContent\WEB-INF\logging.properties

b. Increase the level of logging by setting the java.util.logging.FileHandler.levelproperty to INFO, for example, java.util.logging.FileHandler.level=INFO.

c. Increase the level of logging further by setting the .level property and thejava.util.loging.FileHandler.level property to FINE.Setting the logging level to FINE often yields information critical to debugging.

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)

d. Save the logging.properties file, and restart the REST server.

Occasionally, it is also useful to check the RedBeans and Java Scheduler log files, found in the U2 WebDE installation directory by default. These log files contain lower-level Web DE information that mightbe pertinent if your RBO service fails because of a Web DE-level problem not specific to Web DE RESTServices.

28

Chapter 6: TroubleshootingYou might run into several common problems in this version of Web DE REST Services. You canaddress 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” mightappear.

Explanation

The “Server Response: 500 error” error appears because the server encountered anunexpected 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 theJavaScheduler.log file in the Web DE installation directory. If the rgw5.ini file was notconfigured after installation, a log entry is written that indicates that an invalid user name orpassword is being used.

If you configured the rgw5.ini and JavaScheduler.ini files and still get a “ServerResponse: 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 thename of the U2 Web DE REST server that you created. You might need to increase the level of loggingto see more detail. For help with increasing the logging level, see Logging and debugging, on page 27or see Administrator’s Guide.

Version 5.2.1 Environmentdocs.rocketsoftware.com/nxt/gateway.dll/RKBnew20... · Environment...

Documents

Transcript of Version 5.2.1 Environmentdocs.rocketsoftware.com/nxt/gateway.dll/RKBnew20... · Environment...