Beacon Web Service Whitepaper

Overview

The beacon web service delivers the locations of the services required by the Simplicity desktop application. These services are then accessed at these locations first attempting on the first returned location for the required service, then the second and so forth.

This service is hosted by Simplicity and is not installed internally to any client networks. As an integral part of the Simplicity service this can deliver multiple fallback service locations for any of the required services. These can be different by client and also can return differentiating results for the development, test and production environments. The methods take the ClientID and the CodeSet to determine the appropriate response.

On each communication with the beacon service a file is created “BWSCache.dat” which is encrypted multiple times to ensure its validity. This file contains the information returned from the beacon service which contains the required Simplicity service locations which is also likely to include backup locations for the beacon service itself.

When the Simplicity desktop application starts up, if the cache file is present, it will use this file and firstly identify any beacon services locations specified in the file. If it finds entries for the beacon service in the cache file it will communicate with these firstly in preference to communicating with the default beacon service.

If no beacon service can be communicated with, including the default beacon service, and a cache file is present then all the required Simplicity services will be communicated to at the locations specified in the cache file created from the last communication.

In the event there has never been a successful communication with the beacon service and no communication can be established with the default beacon service then the Simplicity desktop application will not be able to be used until an initial connection with the beacon service is made.

Communication is performed with the beacon service at the initial startup of the Simplicity desktop application and returned results are cached for a configurable period of time, typically a week.

Current service locations published through the beacon service are:

Beacon Service – What is accessible where
Sentinel Service – Are they authorized to access Simplicity
File Management Service – “Online Library” and “Online Form” publishing
Assembly Info Service – What DLL’s are current
Upgrade Service – Startup component updates
Right Address Service – “Rapid Keying” and “Address Cleaning”
Reporting Services – Simplicity

Simplicity beacon web service is accessed via https on port 443 at the following primary url: https://beacon.simplicitycrm.com/beaconsvc.asmx

or alternatively via http on port 80 at the following primary url:
http://beacon.simplicitycrm.com/beaconsvc.asmx

Accessibility Diagram

The web service and application DLL’s are accessed via standard web requests from the Simplicity desktop application to the Simplicity Beacon server as illustrated.

Web Service Method Definitions

The following methods are supported by this web service.

·LocateAllServices

·LocateService

Web Service Method - LocateAllServices

SOAP 1.1

The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values.

POST /beaconsvc.asmx HTTP/1.1

Host: beacon.simplicitycrm.com

Content-Type: text/xml; charset=utf-8

Content-Length: length

SOAPAction: "http://services.simplicitycrm.com/Beacon/LocateAllServices"

<?xml version="1.0" encoding="utf-8"?>

<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>

<Key>string</Key>

<CodeSet>string</CodeSet>

</LocateAllServices>

</soap:Body>

</soap:Envelope>

HTTP/1.1 200 OK

Content-Type: text/xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<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>

<ServiceName>string</ServiceName>

</ServiceLocation>

<ServiceName>string</ServiceName>

</ServiceLocation>

</Locations>

<ExpirationTimeInDays>double</ExpirationTimeInDays>

<ExpirationWarningTimeInDays>double</ExpirationWarningTimeInDays>

</LocateAllServicesResult>

</LocateAllServicesResponse>

</soap:Body>

</soap:Envelope>

SOAP 1.2

POST /beaconsvc.asmx HTTP/1.1

Host: beacon.simplicitycrm.com

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<Key>string</Key>

<CodeSet>string</CodeSet>

</LocateAllServices>

</soap12:Body>

</soap12:Envelope>

HTTP/1.1 200 OK

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<ServiceName>string</ServiceName>

</ServiceLocation>

<ServiceName>string</ServiceName>

</ServiceLocation>

</Locations>

<ExpirationTimeInDays>double</ExpirationTimeInDays>

<ExpirationWarningTimeInDays>double</ExpirationWarningTimeInDays>

</LocateAllServicesResult>

</LocateAllServicesResponse>

</soap12:Body>

</soap12:Envelope>

Web Service Method - LocateService

SOAP 1.1

The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values.

POST /beaconsvc.asmx HTTP/1.1

Host: beacon.simplicitycrm.com

Content-Type: text/xml; charset=utf-8

