Expertsystemen

 

SOAP

For the creator of a model, the SOAP interface is quite simply a mapping of data: you send some data, then get some information back.

SOAP definition file

The definition of a SOAP interface is made in an XML file, that starts with bbsoap and has the extension .xml, for example bbsoap.Nmbrs.CompanyService.Address_GetCurrent.xml.

These files are stored in the subfolder soapdef on the server. The same way, those files can be stored for the Editor.

On startup, the program will search for those files, and offer the interfaces to the model.

The basic layout of a bbsoap definition looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<bb:berkeleybridgesoap xmlns:bb="www.berkeleybridge.nl/soap">
  <bb:url>https://someserver.com/api/contactmanager.asmx</bb:url>
  <bb:soapversion>soap 1.1</bb:soapversion>
  <bb:soapaction>GetCompany2</bb:soapaction>
  <bb:description>ContactManager GetCompany2</bb:description>
  <bb:soaprequest>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:con="http://someserver.com/ContactManager/">
      <soapenv:Header/>
      <soapenv:Body>
        <con:GetCompany>
          <con:ID/>
        </con:GetCompany>
      </soapenv:Body>
    </soapenv:Envelope>
  </bb:soaprequest>
  <bb:soaprequestelement>//bb:soaprequest/soapenv:Envelope/soapenv:Body/con:GetCompany</bb:soaprequestelement>
  <bb:soapreply>
    <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <soap:Body>
        <GetCompanyResponse>
          <GetCompanyResult>
            <ID>string</ID>
            <ObjectType>string</ObjectType>
            <DisplayName>string</DisplayName>
            <Name>string</Name>
          </GetCompanyResult>
        </GetCompanyResponse>
      </soap:Body>
    </soap:Envelope>
  </bb:soapreply>
  <bb:soapreplyelement>//bb:soapreply/soap:Envelope/soap:Body/GetCompanyResponse</bb:soapreplyelement>
</bb:berkeleybridgesoap>

The file consists of some essential data, such as version, action and endpoint. The bb:description value is used to link this interface in the model. It is also used for the selection in the Studio.

The request and reply part are referenced in soaprequestelement and soapreplyelement as XPath-like values.

In the root you’ll also find the following elements:

  • url: soap server endpoint
  • soapversion: for example soap 1.1 or soap 1.2
  • soapaction: the soap action

The following elements are optional:

  • alwayscontinue: true or false (default). If true and if SOAP call fails (server not reachable for instance), just continue with the model.
  • setnullvalue: in reply, if a value is not available, the value will be set to this value (e.g. null).
  • minifyrequest: true or false (default). If true the xml will be send without indent or newline characters.
  • caching: true or false (default). If true then for the instance of that model the reply is cached. The same question will result in the reply from the cache. This is handy if you have to pay per request, in time or money.
  • fixnamespaces: true (default) or false. automatic adding of namespaces is prohibited. This means the reply and request must be defined with the right namespaces.
  • authentication: true or false (default). used for authentication on HTTP level.
  • username: username if authentication = true.
  • password: password if authentication = true.
  • ssl: some servers don’t like being asked for sslv2, values are ‘tls1.3’, ‘tls1.2’, ‘tls1.1’, ‘tls1.0’, ‘ssl3’, ‘ssl2’. Prefered is to remove this element, the default will be done by the operating system (most safe).
  • authtype: value is ntlm for authentication NTLM.
  • authtype: with attributes rootcertfile ="SSL\rootca.cer" certfile=" SSL\servercert.cer" keyfile="SSL\serverkey.pem" and value twowayssl for authentication by two way ssl.
  • isprovider: true or false (default). true if the bbsoap is for use in a soap server.
  • isconsumer: true (default) or false. true if the bbsoap is for use as a soap client.
  • xmlnewline: true or false (default) if true then \n will be replaced by the LINE FEED character (&xa; or &x10;).
  • foldercaching: full folder path. The requests will not be send to the server, but stored in this folder. The folderworker will send those requests later (making sure the requests will always reach their destination).

Besides these options, sometimes the request or reply needs to be handled in a different way. For this, there are the processing instructions:

<bb:processing>
  <bb:processing-instruction httpcode="500">ignoreexception</bb:processing-instruction>
  <bb:processing-instruction transform="request">transform.xsl</bb:processing-instruction>
  <bb:processing-instruction xpath="//bb:soaprequest/soapenv:Envelope/soapenv:Body/doc">document</bb:processing-instruction>
  <bb:processing-instruction xpath="//bb:soapreply/soapenv:Envelope/soapenv:Body/doc">savedocument</bb:processing-instruction>
</bb:processing>

The first two are special.

The ignoreexception instruction will ignore it when a specific exception (in the httpcode attribute) is returned.

The transform instruction can be request or response. This will transform the request (after it is ready) or response (before it is processed).

The following instructions point out an element in the reply or request via the xpath attribute. Such an element can have the following values:

  • case: includes a case in the refered element
  • document: loads the document (base64) into that element. The value in that element from the model must be the documentname
  • cdata: will place cdata around the element
  • iterate: when the model has datasets, you can force that this element be repeated. Normally that happens automatic, but if we need to repeat /person/name/ do we repeat /person or /person/name?
  • iterateself: same as iterate, only this repeats itself
  • savedocument: Saves the document under the name of the value in that element, in the own session document folder. You can overrule the filename by adding the attribute filename (<data filename=”filename”></data>)
  • blob: the selected element will be converted to base64, or decoded if it is a reply from the server.
  • savedocaspdf: gets the content (base64) and converts it to a pdf file
  • savehtmlaspdf: gets the content (base64) and converts it to a pdf file