03. Links SOAP Service
Posted by Maddison Mitchell, Last modified by Amy Wallace on 26 November 2020 11:56 AM

SOAP and the Links Database
Links uses SOAP as the communication layer between authorised internet applications and the Links database via your external static IP. The Links SOAP server runs on an included, standalone installation of Apache. In order for the system to work, the following conditions must be met.

1. The SOAP Service must be installed and running (this is completed by the Links Online Specialist)

2. The following IP and port rules MUST be in place:

Via your external static IP.

  • Incoming traffic for ActiveCarrot to communicate with Links

Inbound TCP to Client External IP Port 10255 (or custom port if configured differently) from:

35.201.6.155 & 35.244.88.75 and all return traffic

  • Outgoing traffic for Automatic Update of the Soap Service

Outbound from Client External IP to 35.201.6.155 & 35.244.88.75 Port 443 and all return traffic

  • Outgoing traffic for Export to e-Blast

Outbound from Client External IP to 35.201.6.155 & 35.244.88.75 Port 443 and all return traffic


Installing the SOAP Service
Installing the SOAP service is a task completed by the ActiveCarrot Project Manager.

The requirements for the SOAP Service configuration file are:

- The Links Database host name.

- A Links Database SQL user ID and password.

- The static endpoint IP of the PC where the SOAP Service is to be installed and the dedicated port (by default 10255).


Links SOAP API
SOAP (Simple Object Access Protocol) is a protocol used as in interoperable interface between two dissimilar operating systems. It uses standard HTTP requests and XML as the mechanism for achieving this. The SOAP protocol defines the rules in which this communication is achieved. SOAP calls are much more likely to get through firewall servers that screen out requests other than those for known applications. HTTP requests are usually allowed through firewalls so programs using SOAP are likely to be able to communicate with programs anywhere. Authentication of SOAP calls within the Links API is constructed in the header part of the SOAP envelope. The parameters sent are location_id and api_key. These correspond to configuration options in the links software database. The calls themselves are done via the standard SOAP protocol and an example can be seen above. Most programming platforms come built with the tools to consume SOAP API’s and it is widely used by banks and large organisations.

What is SOAP?
The Simple Object Access Protocol (SOAP) is a minimal set of conventions for invoking code using XML and HTTP. DevelopMentor, Microsoft, and UserLand Software submitted SOAP to the IETF as an Internet Draft in December 1999. Since then, numerous application server/ORB vendors have announced support for the protocol as an Internet-friendly alternative to Microsoft's DCOM, Sun's RMI, and OMG's CORBA/IIOP (see the SOAP FAQ for a list of supporting vendors and products). SOAP utilizes the existing HTTP-centric fabric of the Internet to carry method requests that are encoded as XML both for ease of parsing as well as platform/language agnosticism.

A Top-Down View
SOAP allows methods to be invoked against endpoints over HTTP. A SOAP endpoint is identified by a URL (just like any HTTP-based resource). A SOAP method is uniquely identified by a namespace URI and an NCName. The NCName maps to the symbolic name of the method. The namespace URI scopes the method name, much like an interface name scopes a method in Java, CORBA, or COM. SOAP method requests are transported in HTTP POST requests. They must have a SOAPMethodName HTTP header indicating the method being invoked. The HTTP payload of a SOAP method request is an XML document that contains the information needed to invoke the request. Assuming that all that is needed to get a bank balance is an account number, the HTTP payload of the request would look something like this:
After drilling through the SOAP:Envelope and SOAP:Body elements, the "root" element of SOAP:Body is an element whose namespace-qualified tag name matches the SOAPMethodName HTTP header exactly. This redundancy is to allow the HTTP-based infrastructure (proxies, firewalls, web server software) to process the call without parsing XML, while also allowing the XML payload to stand independent of the surrounding HTTP message.
Once the server-side operation has executed, an HTTP response message will be returned to the client containing the results of the operation. There are no SOAP-specific HTTP response headers. However, the HTTP payload will contain an XML document that contains the results of the operation. The results will be inside an element whose name matches the method name suffixed by "Response." Here's an example response message (including the HTTP header): SOAP endpoints are just URLs. SOAP methods are just a pair of XML element declarations identified by a namespace URI and an NCName.

A Bottom-Up View
Now that we have looked at a simple SOAP method call, it is useful to dissect the SOAP protocol from the bottom-up. Figure 1 shows the implied layering model of SOAP. While the SOAP specification is not organized according to this figure, the figure acts as a reasonable decomposition of the SOAP protocol. Note that the core of SOAP is the XML 1.0 recommendation and XML Namespaces. This reflects the fact that SOAP is simply an application of XML. The next layer is the XML Schemas specification. While SOAP does not mandate the use of XML Schemas, it was designed to allow them to act as its type description language. Additionally, several "XML Schema-isms" appear in the SOAP specification. In particular, SOAP's use of the xsi:type attribute. Note that neither of these two layers are SOAP-specific. Rather, these are two technologies that SOAP utilizes. The first "new" layer added by SOAP is the element-normal-form encoding style described by section 8 of the SOAP specification.

Authentication
SOAP Header Authentication The API utilises the current pre-shared API key sent through the request header. It is automatically authenticated against the links database with every request ensuring strong security. No request to the API port can pass the authentication layer without a successfully matching API_KEY and LOCATION_ID.

Links Database Access
Registry based credentials
Access to the Links database is via Links registry settings. If the connection type DBNT is not true, then the Password variable is decoded using the algorithm provided by links. This ensures that the API is plug and play and works with minimal configuration. HKEY_LOCAL_MACHINE\\SOFTWARE\\LMS\\Links\\Links\\Setup\\DBName HKEY_LOCAL_MACHINE\\SOFTWARE\\LMS\\Links\\Links\\Setup\\DBNT HKEY_LOCAL_MACHINE\\SOFTWARE\\LMS\\Links\\Links\\Setup\\Password HKEY_LOCAL_MACHINE\\SOFTWARE\\LMS\\Links\\Links\\Setup\\Server HKEY_LOCAL_MACHINE\\SOFTWARE\\LMS\\Links\\Links\\Setup\\TrainDBName HKEY_LOCAL_MACHINE\\SOFTWARE\\LMS\\Links\\Links\\Setup\\UserId

Data Querying
The API utilises NO legacy Links Stored procedures, SQL or views. All queries are custom written. Simple CRUD operations are auto generated for rapid application development.

SOAP AUTOMATIC UPDATES

The Links SOAP Service will be automatically updated when a SOAP Service update has been deployed, provided that the IP & Port rules have been implemented to allow automatic updates.

When the IP & Port rules implemented do not allow automatic updates, you will need to manually update your SOAP Service by obtaining the new SOAP Service files and following the Manual SOAP Service Updates knowledgebase article to complete the update.