Content-Length: length

SOAPAction: "http://services.simplicitycrm.com/Beacon/LocateService"

<?xml version="1.0" encoding="utf-8"?>

<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>

<Key>string</Key>

<CodeSet>string</CodeSet>

<Service>string</Service>

</LocateService>

</soap:Body>

</soap:Envelope>

HTTP/1.1 200 OK

Content-Type: text/xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<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>

<string>string</string>

</Locations>

<ServiceName>string</ServiceName>

</LocateServiceResult>

</LocateServiceResponse>

</soap:Body>

</soap:Envelope>

SOAP 1.2

POST /beaconsvc.asmx HTTP/1.1

Host: beacon.simplicitycrm.com

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<Key>string</Key>

<CodeSet>string</CodeSet>

<Service>string</Service>

</LocateService>

</soap12:Body>

</soap12:Envelope>

HTTP/1.1 200 OK

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<string>string</string>

</Locations>

<ServiceName>string</ServiceName>

</LocateServiceResult>

</LocateServiceResponse>

</soap12:Body>

</soap12:Envelope>

Web Service Setup & Configuration

Multiple configuration documents are present in the ~\APP_DATA\ web service folder. The returned results are the prioritisedsuperset of all the configuration documents matching the supplied ClientID and CodeSet. The result location ordering returned is based on the “Rank” attribute with the higher the number, the higher the priority.

~\APP_DATA\DEFAULT.XML

The following is a sample of beacons’s default.xml file.

<?xml version="1.0" encoding="utf-8" ?>

<ClassName>Beacon.SABeaconConfiguration,Beacon</ClassName>

<PermitOrDeny>Permit</PermitOrDeny>

<AfterPermit>ContinueProcessing</AfterPermit>

<AfterDeny>StopProcessing</AfterDeny>

<ClassName>Beacon.SABeaconServiceConfigurationCollection,Beacon</ClassName>

<ItemClassName>Beacon.SABeaconServiceConfiguration,Beacon</ItemClassName>

<Items>

<Item>

<Service>Beacon</Service>

<PermitOrDeny>Permit</PermitOrDeny>

<AfterPermit>ContinueProcessing</AfterPermit>

<AfterDeny>StopProcessing</AfterDeny>

<ClassName>Beacon.SABeaconServiceLocationCollection,Beacon</ClassName>

<ItemClassName>Beacon.SABeaconServiceLocation,Beacon</ItemClassName>

<Items>

<Item>

<URL>https://beacon.simplicitycrm.com/BeaconSvc.asmx</URL>

</Item>

<Item>

<URL>http://beacon.simplicitycrm.com/BeaconSvc.asmx</URL>

</Item>

</Items>

</Locations>

</Item>

<Item>

<Service>Sentinel</Service>

<PermitOrDeny>Permit</PermitOrDeny>

<AfterPermit>ContinueProcessing</AfterPermit>

<AfterDeny>StopProcessing</AfterDeny>

<ClassName>Beacon.SABeaconServiceLocationCollection,Beacon</ClassName>

<ItemClassName>Beacon.SABeaconServiceLocation,Beacon</ItemClassName>

<Items>

<Item>

<URL>https://sentinel.simplicitycrm.com/SentinelSvc.asmx</URL>

</Item>

<Item>

<URL>http://sentinel.simplicitycrm.com/SentinelSvc.asmx</URL>

</Item>

</Items>

</Locations>

</Item>

<Item>

<Service>FileManagement</Service>

<PermitOrDeny>Permit</PermitOrDeny>

<AfterPermit>ContinueProcessing</AfterPermit>

<AfterDeny>StopProcessing</AfterDeny>

<ClassName>Beacon.SABeaconServiceLocationCollection,Beacon</ClassName>

<ItemClassName>Beacon.SABeaconServiceLocation,Beacon</ItemClassName>

<Items>

<Item>

<URL>http://services.simplicitycrm.com/FileManagement/IOService.asmx</URL>

</Item>

</Items>

</Locations>

</Item>

<Item>

<Service>AssemblyInfo</Service>

<PermitOrDeny>Permit</PermitOrDeny>

<AfterPermit>ContinueProcessing</AfterPermit>

<AfterDeny>StopProcessing</AfterDeny>

