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.

See Tutorial: Build a Web Service for information on building a server. This document explains how to access the service from another application.

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

To access a BuildProfessional Web Service you'll need to create the request xml file and run the REQUEST command.

Prerequisites

You will need the following to access a web service:

• BuildProfessional 8.02 or later.
• Latest Developer (xdev) release as available  in the Developer Zone.

Building a Web Service Client

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. If you've just built the example Web Service, you can continue to build on that application in which case the application is both a client and a server.

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

• The bpwc Package
• XML Access Components

The 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 "bpwc" or "xml" 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 bpwc package in the future do not make undocumented changes to the bpwc 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.

Testing the Service

Go to Tools / Request Tester. From the list of services, select the the service you want to access. Ensure that it is running and one or several entrypoints are available.
 

Accessing the Web Service

If you are running the example Web Service, open and run the bpwcTest function (change the V-bpwcService to your service name). Change L-bpwcEntryPoint to access different entry points (bpwsVariable, bpwsTest, bpwsPause). Change the "data" value to send different values to the server.

1 : // BuildProfessional Web Services Client Test Function
2 :
3 : *DELAY = 0
4 :
5 : // Setup:
6 : V-bpwcServer = "localhost"
7 : V-bpwcService = "bpclient"
8 : V-bpwcTimeout = "5"
9 : L-bpwcEntryPoint = "bpwsQuick"
10 :
11 : // Connect to Service:
12 : L-bpwcError = VISIT bpwcRemoteLogin "guest" ""
13 : IF L-bpwcError <> "" THEN ERROR "2Could not connect to service "; EXIT
14 :
15 : // Display Session Id Received:
16 : *ERROR = "2Logged on. Session Id=" V-bpwcSID
17 : ERROR *ERROR
18 :
19 : // Create a Request with a data element:
20 : XML *SUBSET "myrequest" *ROOT= "bpxml"
21 : XML *INSERT "myrequest" *ELEMENT= "data" "20"
22 :
23 : // Issue Request:
24 : L-bpwcError = VISIT bpwcRequest "myrequest" "myreply" L-bpwcEntryPoint "XML" V-bpwcTimeout V-bpwcServer V-bpwcService V-bpwcSID
25 : IF L-bpwcError <> "" THEN EXIT
26 :
27 : // Save Reply in file:
28 : XML *WRITE "myreply" "bpwcReplyFile.xml"
29 : ERROR "2Request Successful. Reply in bpwcReplyFile.xml"
30 :
31 : // Finally, logoff:
32 : VISIT bpwcRemoteLogoff
33 :
34 : // Confirm Session Id:
35 : *ERROR = "2Logged off. Session Id=" V-bpwcSID
36 : ERROR *ERROR

How Does it Work?

The bpwc package contains components that simplify the access of the Web Service. The following describes what they do:

Some entry points are "secure" and therefore require a non-public session id in order to talk to a BuildProfessional Web-API service. We use the bpwcRemoteLogin function to obtain the session id into V-bpwcSID.

For each request we create an XML subset containing the details we want to send to the Web Service.

To run the request, we call function bpwcRequest. This will first place the request subset inside the Web-API required envelope and then issue the request using the REQUEST command. Any high-level errors are handled automatically. If the reply is received ok, the reply data is extracted from the reply envelope and returned to the calling function.

Eventually we will call bpwsRemoteLogoff to disconnect from the service and return the session id.

NOTE. Session Id are issued automatically for non-secure entry points. Session Ids control the number of users accessing the service.

Other Methods to Access the Service

You can also access a BuildProfessional Web-API Service from the command line or from a library using the Web-API Client. Create an example request file by saving the results produced in function bpwcRequest.

From a UNIX or Windows Command Line

Run the Web-API Client from the command line.

UNIX / Linux:
webapiclient -c ./webapiclient.conf -i requestfile.xml -o replyfile.xml

Windows:
webapiclient.exe -c .\webapiclient.ini -i requestfile.xml -o replyfile.xml
 

From a Windows Application

Use the webapi.dll library version of the Web-API Client. For details see Web-API Visual Basic Example.
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. See the xri package for accessing the Repository Service.
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.