• Internet
• 18.07.2018
• EN

oshyn: WS + LS: Web Services in LiveServer

Consuming a Web Service with LiveServer, so simple anyone can do it. It’s just a matter of creating a Web Service Connector with the URL of the WSDL and write a dynament… but for advanced tasks, keep reading this post.

Given the fact that Web Services are based on XML, dealing with a method response in LiveServer is a piece of cake. As usual, a requirement is that you to set-up a connector and the corresponding dynament; having said that, let’s get into the details:

Inside LiveServer, create a new Web Service Connector

(Main Menu -> Administer RedDot LiveServer -> Connectors -> Web Services -> Administer -> New)

The first step asks for naming the connector, this name will be an attribute in the dynament, the URL of the WSDL and Username-Password, are only required if the URL needs authentication (HTTP basic). Remember the URL is accessed from the server, so you may need to add host file entries or firewall rules accordingly. In the second step, you select one of the service ports available and provide credentials if required by the port.

Additional configuration can be performed once the connector is created, select it and inside the General section, you can activate the connector for use, set timeout or change Username-Password. Under this section there is an Operation-specific configuration sub-section, there’s no need to get into this, unless you deal with bizarre attachments or parameters.
 

Default values for method parameters

In the Envelopes section, it’s possible to play with the SOAP envelope for a given method. This is especially useful to set default/fixed values for method parameters using placeholders in inline notation format [#param:placeholder#default#]
To create a new envelope, inside the Envelopes section click New Data Group, define an alias, select a method and click Edit. Then click Create envelope to work using a template for the method selected.

This is an example of the envelope with a default value for parameter source, a fixed value for parameter destination and a user attribute for parameter name.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Body>
        <MyMethod xmlns="http://mynamespaceurl.com/">
            <source xsi:type="xsd:string">[#param:source#This is a default value#]</source>
            <destination xsi:type="xsd:string">This is a fixed value</destination>
            <name xsi:type="xsd:string">[#user:rde-fields.name#]</name>
        </MyMethod>
    </soapenv:Body>
</soapenv:Envelope>

To use this envelope, the dynament must be set to type="prepared". We’ll get into that latter…
 

Reusing results

A Web Service call returns an XML structure. Using XPath expressions, you isolate important content that is relevant for you from the XML structure returned. You assign these to attributes that can be used directly with Attribute dynaments.

In the Result attribute section, Add a New Data Group, select a Service Method, write an XPath expression, enter an Attribute name and select a Source. It is useful for counting the number of results or saving a method result in the session for latter use without having to call the method again… always think lighter!

The Namespaces section is only used when a specific method requires a namespace that is not explicitly defined inside the WSDL, not a big deal; on connector creation, all namespaces in the WSDL are filled automatically here. If the XPath expression defined to reuse the results is not working, a missing namespace would probably be the cause.

The dynament to consume a web service is pretty simple, there are 3 options:
 

Envelope type

Using the type=”envelope”, a SOAP envelope can be defined inside the dynament. Remember the parameter can be fixed or can use the inline notation. This is the most difficult way to do it, so just skip this one

<dynaments>
<rde-dm:webservice name="MyConnector" tag="myxmltag">
    <rde-rd:soap-message type="envelope">
      Here goes an envelope, such the one defined above in this post
    </rde-rd:soap-message>
</rde-dm:webservice>
</dynaments>

Prepared type

Using the type=”prepared”, we can use the prepared envelope defined in the Envelopes section. It is referenced using its alias. In our example there’s no need to use parameters, since all of them will have default or fixed values. The alias can be totally different from the method name:

<dynaments>
<rde-dm:webservice name="MyConnector" tag="myxmltag">
    <rde-rd:soap-message type="prepared" prepared-envelope="myalias">
    </rde-rd:soap-message>
</rde-dm:webservice>
</dynaments>

Operation type

Using the type=”operation”, it is possible to call the method directly. Everything inside the message tag is a parameter; it has to be surrounded by tags which correspond to the parameter name in the web method. So in this example, one parameter is read from the request and the other is hardcoded

<dynaments>
<rde-dm:webservice name="MyConnector" tag="myxmltag">
    <rde-rd:soap-message type="operation" operation="mymethodname">
        <rde-dm:attribute mode="read" source="request" attribute="TextValue" tag="source" />
        <destination>Hardcoded value</destination>
    </rde-rd:soap-message>
</rde-dm:webservice>
</dynaments>

Notice the tag attribute in the rde-dm:webservice node, it is useful to have it, so when rendering the XML returned by the method, a XSL can easily identify the elements it should to work with. One very important thing to remember, is that inside the XSL you should add the namespaces used in the method response before rendering it

It’s worth pointing out that LiveServer also provides its own Web Services, but that’s a matter for another post. Still if you are a do-it-yourself type, used to working from manuals, then check out the RedDot LiveServer Web Services section of the Users/Administration documentation.

Source: WS + LS: Web Services in LiveServer

© copyright 2013 by oshyn