Defining and Calling SOAP Procedures

The tip of the week for September 21, 2007 shows how Lasso's built-in SOAP functionality can be used to define SOAP procedures which other SOAP clients can call and how to define local tags which serve as proxies for remote SOAP procedure calls.

Introduction

SOAP (the Simple Object Access Protocol) is a method of making Remote Procedure Calls (RPCs) which is XML-based and is supported across a broad spectrum of languages and Web application servers. SOAP procedures on a public server may be used to look up shipping rates, to find results in a major search engine, or for many other purposes.

SOAP may also be used to call remote procedures on another Lasso server. This tip shows how to create a couple local SOAP procedures and then to call them using a local Lasso tag as a proxy. This tip also shows how a local tag can be used to lookup data using a publicly available SOAP procedure hosted on LassoSoft's Reference server.

This tip shows how SOAP works when Lasso is both the host of the remote procedure and the client. There are some shortcuts which make these kind of SOAP calls easy. Calling remote procedures defined by other languages or Web application servers is conceptually the same, but dealing with the data types used by some servers can be difficult.

The files for this tip can be download from the following URL and run in any copy of Lasso 8.5.4.

<http://download.lassosoft.com/pub/TotW/TotW_9305.zip>

Note - Despite being called "simple", SOAP is actually a heavyweight protocol. The XML which is required for SOAP calls can get quite complex and makes extensive use of namespaces which can be confusing to read and parse. A future tip of the week will discuss how to do XML-RPC calls and how to use JSON for easier remote procedure calls.

 

Hello World Example

The code in this section is found in the SOAP_HelloWorld.lasso file.

This example creates a trivial SOAP procedure on the local server and then immediately calls it. The example is simple, but it demonstrates the basic principles of defining and calling SOAP procedures.

First, we need to define a SOAP procdure. We do this using the [Define_Tag] tag with a-SOAP keyword. Rather than defining a tag that we will call locally, this instead defines a SOAP procedure which can be called remotely. Our simple example defines a tag with no parameters that returns the string "Hello World".
 

Define_Tag('Example.HelloWorld', -SOAP, -ReturnType='string');
    Return('Hello World');
  /Define_Tag;

Note that the -ReturnType for the tag is specified. SOAP procedures must specify the-Type for every -Required and -Optional parameter and must specify a -ReturnType.

Since the tag is not defined locally, an attempt to call this tag like [Example.HelloWorld] will fail. Instead, the tag is added to the list of publicly available SOAP procedures which can be found by looking at the WSDL file for the local server. The following URL loads the WSDL file, but since it is in XML you must view the source of the page to see the content.
 

 http://127.0.0.1/RPC.LassoApp?WSDL

The WSDL file is hard to interpret directly, but if we scan through it we can find the list of operations where our Example.HelloWorld procedure is defined.

Fortunately, Lasso will interpret the WSDL file for us and create a local tag which serves as a proxy for the remote SOAP procedure. First, we load the WSDL file for the local server into a variable using the [Include_URL] tag.

var('localWSDL' = Include_URL('http://127.0.0.1/RPC.LassoApp?WSDL'));

Then, we use [SOAP_DefineTag] to create our local proxy tag. The -Namespace and-LocalTagName combine to define the local tag name: [Example_HellowWorld]. The -WSDLparameter must be passed an XML object containing the WSDL file for the server we want to call. The -OperationName is the name of the remote SOAP procedure we want to call: Example.HelloWorld. The -Procs allows us to specify an array of post-processors for the data returned by the SOAP procedure. In this case we pass [Proc_Lasso] which is a shortcut that returns a normal Lasso data type from the results.

SOAP_DefineTag(
      -LocalTagName='HelloWorld',
      -Namespace='Example_',
      -WSDL=XML($localWSDL),
      -OperationName='Example.HelloWorld',
      -Procs=Proc_Lasso,
    );

Now, we can call the local tag [Example_HelloWorld]. Since this is a SOAP proxy tag it will generate a SOAP request envelope (in XML), send it to the local server, and interpret the SOAP response (again in XML) which is returned.

[Example_HelloWorld] -> Hello World

The net result is as if we called the tag on the local machine, but a lot of work has gone on behind the scenes to make this happen. If you load the example files locally you can see the SOAP request and SOAP response which were generated.

The remainder of this tip walks you through creating a more complex SOAP procedure which has a parameter and does some real work on the back-end. This SOAP procedure is provided in a local version and also in a publicly available version hosted on the Lasso Reference server.

 

Defining a SOAP Procedure

The code in this section is found in the SOAP_Define.lasso file.

Our goal is to create a SOAP procedure LassoReference.Lookup which allows anyone to look up the reference material for a Lasso tag. This procedure could be used on a Web server or in an editor in order to provide an up-to-date reference for any Lasso tag which was used, without having to worry about data that is stored locally going out-of-date. The procedure will accept one parameter, the name of the tag which is to be looked up.

The [Define_Tag] call for the SOAP procedure is shown below. The procedure is called "LassoReference.Lookup". The -SOAP keyword ensures that the procedure is only available through SOAP and is not defined as a local tag. The -ReturnType is specified as a string. The tag requires one parameter "tag" which also must be a string.

