Quick Start

A guide to help you get up & running with the Keyfax SOAP API.

These pages detail the processes to launch Keyfax and to obtain the diagnostic results. Both the launching of Keyfax and returning the results are processed through the KeyfaxWS web service. This is the preferred/recommended solution for all future integrations, be those with host Housing Management Systems or online portals.

NOTE We recommend use of the Keyfax SOAP based web services under the HTTPS protocol. You may also wish to consider using the Keyfax REST API instead.

In essence, this is the sequence of events...

The SOAP based web services flow.

Startup

Parameters

• startupXml=string

The Startup web method is a SOAP call which takes a single string* parameter containing the appropriate start-up data in XML format.

*Although we try to adhere to a standard generic XML schema, there have, and will continue to be, exceptions and by passing a string this avoids the need for separate webservice descriptors (WSDL).

ReturnUrl Query String Parameters

The start-up xml ReturnUrl value can have up to 4 query string parameters included to help the host system/portal retrieve the results. These can be included directly in the ReturnUrl value with placeholders "{n}" as follows:

• {0} replaced with the ResultStatus

• {1} replaced with the company config code

• {2} replaced with the GUID

• {3} replaced with the userId

E.g. a ReturnUrl could be sent in the start-up xml with parameters as follows:

• status={0}&co={1}&guid={2}

If a ReturnUrl is sent in the start-up xml with no placeholders specified, the following parameters will automatically be added:

• status={0}&guid={2}

Startup Response

The Startup web service returns a LaunchUrl and GUID. The launchUrl already contains the GUID as a query string parameter and can be used unmodified to launch Keyfax. The GUID is provided separately as it may be of use in future extensions to the integration.

In case of an error, a single ErrorText element is returned with an appropriate error description. Further details will be recorded in the Keyfax error log for further investigation if required.

Startup Return Xml:

<?xml version="1.0" encoding="utf-8"?>  
<WSStartupGuid xmlns="http://keyfax.touch-base.com/">  
  <Guid>string</Guid>  
  <LaunchUrl>string</LaunchUrl>  
</WSStartupGuid>    

Error Return Xml:

<?xml version="1.0" encoding="utf-8"?>  
<WSStartupGuid xmlns="http://keyfax.touch-base.com/">  
  <ErrorText>string</ErrorText>  
</WSStartupGuid>

GetResults

Parameters

• company=string

• guid=string

The GetResults web method requires a Company and a GUID parameter to retrieve the results. The Company must match the Company value passed in the original start-up xml and the GUID value must match the GUID passed as a query string parameter on the return url (as provided in the original start-up xml).

GetResults returns a ResultStatus and ResultXml string containing the diagnostic result xml. As with Startup, in case of an error a single ErrorText element is returned with an appropriate error description.

GetResults Response

<?xml version="1.0" encoding="utf-8"?>  
<WSGetResult xmlns="http://keyfax.touch-base.com/">  
  <ResultStatus>string</ResultStatus>  
  <ResultXml>string</ResultXml>  
</WSGetResult>  

GetResults Error Response

<?xml version="1.0" encoding="utf-8"?>  
<WSGetResult xmlns="http://keyfax.touch-base.com/">  
  <ErrorText>string</ErrorText>  
</WSGetResult>  

The ResultStatus = "1" indicates completed and "2" indicates a cancelled script. A sample for each status is given in the following sections.

A completed script sample as returned in the ResultXml string can be found within the XML Schemas section.

Notes:

Multiple Repair, Advice, Action and SubAction elements can be returned.

Examples:

• Cancelled script sample as returned in the ResultXml string can be viewed within the XML Schemas section.

• An enquiry which has generated a Note task can be viewed within the XML Schemas section.