ibm forms v8 · built with web experience factory lab exercise. ... feb includes enterprise level...

IBM Software

IBM Forms V8.0Using Forms Experience Builder - REST API in applications built with Web Experience Factory

Lab Exercise

Catalog Number

© Copyright IBM Corporation, 2012

US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

IBM Software

Contents

OVERVIEW............................................................................................................................................................4INTRODUCTION..................................................................................................................................................................4PREREQUISITES (ALREADY COMPLETED)....................................................................................................................6DURATION...........................................................................................................................................................................7

USING FORMS EXPERIENCE BUILDER REST API IN APPLICATIONS BUILT WITH WEB EXPERIENCE FACTORY..............................................................................................................................................................81.1 GETTING STARTED............................................................................................................................................................81.2 IMPORTING THE EXPENSE REPORT APPLICATION.....................................................................................................91.3 EXPLORING THE REST API.............................................................................................................................................12

1.4 CREATING THE REST API WEB APPLICATION USING WEB EXPERIENCE FACTORY...........................................221.5 OPTIONAL – SOLUTION IMPORT INSTRUCTIONS FOR WEF MODELS.....................................................................711.6 SUMMARY.........................................................................................................................................................................73

ADDITIONAL RESOURCES..............................................................................................................................................73

Contents

IBM Software

OverviewThe objective of this lab is to provide you with an overview of Forms Experience Builder 8.0 (FEB) REST based API (RESTful services) and to demonstrate building a simple application using this REST API.

Representational State Transfer (REST) is an architecture style for designing network applications. Although it is just a style, in practice almost all implementations use HTTP requests to access data. By REST API we really mean the implementation of RESTful services in the context of Forms Experience Builder.

The application using the API will be created with the IBM Web Experience Factory (WEF) designer (an Eclipse based software development tool) and this task will be accomplished without writing any programming code.

Some of the tasks that you will perform in this lab include:

◦ Reviewing Forms Experience Builder (FEB)

◦ Reviewing the FEB REST API

◦ Using cURL to work with the API

◦ Covering basics of IBM Web Experience Factory (WEF)

◦ Working with WEF service provider and service consumer models

◦ Working with WEF Builders

◦ Publishing and deploying WEF applications (portlets) to application (portal) servers

Introduction

As you have already learned from previous labs, Forms Experience Builder makes creating forms easier than before by dramatically reducing the time and effort required to deliver compelling, interactive applications. The simple web-based user interface allows any Web designer to quickly assemble a series of application screens, capture data into a relational database, and orchestrate notifications using an integrated workflow.

In addition to those features, FEB includes enterprise level integration capabilities by offering a REST API that can be used by other programs.

The REST API exposes operations on application submitted data, also known as records.

The data captured by a FEB application is stored in a relational database. Forms Experience Builder provides secure access to that data. The API is used to fetch responses from the FEB allowing for data filtering and searching. When accessing the data using the API, all security permissions as defined in the Access rules for the FEB application are enforced.

Using Forms Experience Builder REST API in applications built with Web Experience Factory

IBM Software

This lab is not about Forms Experience Builder applications. It is about creating external (web or portlet) applications accessing data created by existing FEB applications.

There are many ways of developing applications incorporating REST API (invoking RESTful services). It boils down to being able to programmatically send HTTP GET and/or POST requests and process HTTP responses. Many programming languages provide such support, including Java, C#, JavaScript, Perl among others. For this Lab we have chosen a programming-less approach. We will use the IBM Web Experience Factory V8 (WEF) product with its Eclipse based graphical WEF Designer tool. Using WEF does not preclude programming. A developer can still use Java or JavaScript code to customize and enhance their application beyond out-of-the-box capabilities. In fact, more complex applications will likely require some coding. The WEF includes an easy mechanism for including Java methods or other Java artifacts as part of a complete application.

The following two paragraphs describe main features and benefits of Web Experience Factory:

IBM Web Experience Factory allows you to build rich, complex, multi-channel applications without having to write code. Key concepts include builders, models, and profiling. Developers create applications by snapping together a sequence of components called builders. Each builder has a simple wizard-like user interface and does the work of automatically generating or modifying part of an application. Some builders create web application artifacts such as a page or a table, while other builders modify the artifacts created by previous builders such as rearranging, hiding or adding columns to a table. Builders are assembled in models, which are like application production lines. Each time a change is made to any of the builders in a model, the application code is regenerated, allowing the developer to iteratively develop an application. In addition, developers can create multiple variations of an application from one code base, without requiring additional code changes or republishing. This is done with the profiling feature of IBM Web Experience Factory. Different profiles can be created for different user roles and even different device/channels.