<ClassName>Beacon.SABeaconServiceLocationCollection,Beacon</ClassName>

<ItemClassName>Beacon.SABeaconServiceLocation,Beacon</ItemClassName>

<Items>

<Item>

<URL>http://services.simplicitycrm.net/AssemblyInfo/AssemblyInfoSvc.asmx</URL>

</Item>

</Items>

</Locations>

</Item>

<Item>

<Service>UpgradeScript</Service>

<PermitOrDeny>Permit</PermitOrDeny>

<AfterPermit>ContinueProcessing</AfterPermit>

<AfterDeny>StopProcessing</AfterDeny>

<ClassName>Beacon.SABeaconServiceLocationCollection,Beacon</ClassName>

<ItemClassName>Beacon.SABeaconServiceLocation,Beacon</ItemClassName>

<Items>

<Item>

<URL>http://www.simplicitycrm.net/SAUpgradeScript/SAUpgradeScript.asmx</URL>

</Item>

</Items>

</Locations>

</Item>

<Item>

<Service>RightAddress</Service>

<PermitOrDeny>Permit</PermitOrDeny>

<AfterPermit>ContinueProcessing</AfterPermit>

<AfterDeny>StopProcessing</AfterDeny>

<ClassName>Beacon.SABeaconServiceLocationCollection,Beacon</ClassName>

<ItemClassName>Beacon.SABeaconServiceLocation,Beacon</ItemClassName>

<Items>

<Item>

<URL>https://rightaddress.simplicitycrm.com/rightaddress.asmx</URL>

</Item>

<Item>

<URL>http://rightaddress.simplicitycrm.com/rightaddress.asmx</URL>

</Item>

</Items>

</Locations>

</Item>

</Items>

</Services>

</Beacon>

~\APP_DATA\CLIENT_SPECIFIC_FILES.XML

The following is a sample of the assembly info’s web.config file. The placeholders shown need to be replaced with actual values.

<?xml version="1.0" encoding="utf-8" ?>

<ClassName>Beacon.SABeaconConfiguration,Beacon</ClassName>

<ClientID>ClientID</ClientID>

<CodeSet>CodeSet</CodeSet>

<PermitOrDeny>Permit</PermitOrDeny>

<AfterPermit>ContinueProcessing</AfterPermit>

<AfterDeny>StopProcessing</AfterDeny>

<ClassName>Beacon.SABeaconServiceConfigurationCollection,Beacon</ClassName>

<ItemClassName>Beacon.SABeaconServiceConfiguration,Beacon</ItemClassName>

<Items>

<Item>

<Service>FileManagement</Service>

<PermitOrDeny>Permit</PermitOrDeny>

<AfterPermit>StopProcessing</AfterPermit>

<AfterDeny>StopProcessing</AfterDeny>

<ClassName>Beacon.SABeaconServiceLocationCollection,Beacon</ClassName>

<ItemClassName>Beacon.SABeaconServiceLocation,Beacon</ItemClassName>

<Items>

<Item>

<URL>http://Your.AlternativeServiceLocation.Sample/FileManagement/IOService.asmx</URL>

</Item>

</Items>

</Locations>

</Item>

</Items>

</Services>

</Beacon>

Service Workflow

BEACON SERVICE INITIAL COMMUNICATION DATAFLOW

The initial beacon service connection workflow is shown next.

This initial connection to the Simplicity beacon service is required before the desktop client will be able to run and connect to the Simplicity client database.

It requires this initial connection in order to know where to connect to for any of the Simplicity services.

BEACON SERVICE SUBSEQUENT COMMUNICATIONS DATAFLOW

The desktop application first checks to see if there is a cache file and if so it will then use the beacon services listed in the file. If there are no beacon services listed in the file or if the desktop application is unable to connect to the beacon services listed then the default beacon location is used.

BEACON SERVICE UNAVAILABILITY DATAFLOW

Should the beacon service be temporarily unavailable, application use can continue as shown below. This is only possible where a connection to a beacon service has previously completed successfully.

Beacon Web Service API

Beacon Web Service Whitepaper

Overview

Accessibility Diagram

Web Service Method Definitions

Web Service Method - LocateAllServices

Web Service Method - LocateService

Web Service Setup & Configuration

Service Workflow