A NEW TODAY IS DAWNING!

Tutorial: Building a Web Service


Introduction

One of the most important runtime features of BuildProfessional V8 is the ability to host and access XML Web Services. The Developer provides packages of components to build and access BuildProfessional Web Services with minimum coding.


The Basics

A BuildProfessional Web Service is an application that receives a Request document in XML format and based on the contents of the request, issues a reply document in XML format. While every request and reply is in XML format they can contain simple text structures (such as an ASCII file or web page).

You start building a web service by importing the bpws component package. The bpws package contains components for both application-to-application communication (xml application) and application-to-browser (web application). This document focuses on building an xml application.

You then define a service and publish entry points to that service. An entry point is a specific function that will be available from remote applications.


Prerequisites

You will need the following to build a web service:

  • BuildProfessional 8.02 or later.
  • Latest Developer (xdev) release as available in the Developer Zone.
  • An end user named "webpub". Define using administ using the same properties as the user "guest". This may already be defined if you are using a recent BuildProfessional release.
     


Building a Web Service

The following instructions will get you up and running. Then we will look at how it works.
 

Import the required component packages

Start the Developer and create a new empty application.

Import the following component packages from Application / Import Component Package.... Select the "Internet" tab to get the latest online versions of the packages:

  • XML Access Components
  • The bpws Package

Both packages warn about deletions. As you are starting an application from scratch there is no concern. If you later want to service enable an existing application, you may not have any existing components with prefixes "xml" or bpws", as these will be lost and replaced when importing the above packages.

Important! Regenerate the entire application. Have a quick view of the components imported from the Component Explorer View (select All Components from the tree view).

NOTE. As you may want to import a newer bpws package in the future do not make undocumented changes to the bpws components. Component packages are building blocks to quickly get up and running. Once you are up to speed with web services, you can rewrite the components to fit your specific requirements.


Create and start service


Services must be defined in both the webservices.xml and webapimanager.ini files.

Service Definitions (webservices.xml)

To define a service you must be running the Developer on the machine where the Web-API Manager is running.

From the Developer, select Tools / Local Services Definitions.... Select the "Add..." button and accept to add a service with the same name as the application name.

NOTE. A service is normally related to the application name, but not always. You can have many services running the same application.

The dialog will now show your service in the list of services with status "Not Running". If you are running the Developer Repository Service on your local machine, it will be displayed as "Online".

Services to Run (webapimanager.ini)

Edit the webapimanager.ini / conf file from the [install] / bin directory. Copy and paste the following lines (replacing myapp with your application name) at the bottom of the file:

[Service: myapp]
Description=My Test Service
CommandLine=-D -w -uguest -amyapp -pbpwsService -cC:\buildpro\bin\wintoday.ini -eC:\buildpro\tmp\myapp_err.txt
NumAgents=1
ServerCommand=C:\buildpro\bin\wintdyx.exe

NOTE. Edit the lines for syntax if you are on Linux.

Restart the BuildProfessional Web-API Manager:

  • On Windows use the Control Panel / Performance and Maintenance / Administrative Tools / Services utility.

  • On Linux kill webapi processes and restart with the installdir / bin / Webapimanager script.

Return to the Developer and select Tools / Local Services.... The service should now be displayed as "Online" with five or so entry points.

See Troubleshooting below if the service is not "Online".


Testing internal entry points


Internal entrypoints are functions that are included in every BuildProfessional Web Service. They provide the ability to login, list available entrypoints and logoff. Go to Tools / Request Tester. From the list of services, select the the service you just created.

Test Login. Press the "Login" button. This will call the internal login entry point and validate the user name (default is guest) against users defined by the BuildProfessional Administrator. A successful login will generate and display a Session Id. After login, the Request Tester automatically asks the service for defined entry points and displays them in the list.

Test Logoff. To release the session id and logoff, press the Logoff button.

Test getEntryPoints. From the list of entry points, select "getEntryPoints" and press "Run XML". The reply XML will be displayed in the reply file viewer.

NOTE. The getEntryPoints entrypoint was automatically called upon login to generate the listview.


Publish application entry points


Entry points are published by copying definitions in the xdev__EntryPoint blob to the bin/webservices.xml file. The bpws package contains several sample entry points that can be published.