WEF includes an easy-to-use graphical tool for creating, viewing, and running web applications and portlets: the IBM Web Experience Factory Designer. WEF Designer provides simplified rapid application development of custom applications and portlets for IBM WebSphere Portal that leverage existing enterprise applications, data and systems - including relational databases, Web services, REST services, SAP®, PeopleSoft®, Lotus® Domino, Microsoft® Excel and more. It does this all without requiring Java EE development expertise, and without developers needing to implement and learn application and portal APIs by automating portlet development with reusable wizard-like components, called Builders. This automation speeds custom portlet development to reduce development time and cost while accelerating portal deployment for incremental ROI.

IBM Software

The application created in this Lab is a portlet application that can be deployed to WebSphere Portal server. You will create a project in Web Experience Factory, consume data from a backend datasource, (the FEB application via FEB REST API) and display the data in a Web 2.0 based table. The UI we are striving to achieve should appear similar to the figure shown below:

Prerequisites (already completed)

The Lab depends on the following software installed on the image:

• IBM WebSphere Portal V8.0

• IBM Forms Experience Builder V8.0

• IBM Web Experience Factory V8.0

• One of the Web browsers (Internet Explorer and/or Firefox)

• cURL tool and Excel Viewer


IBM Software

• existing FEB application with application data (Expense Report application is made available for import into FEB)

Duration

You should be able to complete this lab in approximately 75 minutes.

IBM Software


1.1 Getting Started

To complete this lab, you will need to run the Portal 8.0 server which also includes Form Experience Builder installed and configured. When Portal server is started the Forms Experience Builder web application becomes automatically activated. It was deployed to the same WebSphere_Portal server and is started together with other portal related applications..

__1. Start the Portal 8.0 server by double clicking on the icon. Wait a few minutes and make sure Portal has started successfully.

__2. Launch Forms Experience Builder with the following URL

http://portal.ibm.com:10039/forms


http://portal.ibm.com:10039/forms

IBM Software

__3. If prompted, login to Forms Experience Builder using the following credentials. After entering credentials, click Log In button.

User ID: wpadminPassword: passw0rd (with a zero)

1.2 Importing the Expense Report Application

The Expense Report application that you are going to access using the FEB REST API has already been created and exported to the file system. To save time we have created some sample data (i.e. submitted several user expense report records using this application) and used the 'Include submission data' option to export the application with the data.

The application and its data are needed to demonstrate the REST API functionality.

Follow the steps in this section to get started.

__1. Click the Manage link at the top of the page.

IBM Software

__2. Import the Expense Report application.

Click Import in the Manage Applications page/view.

__3. In the Import Application popup window click Browse button and drill down to

“C:\Lab Files\RestAPI Lab” folder. Select ExpenseReportwithData.nitro_s file.

Make sure to mark (check) both the Deploy application? and Import data? checkboxes. Click OK to initiate import.


IBM Software

__4. The Expense Report application should now be displayed. Click Show application details double arrow icon ( ) next to the application name to show more details.

__5. Make a note of the application UID and the form I that are displayed in the URL Links section (highlighted in red in the image below). Notice that the application ID is also shown in the Details section above the URL Links.

As you will see later, to list data from any given application, the application ID and the form name must be known. They are required when making any REST API calls accessing application data. All REST API actions: List, Create, Retrieve, Update, Delete (CRUD) require the app-uid and form-id in the URL identifying the API call/action. Here you see :

app-uid = 33738ef3-8277-4a02-8332-9a2bc41972f4

form-id = F_Form1

Copy the displayed ID to a clipboard or copy/paste it to a text file.

IBM Software

1.3 Exploring the REST API

There are several ways one can work with RESTful APIs (or REST style services). Since there is no standard description of a REST service product documentation must be consulted to find out implementation details. The REST API is a web service implemented using HTTP protocol with a set of supported HTTP requests: GET, PUT, POST or DELETE, to perform desired actions. Resources that are subjects of those operations must be uniquely identified (or addressed) in a URL invoking the service.

