Startup Schema
All the supported start-up data supported by Keyfax.
This section details the start-up (Startup) information required for a Keyfax "session", and is intended as a definitive guide to how to pass input data to Keyfax from a Housing Management System or other calling application (Host). This schema should be used whilst testing Integration scenarios, and as a general reference. This is a SOAP call.
Keyfax can be launched via the SOAP API or REST API and it will require populated startup data as described below.
Basic SOAP Requests
Below we've provided an example minimal SOAP request to help you get started using the Keyfax SOAP based API. Examples are provided for both Keyfax Staff & Keyfax Self-Service.
The minimal values are described below...
Company - Please contact Omfax Systems for this information. This will vary depending on the installation being used. This is typically in the form Customer_Module_Environment - for example
AbcHousing_Staff_Live.ReturnUrl - The URL Keyfax will return back to after the script has been completed or cancelled. If omitted Keyfax will return to a standardized completion page.
Mode - Depending on your Keyfax configuration valid values include
RD,FL,ROL,EOL. Please contact Omfax Systems to confirm exactly which mode you should use.OriginatingSystem - This can be any string value and is simply used to distinguish requests across different systems. We would suggest using the name of your host system for this value.
Launching Repairs Self Service (ROL)
The below illustrates how to obtain launch details for a Keyfax Self Service Repairs Online session. This only contains the very minimal start-up data and additional data can be provided as detailed within the "Full Schema" section further below.
URL
https://keyfax.yourdomain.com/interview/ws/keyfaxws.asmx
SOAP BODY
Launching Repair Diagnostics (RD)
The below illustrates how to obtain launch details for a Keyfax Repairs Diagnostics session. This only contains the very minimal start-up data and additional data can be provided as detailed within the "Full Schema" section further below.
URL
https://keyfax.yourdomain.com/interview/ws/keyfaxws.asmx
SOAP BODY
Full Schema
Note the schema describes a 'base' schema and is subject to change.
<KeyfaxData test="0" version="1.1">
Set test="1" for test environments only
<Startup>
<OriginatingSystem>My Housing System</OriginatingSystem>
Name of Host System passing Start-up.xml
<Mode>RD</Mode>
Typical Modes are: RD Repair diagnostics FL Front-line enquiries ROL Repairs on-line EOL Enquiries on-line
<UserName>Operator</UserName>
Session based User ID text (must be the same value as used in session XMLHTTP calls). This person must be established as a user in Inter•View by (via the Administrator Tools). Note: in some integrations, it is not practical to supply a valid/registered username, e.g. Repairs Online; in these cases, default usernames would be established so this node can be left blank.
<Password></Password>
User password as setup in Keyfax Admin Tools. Alternatively, a single global (configurable) password can be used or the interface can authenticate with a valid UserName only.
<Company>Keyfax Configuration Code</Company>
A Keyfax configuration code. This reverted back from 'Config' on 09/11/2015,
<ClientID>MyHMSClient</ClientID>
A Client ID to use if the Host manages calls for multiple clients
<ScriptSet>1</ScriptSet>
Code representing the tenure type for the caller.
<Category>Optional Startup Category Name</Category>
Mandatory if a Topic is passed
<Topic>Optional Startup TopicName</Topic>
Category is mandatory if a Topic is passed
<ReturnURL>http://xxx.com/Page.aspx?status={0}&co={1}&guid={2}</ReturnURL>
Webpage to display on completion
<CallerDetails isTenant="Y" >
Caller Details
<CallerID>123456</CallerID>
Caller unique identifier
<Caller>RUPERT JONES,21 The Causeway,Bicester,OXON,B23 7AS</Caller>
Caller Name and Address
<Title>MR</Title>
Caller Title
<FirstName>Rupert</FirstName>
Caller First Name
<LastName>Jones</LastName>
Caller Last Name
<DOB>16-12-1976</DOB>
Caller Date of Birth
<MainTelephone>01869242967</MainTelephone>
Caller Main Telephone number
<HomeTelNo>01234 555 666</HomeTelNo>
Caller Home Telephone number
<WorkTelNo>01869 242 967</WorkTelNo>
Caller Work Telephone number
<Mobile>07779235451</Mobile>
Caller Mobile number
<Email>RJ@hotmail.org</Email>
Caller Email address
<Notes>If not available at main Contact number, please try on Mobile phone.</Notes>
Notes relevant to caller
<Financials>
Financial section
<CurrentBalance>445.54</CurrentBalance>
Caller current rent balance
<EligibleRent>112.50</EligibleRent>
<Contributions>74.35</Contributions>
<RegularPaymentMethod>DIRECTDEBIT</RegularPaymentMethod>
Caller method of rent payment
</Financials>
<Alert Type="xxx" Severe="yes/no" Level="xxx">Visually Impaired</Alert>
<Alert Type="xxx" Severe="yes/no" Level="xxx">Blind</Alert>
<Dependent>
Caller Dependant details
<Name></Name>
Caller Dependant Name
<DOB></DOB>
Caller Dependant Date of Birth
<Sex></Sex>
Caller Dependant Sex
<Alert Type="xxx" Severe="yes/no" Level="xxx">Visually Impaired</Alert>
<Alert Type="xxx" Severe="yes/no" Level="xxx">Blind</Alert>
</Dependent>
</CallerDetails>
<TenancyDetails>
Details of Caller's tenancy
<Tenancy>STD</Tenancy>
Tenancy Code
<TenancyType>Assured</TenancyType>
Tenancy Type
<Tenure_Code>1</Tenure_Code>
Tenure Code
<OnMutualExchangeRegister>N</OnMutualExchangeRegister>
Is Caller on the Mutual Exchange Register?
<OnTransferRegister>N</OnTransferRegister>
Is Caller on the Transfer Register?
<TenancyCommencementDate>2015/01/01</TenancyCommencementDate>
Date of Tenancy Commencement
<HousingOfficer>John Smith</HousingOfficer>
Tenant Housing Officer Name
<MainTenant>Y</MainTenant>
Is Caller the Main Tenant?
<JointTenant TenantId="xxx">
Joint Tenant details
<Title>MR</Title>
Joint Tenant Title
<FirstName>Rupert</FirstName>
Joint Tenant First Name
<LastName>Jones</LastName>
Joint Tenant Last Name
<DOB>1976-01-01</DOB>
Joint Tenant Date of Birth
<MainTelephone>01869242967</MainTelephone>
Joint Tenant Main Telephone number
<HomeTelNo>01234 555 666</HomeTelNo>
Joint Tenant Home Telephone number
<WorkTelNo>01869 242 967</WorkTelNo>
Joint Tenant Work Telephone number
<Mobile>07779235451</Mobile>
Joint Tenant Mobile number
<Email>RJ@hotmail.org</Email>
Joint Tenant Email address
<Alert Type="xxx" Severe="yes/no" Level="xxx">Visually Impaired</Alert>
<Alert Type="xxx" Severe="yes/no" Level="xxx">Blind</Alert>
</JointTenant>
</TenancyDetails>
<PropertyID>616161</PropertyID>
Unique Property ID
<Property>
<AddressLine1>21 THE CAUSEWAY</AddressLine1>
Tenant Property Address
<AddressLine2></AddressLine2>
<AddressLine3></AddressLine3>
<AddressLine4></AddressLine4>
<AddressLine5></AddressLine5>
<City>BICESTER</City>
Tenant Property City
<County>OXON</County>
Tenant Property County
<Postcode>OX26 6AN</Postcode>
Tenant Property Postcode
<DefaultContractor id="xxx">Willmott Dixon</DefaultContractor>
Default Contractor for Tenant
<Contractor id="xxx" trade="Gas">PHJONESN</Contractor>
Contractor and Trade
<ConstructionDate>2015-01-01</ConstructionDate>
Construction Date of Tenant Property
<InDefectLiabilityPeriod>Y</InDefectLiabilityPeriod>
Property in Defect Liability period?
<DefectLiabilityExpiryDate>2016-01-01</DefectLiabilityExpiryDate>
Defect Liability period expires on
<TotalBedrooms>3</TotalBedrooms>
Number of Bedrooms of Tenant Property
<PropertyLastGasServiceDate>2014-01-01</PropertyLastGasServiceDate>
Date of last gas service
<PropertyTypeCode>BLK</PropertyTypeCode>
Code for Property type
<PropertyTypeDescription>BLOCK</PropertyTypeDescription>
Type of Property (Block, Detached, Semi-Detached)
<BlockCode>66667</BlockCode>
Code for the Block if applicable
<Scheme_Code>S0234</Scheme_Code>
Code of Scheme the Property belongs to
<LA_Code>127</LA_Code>
Local Authority Code
<Road_Code>R0461</Road_Code>
Road Code
<ComponentData>
Data on Components within the Property
<Component>
<Description>HEATINGTYPE</Description >
Component Description
<Type>GASBOILER</Type>
Type of Component
<Make>Worcester</Make>
Make of Component
<Model>DW123</Model>
Model number of Component
<SerialNumber>7894546136 </SerialNumber>
Serial number of Component
<InstallDate>2010-01-01</InstallDate>
Date Component was installed
<WarrantyExpiryDate>2011-01-01</WarrantyExpiryDate>
Date Warranty of Component expires
<WarrantyNumber>21234</WarrantyNumber>
Unique Warranty number
<LastServiceDate></LastServiceDate>
Date of last service
<NextServiceDate></NextServiceDate>
Date of next service due
<Contractor></Contractor>
Contract responsible for Component
<Location></Location>
</Component>
<Component>
<Description>SHOWER</Description>
<Type>ELECTRIC</Type>
<Make>Honeywell</Make>
<Model>EL345</Model>
<SerialNumber>7894546136</SerialNumber>
<InstallDate>2010-01-01</InstallDate>
<WarrantyExpiryDate>2010-01-01</WarrantyExpiryDate>
<WarrantyNumber>21234</WarrantyNumber>
<LastServiceDate></LastServiceDate>
<NextServiceDate></NextServiceDate>
<Contractor>SHOWERSRUS</Contractor>
<Location></Location>
</Component>
</ComponentData>
<Adaptations>
<Adaptation Code="LIFT:STAIR">STAIR LIFT IN PROPERTY</Adaptation>
Adapation Notes
<Adaptation Code="HANDRAIL">HANDRAILS IN PROPERTY</Adaptation>
</Adaptations>
<PlannedMaintenance>
<PMJob>
<ProgrammeCode>GASSERVICING0607</ProgrammeCode>
<ProgrammeDescription>Servicing Of Gas Appliances 2006/07</ProgrammeDescription>
<Contractor>Enterprise</Contractor>
<ContractStatus>OPEN</ContractStatus>
<LastCompletedDate>2010-01-01</LastCompletedDate>
<WarrantyPeriod>12 months</WarrantyPeriod>
<NextPlannedDate>2011-01-01</NextPlannedDate>
</PMJob>
</PlannedMaintenance>
<ContactHistory Range="Last 10 months">
<CallType id="xxx">Repair</CallType>
<CallRef>987654321</CallRef>
<Status>COMPLETE</Status>
<Description>Heating</Description>
<RaisedDate>YYYY/MM/DD HH:MM</RaisedDate>
<TargetDate>YYYY/MM/DD HH:MM</TargetDate>
<CompletedDate>YYYY/MM/DD HH:MM</CompletedDate>
<Comments>Migrated from Works Order Ref.12345</Comments>
<ReferredTo>P H Jones Gas Servicing</ReferredTo>
<JobLineItem id="1">
<SoRCode>12345A</SoRCode>
<SoRShortDescription>Find Fault and Rectify</SoRShortDescription>
<Quantity>1</Quantity>
<Trade>GAS</Trade>
<PriorityCode>E</PriorityCode>
<Location>BEDROOM</Location>
</JobLineItem>
</ContactHistory>
<Warning Type="xx">Asbestos</Warning>
<Warning Type="xx">Violent history</Warning>
<Notes>If not available at main Contact number, please try on Mobile phone.</Notes>
</Property>
</Startup>
</KeyfaxData>
Last updated