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.
SOAP (the Simple Object Access Protocol) is a method of making Remote Procedure Calls (RPCs) which is XML
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.
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
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
Define_Tag('Example.HelloWorld', -SOAP, -ReturnType='string'); Return('Hello World'); /Define_Tag;
Note that the
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.
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
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
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
The [Define_Tag] call for the SOAP procedure is shown below. The procedure is called "LassoReference.Lookup". The
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.
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
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.
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.
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
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 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
Please note that periodically LassoSoft will go through the notes and may incorporate information from them into the documentation. Any submission here gives LassoSoft a non-exclusive license and will be made available in various formats to the Lasso community.