The IBM Forms Experience Builder REST API documentation ( http://www-10.lotus.com/ldd/lfwiki.nsf/dx/Data_access_REST_API_FEB_8 ) provides the following summary:

URL HTTP Verb Action Name/forms-basic/secure/org/data/{app-uid}/{form-id} GET List/forms-basic/secure/org/data/{app-uid}/{form-id}/{record-uid} GET Retrieve/forms-basic/secure/org/data/{app-uid}/{form-id} POST Create/forms-basic/secure/org/data/{app-uid}/{form-id}/{record-uid} PUT Update/forms-basic/secure/org/data/{app-uid}/{form-id}/{record-uid} DELETE Delete


IBM Software

The /forms-basic/ context uses basic authentication rather than form based authentication. The credentials used for authentication must match the users and permissions specified by the application designer in the Access tab. Each form and stage can have different permissions set for each REST API action.

For example, to invoke the List RESTful service (action) that retrieves a list of records the URL takes this general form:

http://<host>:<port>/forms-basic/secure/org/data/{app-uid}/{form- id}?format={format}&sortBy={sort}&order={order}&from={from}&to={to}

where:

{app-uid} - the application UID

{form-id} - the form ID = F_Form1 by default

format={format} - The format in which the data must be returned.

◦ text/xml returns data as a standard ATOM feed in XML format. This is the default value.

◦ application/x-msexcel returns data as an Excel document

◦ application/vnd.oasis.opendocument.spreadsheet returns data as an IBM Symphony™ Spreadsheet document

sortBy={sort} - The order in which the data must be returned. The default sort order is indeterminate.

◦ lastUpdated uses the last updated date as the sort attribute.

◦ itemAuthor uses the display name of the author as the sort attribute.

◦ flowState uses the stage name as the sort attribute.

◦ item ID uses the values of a particular form item, for example, F_SingleLine, as the sort attribute.

order={order} - The direction of the sort.

◦ ASC uses an ascending sort order. This is the default value.

◦ DESC uses a descending sort order.

from={from}

The starting offset of a range of results. The default value is 0.

to={to}

The ending offset of a range of results. The default value is the end of the list.

IBM Software

In our Expense Report application case, {app-uid} = 33738ef3-8277-4a02-8332-9a2bc41972f4 and {form-id} = F_Form1 therefore a URL needed to invoke the List REST service/action in its simplest form, would be as shown below.

http://portal.ibm.com:10039/forms-basic/secure/org/data/33738ef3-8277-4a02-8332-9a2bc41972f4/F_Form1Note that the {app-uid} used in this example could be different in your particular environment.

In this Lab we will only use the List REST action/service. Please consult the REST API documentation for more information about other services.

Before starting to develop any REST API based applications, familiarize yourself with RESTful services requests and results produced by running them. There are many stand-alone tools, including web browsers that could be used to make REST calls without doing any coding.

One of the most popular is the cURL tool. It is a command line tool for getting or sending files using URL syntax. It runs on many O/S platforms including Linux and Windows. This tool has been installed for this Lab environment.

__1. To start working with cURL, open a comand window and change directory to C:\code\curl (i.e. issue command cd c:\code\url from the command prompt). This is where the cURL tool has been installed.


IBM Software

__2. At the command prompt enter the following cURL command:

curl --user wpadmin:passw0rd http://portal.ibm.com:10039/forms-basic/secure/org/data/33738ef3-8277-4a02-8332-9a2bc41972f4/F_Form1

__3. Observe the result returned from running the cURL command. Since the default returned format is text/xml (format=text/xml is the default, if omitted), the data represents standard ATOM feed in XML format. To have a better look into the returned XML data, you can specify -o FILE option in the curl command invocation. The -o option will direct cURL to write output to specified file instead of stdout. We will do it in the next step.

IBM Software

__4. Re-run the cURL command using the -o FILE option. The file name is listoutput.xml and it will be created in the same directory the cURL is executing from (C:\code\curl )

curl --user wpadmin:passw0rd -o listoutput.xml http://portal.ibm.com:10039/forms-basic/secure/org/data/33738ef3-8277-4a02-8332-9a2bc41972f4/F_Form1


IBM Software

__5. Use Windows Explorer and go to C:\code\curl directory . Right-click on listoutput.xml file name and select Open with → Internet Explorer (for better readability of the XML file)

__6. You can easily see that the ATOM feed returns all (3 in our case) <entry> elements (to conserve space only the top <entry> is shown in the image on next two pages) .

It is important to note the following points:

▪Each submission record (an expense report in our case) is represented by an <entry> within the feed.

▪Each entry has an <author> that represents the person who initially created the record.

▪Each entry has a <contributor> that represents the person who last updated the record.

▪Each entry has a <link> with rel="edit" that represents the URL to use to Retrieve and Update just this record.

▪Each entry has a <link> with rel="print" that represents the URL that, when displayed in a browser, is the print version of the record.

IBM Software

▪Each entry has a <link> with rel="form" that represents the URL that, when displayed in a browser, allows the editing of this record.

▪Each entry has a <content> that contains the actual data for this record. There are multiple <F_Table> elements containing detailed data (individual expenses in our case)

▪The root element of the actual data, which in this example is <F_Form1> , has a generated uid attribute. This attribute is the unique ID for the record and can be used for subsequent calls to Retrieve, Update, or Delete for that particular record.


IBM Software

IBM Software

__7. In addition to the standard ATOM feed XML format returned by default from the List REST service call, there are two more formatting options supported by this REST API. One is the Excel document format and the other one is the Open document spreadsheet format supported by IBM Symphony.

In the next step we will use this powerful functionality to generate an Excel spreadsheet document from our Expense Report application data.

__8. Modify the URL used in the cURL command to specify format=application/x-msexcel and re-run cURL using the -o listoutput.xls option to direct the output to a spreadsheet file. The full command is shown below.

curl --user wpadmin:passw0rd -o listoutput.xls http://portal.ibm.com:10039/forms-basic/secure/org/data/33738ef3-8277-4a02-8332-9a2bc41972f4/F_Form1?format=application/x-msexcel

__9. Use Windows Explorer and go to C:\code\curl directory . Click on listoutput.xls to open the file with the Excel Viewer (MS Office is not installed on this image).


http://portal.ibm.com:10039/forms-basic/secure/org/data/33738ef3-8277-4a02-8332-9a2bc41972f4/F_Form1?format=application/x-msexcel

http://portal.ibm.com:10039/forms-basic/secure/org/data/33738ef3-8277-4a02-8332-9a2bc41972f4/F_Form1?format=application/x-msexcel

IBM Software

__10. The Excel Viewer shows the expense report data grouped into 3 areas (one expense report per submission). As you can see one of the reports has been approved. The Viewer does not allow for any editing or expanding of the columns so some of the data is not fully visible. You will need MS Excel product to see all the information and/or manipulate the data.

IBM Software

1.4 Creating the REST API Web Application using Web Experience Factory

In this section we will demonstrate using the IBM Web Experience Factory software to build a web portlet application that utilizes the IBM Forms Experience Builder REST API for acquiring the Forms application data. Our application will access the data from the Expense Report application that we imported in the prior section.

For more information about the IBM Web Experience Factory, reference the Introduction section at the beginning of this Lab document and the product documentation.

In this section, you will create a new Web Experience Factory project. In subsequent sections you will add the Service Provider and the Service Consumer models to this project. Since the focus of this lab is REST services, the Service Provided will include the REST Service Call builder accessing the data. Once the service provider model is finished and tested, you will then be able to consume and display the data using the service consumer model

__1. Use the Web Experience Factory Designer shortcut located on the desktop to start Web Experience Factory:

__2. If prompted to select a workspace, identify your unique workspace name by appending a folder name of your choosing to the presented default workspace location/path, for example 'RestApiLab'. The folder doesn't have to exist and will be created for you. Click OK to proceed.


IBM Software

__3. Dismiss (close) the Welcome and Feeds tabs, if shown and close the welcome.html in the center pane to display the Designer's perspective as shown below.

__4. From the menu, select File → New → Web Experience Factory Project.

IBM Software

__5. Name the project FormsRestLabProject and click Next to continue.

__6. On the Feature Set page, accept defaults and click Next to continue.


IBM Software

__7. On the Server configuration page, you should see WASCE configuration already created and selected by default. Since we are deploying to WebSphere Portal V8 server, uncheck WASCE and select Portal V8 server instead. If there is no Portal V8 configuration showing in the list, click Create Server Configuration button to create it.

__8. From the Create Server Configuration popup window, select IBM WebSphere Application Server and Portal Server 8.x and click OK.

IBM Software

__9. In the Edit Server Configuration window accept defaults and provide user credentials for accessing the Portal server:

User name: wpadmin Password: passw0rd

Click Test connection button to validate connectivity.

__10. Wait until operation in progress is finished and you see a message confirming your Server configuration is OK. Click OK to dismiss the message window.


IBM Software

__11. Click OK again to return to the Server configuration window. Make sure IBM WebSphere Application Server and Portal Server 8.x is now selected as the server you would like to publish your application to. Click Finish.

__12. Wait for the operation to finish. When prompted if you would like to publish your project now, choose Yes. Please wait for the publishing to complete. Click OK to dismiss the Publish results window .

IBM Software

NOTE: Please be patient as the project is published. The time taken will depend on the lab system resources.

__13. Once the project is created and publishing completed, your workspace should be similar to the following image.

__14. If you see a Warning displayed in the Problems section about Java J2SE-1.5 execution environment – “... no JREs installed that are compatible with this environment”, correct the issue as described in the next step.


IBM Software

__15. Right-click on the FormsRestApiLab project name and select Properties.

IBM Software

__a. In the Properties for FormsRestLabProject window select Project Facets in the left side panel and change the Java version from 1.5 to 1.6 by clicking the triangle icon next to 1.5 in the Version column..

__b. Select 1.6 from the available versions dropdown list and click OK. The warning message should now be resolved.


IBM Software

1.4.1 Creating the Service Provider to access the application data

In the previous section, you created a new WEF project. In this section, you will create a Service Provider responsible for providing data from the back-end system. In our case the data is the Expense Report application data that is stored in the Forms Experience Builder database. This data will be accessed using REST API services supported by the Forms Experience Builder software.

Note: It is recommended you execute all the steps in this section. However, we also provided a solution, i.e. a completed Service Provider model that you can import to your project (importing instructions are at the end of this document). The model to be imported here is stored under: “C:\Lab Files\RestAPI Lab\solution\FormsDataProvider.model” . If you import this model you can skip to step 26 of this section (to test the model) and resume the lab from there.

__1. Right-click the project name and select New->Web Experience Factory Model from the list of presented choices

__2. In the Choose Project dialog, select FormsRestLabProject and click Next to continue.

__3. In the Select Model dialog, select REST service provider model type and click Next to continue.

Note: By selecting a non-empty model type at this stage, the model creation “wizard' will automatically generate several builders for you (depending on the type you selected). Alternatively, you could select the Empty model which would create an empty model giving you opportunity to add your builders later.

IBM Software

__4. Name the service FormsDataService and click Next to continue.


IBM Software

__5. The next panel guides you to provide the REST call information. As practiced in the section 1.2, you are going to use the same List REST service (action). Provide the following :

▪HTTP Request Type => GET (the default)

▪URL => http://portal.ibm.com:10039/forms-basic/secure/org/data/33738ef3-8277-4a02-8332-9a2bc41972f4/F_Form1

▪User Name => wpadmin▪Password => passw0rd▪Logical Operation => Retrieve List

Click Next.

http://portal.ibm.com:10039/forms-basic/secure/org/data/33738ef3-8277-4a02-8332-9a2bc41972f4/F_Form1



IBM Software

__6. Click Next in the following (REST Schema Information) panel since the schema information will be obtained from the actual service call.

__7. In the Save New Model panel, name the model FormsDataProvider and click Finish.


IBM Software

__8. The provider model “wizard' you just used automatically created four builders as shown in the next image. The builders appear in the Outline panel of the WEF designer. The builders created were:

▪Comment builder (optional - containing usage comments)

▪REST Service Call builder

▪Service Definition builder

▪Service Operation builder

To review the builders, double-click a selected builder in the Outline area and explore the builder's definition in the Builder Call Editor panel. As you can see, the Service Definition builder was generated with the testing support enabled. This feature gives you a quick and easy way of testing the service operations defined in the Provider model. Also, note that the Service Definition builder specifies all operations using this service as 'Public' so the operations will be 'visible' outside of the Service Provider model and can be invoked from other models, specifically from the Service Consumer models.

IBM Software

__9. To test the service operation that was defined in the Service Provider model, click the Run Active Model icon, as shown below.


IBM Software

__10. A web browser window should automatically open, showing all the operations that were made available in the model. In this case you should see just one operation named FormsDataService_op (this is how the Service Operation builder was named). Click the FormsDataService_op link to invoke the operation.

__11. A results page should now be displayed, showing the result of the List REST service/action call. Remember that our FormsDataService_op is defined to execute the action provided by the REST Service Call builder that you defined in the model. The partial output is shown below. Notice that WEF web engine formats the data for you for better readability (the 'raw' data returned by the operation is in the ATOM feed XML format).

IBM Software


IBM Software

__12. The next step is to enhance the Service Provider model with another operation that filters only selected information from the returned feed. Our application design calls for providing a simplified view of the expense report data. The UI that you will build later (in a separate Service Consumer model) needs to invoke an operation returning a subset of the complete feed data.

WEF supplies a set of 8 ready to use Transform type builders that operate on elements in schema typed XML data. With the help of those builders you can perform actions on XML data elements such as aggregate, combine, group, filter, map, merge, modify and sort.

Since the REST Service Call builder returns data in XML format (ATOM feed) you can easily apply any of the existing transform type builders to operate on this data. In this case the TransformMap builder appears to be capable of doing the needed transformation.

__13. To add a new builder to your model, click the Builder Picker icon in the Outline area.

__14. From the Builder Picker window select TransformMap builder. Click OK to open it in the Builder Editor.

IBM Software

__15. Name your builder transformFeed and provide the required Target Operation information. This is the name of an existing operation returning XML data for this Transform Map builder to operate on (as indicated by Apply Transform To radio button).

To populate this field use the Chooser helper by clicking the Chooser icon to the right of the field. In the Selection Action without Arguments popup window drill down to DataServices->FormsDataService and select execute. Click OK to populate the Target Operation with the DataServices/FormsDataService/execute operation (this is your REST Service Call operation that is providing results for transformation by this builder).

When working in Builder Editor use the Chooser functionality as much as possible. It greatly speeds up builder creation process and helps with selecting right information.


IBM Software

__16. In the Results Schema Options section select the Generate Automatically radio button.

__17. In the Map Options section click inside the Source Path column first row and click the Chooser icon. Inside the Choose Element window, drill down to feed->entries->entry->content->F_Form1->F_SingleLine (F_SingleLine represents the employee name). Click OK to transfer this XML path into the Source Path column.

Note: As you see, this builder is able to automatically generate the XML schema of the source data returned by the REST Service Call builder (i.e. the target operation results).

IBM Software

__18. Map this entry to forms/form/empname Target Path (the path chosen here is up to you) by entering typing this path into the Target Path column. Mark the Copy Text box to read true (the textual value from the source schema node will be copied to the target node

__19. Repeat above two steps to provide two more transformations. The table below summarized the transformation that is going to take place in this builder. Notice that the last transform mapping requires children of the schema node to be copied to the target node as well (otherwise we would not have any data transferred from the children of the F_Table schema node.

Source Path Target Path Copy Text

Copy Attribs

Copy Children

feed/entries/entry/content/F_Form1/F_SingleLine forms/form/empname TRUE FALSE FALSE


IBM Software

Source Path Target Path Copy Text

Copy Attribs

Copy Children

feed/entries/entry/content/F_Form1/F_Paragraphtext forms/form/description TRUE FALSE FALSEfeed/entries/entry/content/F_Form1/F_Table/F_Table forms/form TRUE FALSE TRUE

Once all the map options are provided, review the Result Schema Preview section to verify/preview the automatically generated result (target) schema of this transform.

__20. Click OK in the Builder Call Editor.

__21. Click Save (Ctrl+S).

IBM Software

__22. The transformFeed Transform Map builder is now added to the Provider model and is visible in the model's Outline area. The last thing to do on the Service Provider side is to define a public service operation that would give an access to the transformFeed from outside service

consumers. Click the Builder Picker icon in the Outline area and select the Service Operation builder from the available builders list. Click OK to continue.


IBM Software

__23. In the Service Operation builder editor, provide a meaningful name for this operation. For the Operation Name enter getExpenseData. Click the Chooser icon next to Action to Call field and select transformFeed from the Select Action window. Click OK in the window to populate Action to Call field with your selection. By doing that you are defining a public getExpenseData operation that when called from the service consumer would call the transform which in turn would call the REST service (a chain of actions ).

IBM Software

__24. Accept all other default values and click OK in the builder editor.



IBM Software

__26. Click Run Active Model icon to test the new operation. You should now see two operations displayed in a browser window. Click getExpenseData link.

__27. Observe that results displayed are different from the other operation. Only subset of the feed is being returned.

IBM Software

__28. The Service Provider model is now completed. In the next section you will work on the Service Consumer model to complete the application.


IBM Software

1.4.2 Creating the Service Consumer (application's User Interface)

In this sub-section, you will create a Service Consumer, which will consume the data and present it to users. The service consumer model will include User Interface type builders which provide robust UI mechanisms without the need to write any code.

Note: It is recommended you execute all the steps in this section. However, we also provided a solution, i.e. a completed Service Consumer model that you can import to your project (importing instructions are at the end of this document). The model to be imported here is stored under: “C:\Lab Files\RestAPI Lab\solution\FormsDataConsumer.model” . If you import this model you can skip to step 27 of this section (to test the model) and resume the lab from there.

Recall that the FormsDataProvider model (your Service Provider) defined all operations to access data from the back-end system. The back-end system is in this case Forms Experience Builder.

Loosely coupling the data layer from the presentation (consumer) layer is a best practice and Web Experience Factory makes this loose coupling easy to implement.

__1. From the menu, select File → New → Web Experience Factory Model

IBM Software

__2. In the Choose Project dialog, select FormsRestLabProject and click Next to continue.

__3. In the Select Model dialog, select the List and Detail Service Consumer model and click Next to continue.

Note: By selecting a non-empty model type at this stage, the model creation “wizard' will automatically generate several builders for you (depending on the type you selected). Alternatively, you could select the Empty model which would create an empty model giving you opportunity to add your builders later.


IBM Software

__4. Enter the name formsFeedConsumer and select FormsDataProvider as the provider model. For the latter, you can use the Chooser (the three dots to the right) to find it, or just type in the name. Accept the check mark for the 'Deploy this model as a portlet'. Click Next to continue.

__5. In the next panel, type in a portlet title as Expense Report Information. Click Next to continue.

IBM Software

__6. In the Main View panel choose the service operation to retrieve the main view data. Since this model was associated with the FormsDataProvider model, only public operations exposed in the provider model can be selected here. Click the selection box drop-down arrow and select getExpenseData operation from the list. Click Next to continue.

__7. In the Details panel, uncheck the Create Link to Details check box. Our application displays the list of expenses and there is no need to provide more details.


IBM Software

__8. Accept all setting in the Field Settings Information panel (you will tweak those settings later, after testing your consumer model). Click Next to continue.

__9. In the Save New Model panel, name the model as FormsDataConsumer and click Finish.

IBM Software

__10. The consumer model “wizard' you just used created automatically four builders as shown in the next image. The builders appear in the Outline panel of the WEF designer. The builders created were:

▪Portlet Adapter builder

▪Service Consumer builder

▪View and Form builder

▪Data Field Settings builder

To review the builders, double-click a selected builder in the Outline area and explore the builder's definition in the Builder Call Editor panel.


IBM Software

__11. The FormsDataConsumer is now the active model. You can test how it works by clicking the

Run Active Model icon at the top.

__12. Observe the displayed page. Notice that paging forward and backward is now part of the application (the 'View and Form' builder added this support). However, the overall format is not yet acceptable. The data is not displayed in a 'tabular', easy to read form and field labels are in most cases non-descriptive. You will make some tweaks to make results more readable in the next few steps.

IBM Software

__13. Double-click View and Form builder in the Outline area to open the builder editor.

The View and Form builder is responsible for most of the processing in your Service Consumer model. It is a very powerful builder, often sufficient to provide complete UI for applications/portlets built with WEF designer.

The View and Form builder creates view and form pages based on data from a data service. The view page can display a table or single record of data from the service results. You can also create the following associated pages: • An input page for the specified operation, with

optional validation • A detail page that displays either data from the

selected row in the view page or data from another data service or method

• An update page for editing details or results data


IBM Software

__14. In the View Page Options section of this builder the Paged Data Display is checked. This option enables/disables paging. Leave the paging enabled, but increase the number of rows per page from 5 to 10 (set Rows Per Page field to 10 ). Don't change anything else.

Click OK.

IBM Software


__16. Double-click Data Field Settings builder in the Outline area to open the builder editor.

The Data Field Settings builder lets you control all the page automation fields in a model. You can control a limited number of field settings (and validation settings for data entry fields) using the Data Field Settings builder. You can limit the changes to one page in the model or to all pages in the model on which the field appears.


IBM Software

__17. The Data Field Settings builder controls some basic field settings used in the model. You will now modify some of those settings.

In the Hide column, set the value to Hide Always for the top 5 fields (for all names starting with F_ ).

Hint: Click a row inside the Hide column to bring up a listbox containing valid values to choose from.

In the Label column, change labels of all remaining fields (the ones that are not hidden) according to what those fields represent (as shown below). Click OK when done.

IBM Software


__19. Re-test the Consumer model by clicking Run Active Model icon .

__20. Observe the displayed page. Notice that the expense data is now displayed in a tabular format. The table header reflects the label changes you made in the Data Field Settings builder. Also, the default page size is set to show 10 items as set in the View and Form builder. Click Show 10 items button and select Show all items from the pulldown.

__21. Observe the displayed page containing all items. Notice that the table is static. The column width cannot be manually adjusted and the column order is fixed. This can be easily fixed by adding to the consumer model one more builder - the Dojo Enhanced Table Modifier builder. You will do it in the next steps.


IBM Software

__22. Using Builder Picker select the Dojo Enhanced Table Modifier builder and click OK.

__23. In the builder Name field enter dojoTable as the name. For the Location Type select Container radio button. For the Container Field select a field using the Chooser:

Click the Chooser icon and drill-down to

[formsFeedConsumerView_ViewPage]formsFeedConsumerView_ViewPage→forms→form

Click OK in the Data Page Field Chooser window to populate the Container Field.

IBM Software

__24. Lastly, make sure Allow Column Resize and Allow Column Reorder are both checked. Uncheck remaining boxes and click OK in the builder editor.



IBM Software

__26. Re-test the consumer model by clicking Run Active Model icon .

__27. Observe the displayed page. Notice that you can now rearrange columns by clicking on a chosen column header, dragging the column to a different location and dropping it on another column header (the visual indicator will guide you while doing that).

You can now also change any column width by clicking on a column separator in the table header and dragging the separator left or right.

IBM Software

__28. The image below shows the displayed page after Employee and Description columns were moved to the first two positions in the table and all columns were expanded in size.

__29. The Service Consumer model is now completed. Your application test was successful and it is now ready to be deployed to the application (portal) server.


IBM Software

1.4.3 Deploying application to WebSphere Portal Server

After verifying that the application behaves the way you intended, all you have left to do is to publish its final version to a Portal server so that it can be accessed by portal users. As you remember, the service consumer model that you created in the preceding section included the Portlet Adapter builder. This makes it possible to deploy this application as the portlet application.

With IBM Web Experience Factory software there are basically two ways of application deployment. One is to use the WEF project 'Publish Application' function (automatic or manual to a development environment) and the other one is to use its 'Export' function to package the application in a standard Web application archive (WAR) format. The latter option is a recommended approach for exporting applications for production. Depending on your target environment you would use either the Export - > WEF Application WAR or the Export -> WEF Portal WAR option. The generated WAR file can be subsequently moved to your target environment and installed into your target (production) application (or portal) server using administrative interface supported in those environments. Please, consult WEF documentation for more detailed discussion of this topic.

__1. In this Lab we are using the local application (portal) server environment and using WEF's project publishing capability is the quickest way of refreshing the already pre-published application.

To publish the application, right-click the project name and select Publish Application option from the list of presented choices.

IBM Software

__2. Wait for publishing to finish (it may take up to a couple of minutes depending on the current load on the system). When publishing finishes, exit the WEF designer by selecting File->Exit from the top menu bar.

__3. Click the Portal Login icon found on the desktop to open a browser window pointing to the Portal Welcome page. Click Login link at the top right corner.

__4. Login using wpadmin / passw0rd credentials.


IBM Software

__5. Select (click) Forms Rest Lab page tab found next to Getting Started. The Forms Rest Lab page was created earlier to save some Lab time. Feel free to create your own page if you so desire. The only requirement when creating a page is that it must use 'Full' in its properties Profile setting. This is because your application (portlet) uses Dojo and Dojo must be enabled in the environment your portlet is deployed to ('Full' means that a given page supports all capabilities, including Dojo). Without the generated Dojo support you would see this error message:

__6. With Forms Rest Lab page displayed (no content is yet shown), click Edit Mode near the top right corner to switch to the edit mode.

__7. Click Content tab to start adding the content to your empty page.

IBM Software

__8. Type expense in the search field and click the Search icon (a magnifying glass) next to it. You should see the Expense Report Information portlet appearing as the search result (remember, this is how you titled your portlet – this title was specified in the WEF Portlet Adapter builder in your service consumer model). If you do not see the Portlet allow a few minutes and try again.

__9. Click the plus next to the portlet title (or just drag and drop the portlet onto the page canvas) to add the Expense Report Information portlet to the page.


IBM Software

__10. Click the save link to display your content.

__11. The Expense Report Information portlet should now be displayed. Switch back to the view mode by clicking the View Mode near the top right corner of the portal page.

IBM Software

__12. Verify that everything works as expected. Try to re-arrange and re-size the columns. Below is the Forms Rest Lab page after doing some adjustments.

__13. The Lab is now concluded. Congratulations!


IBM Software

1.5 Optional – Solution import instructions for WEF models

__1. To Import WEF models (for sections 1.4.2 and/or 1.4.3) follow instructions in this section.

Right-click models in the project explorer and select Import->Import

IBM Software

__2. In the Select window click General->File System and click Next.

__3. In the File system window browse to C:\Lab Files\RestAPI Lab\solution directory and select one of the models you wanted to import. Click Finish to complete importing the selected model.


IBM Software

1.6 Summary

This lab provided you with an overview of IBM Forms Experience Builder REST API. In this lab, you have learned how to use the API using cURL tool and how to use the IBM Web Experience Factory to easily build a web (portlet) application that used the REST API to access FEB application data and displayed the data in a portlet deployed in IBM WebSphere Portal.

Additional Resources

IBM Forms Experience Builder Documentationhttp://www-10.lotus.com/ldd/lfwiki.nsf/xpViewCategories.xsp?lookupName=Forms%20Experience%20Builder%208%20documentation

http://www-10.lotus.com/ldd/lfwiki.nsf/xpViewCategories.xsp?lookupName=Forms%20Experience%20Builder%208%20documentation

http://www-10.lotus.com/ldd/lfwiki.nsf/xpViewCategories.xsp?lookupName=Forms%20Experience%20Builder%208%20documentation

IBM Software

NOTES


© Copyright IBM Corporation 2012

The information contained in these materials is provided for

informational purposes only, and is provided AS IS without warranty

of any kind, express or implied. IBM shall not be responsible for any

damages arising out of the use of, or otherwise related to, these

materials. Nothing contained in these materials is intended to, nor

shall have the effect of, creating any warranties or representations

from IBM or its suppliers or licensors, or altering the terms and

conditions of the applicable license agreement governing the use of

IBM software. References in these materials to IBM products,

programs, or services do not imply that they will be available in all

countries in which IBM operates. This information is based on

current IBM product plans and strategy, which are subject to change

by IBM without notice. Product release dates and/or capabilities

referenced in these materials may change at any time at IBM’s sole

discretion based on market opportunities or other factors, and are not

intended to be a commitment to future product or feature availability

in any way.

IBM, the IBM logo, and ibm.com are trademarks of International

Business Machines Corp., registered in many jurisdictions

worldwide. Other product and service names might be trademarks of

IBM or other companies. A current list of IBM trademarks is

available on the Web at “Copyright and trademark information” at

www.ibm.com/legal/copytrade.shtml.

ibm forms v8 · built with web experience factory lab exercise. ... feb includes enterprise level...

Documents