The blob xdev__EntryPoint is automatically added by the Developer and contains the current application's entry points. We first need to add application entry points to the xdev__EntryPoint blob. The easiest way to do this is using the logic editor.

Do this each of the following functions: Open the function in the logic editor. Select "Logic / Publish as EntryPoint...". Select "Secure" as noted below. Close the function.

  • bpwsSignIn, Not Secure.
  • bpwsMain, Secure.
  • bpwsTest, Not Secure.
  • bpwsQuick, Not Secure.
  • bpwsVariable, Not Secure.
  • bpwsPause, Not Secure.

Review blob xdev__EntryPoint to see the entry point definitions.

Now we need to publish the application entry points to a server. Select "Tools / Local Services...". Select the service you defined above and press "Publish". The service should now be displayed as "Online" with approximately 10 entry points.

Important! Restart the Web-API Manager.


Testing application entry points


In the Developer go to "Tools / Request Tester..." and Login to your service.

Test each bpws entry point using both XML and HTML formats.

NOTE. If you select HTML as the format, the Request Tester will extract the HTML portion of the reply even though the reply is always in XML format. Press "View file..." for the actual reply contents. The bpws entry points provide both XML and HTML replies.

Edit the function bpwsQuick to alter the reply values and retest.


Accessing the Web Service

You can now read on or go to Tutorial: Building a Web Service Client to learn how to access the entry points from another application.

You can now read on or go to Tutorial: Building a Web Application to learn how to access the entry points from a web browser.


How Does it Work?

The bpws package contains components for both application-to-application communication (xml application) and application-to-browser (web application) communication. In most cases you do not need to understand the complete features of the package. See "Building a Web Application" for extended details on communicating with a browser. The following applies in both situations:

An application is launched by starting the Web-API Manager. The command line designates the startup process (P-bpwsService) which will initialize the application and quickly enter a wait state via the SERVICE *REQUEST command. The startup process allows the developer to determine what happens once on initialization and what happens on a request by request basis. The application remains in the wait state until a request is received or the Web-API Manager is shutdown.

An xml request file is sent from the Web-API client to the Web-API Manager on the server. The Web-API Client is available in the form of the REQUEST command, as a command line utility (webapiclient.exe), or as a library (webapi.dll).

Upon receiving the request, the manager will check the service and forward the request to a BuildProfessional process running the desired service. For each service you can define how many agents are to serve a certain service. The number of agents determine the number of concurrent requests that can be served simultaneously.

Once in the BuildProfessional application, the entry point is checked against the webservices.xml file from which it determines the function to run. The application, currently in wait state, is directed to run the common pre-entrypoint logic (bpwsReqInit), then the entry point specific function, and finally the post-entrypoint logic (bpwsReqCommit). Finally the application is returned to the startup process where it loops back into the wait state.

The entry point function can read details from the request xml file which is available in the *REQUEST xml subset. The bpwsGetElement is a wrapper for reading the request file.

The entry point function writes its response to one of two locations:

  1. In the case of an XML reply, to the V-bpwsPageSubset xml subset. This subset is returned as part of the reply in bpwsCommit.
     
  2. In the case of an HTML reply, to the V-bpwsPageBuffer text buffer. This buffer is inserted into the XML reply in bpwsCommit.

You can decide which entry-points are secure or non-secure. A secure entrypoint requires that the calling program has obtained a session id using the intLogin internal entry-point. For example, from the Request Tester you can access bpwsQuick without logging in.


Troubleshooting

There are several files to look for potential problems:

  • installdir / tmp / webapimanager.log contains errors relating to bad configurations or missing programs.
  • installdir / tmp / myapp_err.txt contains any error messages and trace output from the application. The "-D" option in the Command Line above is to turn trace output on.
  • installdir / tmp / bp_myapp.log contains log messages from the bpws components (from function bpwsLog).
     


Examples

The BuildProfessional Developer Repository Service is a comprehensive service built on the same principles as the bpws component package.
 

Limitations

Non Standardized Service. While operating on the same principles, BuildProfessional is not a SOAP compatible Web Service. Future releases will address this issue. This will change the Web-API envelope and allow access to the service without a Web-API Client.

Web-API Envelope. BuildProfessional requires the Web-API envelope to process requests. Future releases will change the handling of this envelope.

Service requests must complete within 60 seconds. There is no keep alive functionality. For longer requests (jobs) you need to create job management functionality.