Expertsystemen

 

SOAP

For the creator of a model, the SOAP interface is not that interesting. You add some data to a definition, and get some information back. With the SOAP definition file, a more technical person can create the interface, so the model creator can focus on the content of that model.

SOAP definition file

The definition of a SOAP interface is made in a 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 is 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, like 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 de Editor. The request part and reply part are defined in de soaprequestelement and the soapreplyelement. The soap file is ready for use, but, naturally, there are more options. In the root there are the following elements that can be used:

  • url: soap server endpoint
  • soapversion: for example soap 1.1 or soap 1.2
  • soapaction: the soap action
  • description: value is used to link this interface in the model. It is also used for the selection in de Editor.

the following values are optional, bold is default.

  • alwayscontinue: true or false. 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 this value (e.g. null)
  • minifyrequest: true or false. If true the xml will be send without indent or paragraphcharacters.
  • caching: true or false. 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.
  • fixnamespaces: true 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. 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’. Preffered 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 two way ssl
  • isprovider: true or false. true if the bbsoap is for use in a soap server
  • isconsumer: true or false. true if the bbsoap is for use as a soap client
  • xmlnewline: true or false if true then \n will be replaced by the paragraph character (#10 or $A)
  • 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 need 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 will ignore if a specific exception 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. With that element there are the following options: case zet een casus neer in de het 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 must repeat itself. Normaly that is 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