The contents of the tag is simple. An inline is used to find the specified tag. An error is reported if the inline reports one or if zero or more than one records are found. Otherwise, the tag's name, description, syntax example, and change notes are appended to the output variable and it is returned. The [Lasso_ErrorReporting] tag ensures that error reports do not contain too much extraneous information.
 

Define_Tag('LassoReference.Lookup',
      -SOAP,
      -ReturnType='string',
      -Required='tag', -Type='String');
    Local('output' = '');
    Lasso_ErrorReporting: 'minimal', -Local;
    Inline( -Log='none',
        -Search,
        -Database='ldml8_reference',
        -Table='tags',
        -Eq, 'tag_display'='Y',
        -Cn, 'tag_name'=#tag,
        -MaxRecords=1,
        -ReturnField='tag_name',
        -ReturnField='tag_description',
        -ReturnField='tag_syntax',
        -ReturnField='tag_changenotes');
      Fail_If(Error_Code != 0, Error_Code, Error_Msg);
      Fail_If(Found_Count == 0, -1, 'Tag not found.');
      Fail_If(Found_Count > 1, -1, 'Tag name must be unique.');
      #output += '<h2>' + Field('tag_name') + '</h2>';
      Field('tag_description') != '' ?
          #output += '<h3>Description</h3><p>' +
              Field('tag_description') + '</p>';
      Field('tag_syntax') != '' ?
          #output += '<h3>Syntax Examples</h3><p>' +
              Field('tag_syntax') + '</p>';
      Field('tag_changenotes') != '' ?
          #output += '<h3>Change Notes</h3><p>' +
              Field('tag_changenotes') + '</p>';
    /Inline;
    Return(#output);
  /Define_Tag;

That's it. The remainder of the file shows the generated WSDL file so you can confirm that the procedure has been defined (search for LassoReference and for HelloWorld). A copy of this SOAP procedure is defined on the public Lasso Reference server so our next step will be calling this SOAP procedure on that remote server.
 

Calling a Remote SOAP Procedure

The code in this section is found in the SOAP_RemoteCall.lasso file.

The SOAP procedure defined above is available on the public Lasso Reference server. The following code defines a local tag proxy which will call this remote SOAP procedure.

First, we must load the WSDL file for the remote server using [Include_URL]. The WSDL is what actually tells Lasso where the SOAP procedure is hosted so it is important to do this for each server that is to be accessed.
 

Var('referenceWSDL' = Include_URL('http://reference.lassosoft.com/RPC.LassoApp?WSDL'));

Then, we use [SOAP_DefineTag] to create our local proxy tag. The -Namespace and-LocalTagName combine to define the local tag name: [LassoReference_Lookup]. The-WSDL parameter must be passed an XML object containing the WSDL file for the server we want to call. The -OperationName is the name of the remote SOAP procedure we want to call: LassoReference.Lookup. The -Procs allows us to specify an array of post-processors for the data returned by the SOAP procedure. In this case we pass [Proc_Lasso] which is a shortcut that returns a normal Lasso data type from the results.

SOAP_DefineTag(
      -LocalTagName='Lookup',
      -Namespace='LassoReference_',
      -WSDL=XML($referenceWSDL),
      -OperationName='LassoReference.Lookup',
      -Procs=Proc_Lasso,
    );

The remainder of the file contains a simple form which generates a "tag" action parameter that is passed into this tag. -EncodeNone is used on the results so that the HTML formatting in the results can be seen in the browser. If you look in the example file, you will also see some code to format errors in red if they occur.

[LassoReference_Lookup(Action_Param('tag'), -EncodeNone)]

This deceptively simple tag will generate a SOAP request, transmit it to the Lasso Reference server, parse the SOAP result which is returned, and interpret the results back into a Lasso string variable.

 

Calling a Local SOAP Procedure

The code in this section is found in the SOAP_LocalCall.lasso file.

Since we defined the same LassoReference.Lookup on our local server, we can also craft a [SOAP_DefineTag] call to create a local proxy which calls this SOAP procedure locally. Since our local server is probably not configured to allow public access to the Lasso Reference database, this local call must take security into account.

There are only a few differences from the remote SOAP procedure call above. First, [Auth_Admin] is used to force the site visitor to provide an administrator username and password. Second, the URL for the WSDL file is specified locally using 127.0.0.1. Finally, the tag name is changed to [LocalReference_Lookup] and -Username and -Password parameters are used to pass the current [Client_Username] and [Client_Password] to the server.

Auth_Admin;
  Var('localWSDL' = Include_URL('http://127.0.0.1/RPC.LassoApp?WSDL'));
  SOAP_DefineTag(
      -LocalTagName='Lookup',
      -Namespace='LocalReference_',
      -WSDL=XML($localWSDL),
      -OperationName='LassoReference.Lookup',
      -Procs=Proc_Lasso,
      -Username=Client_Username,
      -Password=Client_Password,
    );

You can try out both the remote procedure call and the local procedure call in the example files download.

More Information

More information about all of the tags used in this tip of the week can be found in the Lasso 8.5 Language Guide or in the online Lasso Reference <http://reference.lassosoft.com/>.

Author: Fletcher Sandbeck
Created: 16 Dec 2010
Last Modified: 16 Mar 2011