Start-Up Data
The mode, company & scriptSet attributes provided within the examples below would need to be updated & configured correctly to match your Keyfax configuration. Please contact Omfax Systems for assistance preparing your Keyfax start-up data.
The minimal start-up data required in order for Keyfax to return launch data is shown below. These examples are only provided for demonstration purposes and start-up data should be tailored to suit your environment & integration.
You would pass start-up data into POST /api/v1/startup to obtain Keyfax launch data allowing you to launch a Keyfax session. Example minimal start-up data in both JSON & XML is provided below.
JSON
var startUpData = {
mode: { value: "RD" },
userName: { value: "administrator" },
password: { value: "" },
company: { value: "RDFL_Dev" },
scriptSet: { value: "RD" }
};XML
<?xml version="1.0" encoding="UTF-8"?>
<StartUpData>
<Mode>
<Value>RD</Value>
</Mode>
<UserName>
<Value>administrator</Value>
</UserName>
<Password>
<Value>Global</Value>
</Password>
<Company>
<Value>RDFL_Dev</Value>
</Company>
<ScriptSet>
<Value>RD</Value>
</ScriptSet>
</StartUpData>Posting Start-Up Data
Whilst you will always need to provide a minimal set of start-up data it's also possible to post custom start-up data into Keyfax. This custom start-up data can be used within Keyfax to provide dynamic or intelligent scripting. Any supplied custom start-up data can also be flowed through Keyfax and made available again within the final results produced by Keyfax when calling POST /api/v1/results.
The example start-up JSON below demonstrates how to include custom data within the request to POST /api/v1/startup via the Keyfax Web API JavaScript SDK...
{
"mode":{
"value":"RD"
},
"userName":{
"value":"administrator"
},
"password":{
"value":"Global"
},
"company":{
"value":"RDFL_Dev"
},
"scriptSet":{
"value":"RD"
},
"customData":{
"key":"CustomData",
"children":[
{
"key":"CustomFields1",
"children":[
{
"key":"CustomField1",
"value":"Example Value 1"
},
{
"key":"CustomField2",
"value":"Example Value 2"
}
]
},
{
"key":"CustomFields2",
"children":[
{
"key":"CustomField1",
"value":"Example Value 1"
},
{
"key":"CustomField2",
"value":"Example Value 2"
}
]
}
]
}
}The example C# code below shows how to build this same custom start-up data using the strongly typed Keyfax Web API .NET SDK...
// Build a sample JSON payload, values are hard coded as this is for demonstration purposes only
var startUpData = new StartUpData()
{
Mode = new StartUpDataItem()
{
Value = "RD"
},
UserName = new StartUpDataItem()
{
Value = "administrator"
},
Password = new StartUpDataItem()
{
Value = "Global"
},
Company = new StartUpDataItem()
{
Value = "RDFL_Dev"
},
ScriptSet = new StartUpDataItem()
{
Value = "RD"
},
CustomData = new StartUpDataItem()
{
Key = "CustomData",
Children = new List<StartUpDataItem>()
{
new StartUpDataItem()
{
Key = "CustomFields1",
Children = new List<StartUpDataItem>()
{
new StartUpDataItem()
{
Key = "CustomField1",
Value = "Child Example Value 1"
},
new StartUpDataItem()
{
Key = "CustomField2",
Value = "Child Example Value 2"
}
}
},
new StartUpDataItem()
{
Key = "CustomFields2",
Children = new List<StartUpDataItem>()
{
new StartUpDataItem()
{
Key = "CustomField1",
Value = "Child Example Value 1"
},
new StartUpDataItem()
{
Key = "CustomField2",
Value = "Child Example Value 2"
}
}
},
}
},
};Start Up Data Examples
Below we've provided several examples showing the start-up data you would typically supply to Keyfax. These are just examples to help demonsteate what's possible. The start-up data you provide to Keyfax would typically be customized based on your integration.
Minimal Start-Up Data Examples
Staff (RD / FL)
{
"originatingSystem": {
"value": "https://yourdomain.com/"
},
"company": {
"value": "Staff_Live"
},
"mode": {
"value": "RD"
},
"userName": {
"value": "operator"
},
"password": {
"value": "Global"
},
"scriptSet": {
"id": "scriptSetCode",
"value": "RD"
}
}Online (ROL / EOL)
{
"originatingSystem": {
"value": "https://yourdomain.com"
},
"company": {
"value": "Online_Live"
},
"mode": {
"value": "ROL"
},
"userName": {
"value": "KFROL_User"
},
"password": {
"value": ""
},
"scriptSet": {
"id": "scriptSetCode",
"value": "ROL"
}
}Full Start- Up Data Examples
The below illustrates some realistic start-up data you would typically post to Keyfax via /api/v1/startup. This is only to serve as an example and to show what's possible. Host systems would typically work with Omfax Systems to craft this start-up data based on your specific requirements & configuration.
Staff (RD/FL)
{
"originatingSystem": {
"value": "https://yourdomain.com"
},
"company": {
"value": "Staff_Live"
},
"mode": {
"value": "RD"
},
"scriptSet": {
"value": "RD"
},
"userName": {
"value": "operator"
},
"password": {
"value": "Global"
},
"returnUrl": {
"value": "https://yourdomain.com/keyfax-completed?status={0}&co={1}&guid={2}&user={3}"
},
"tenant": {
"value": "James Sopher, 12 Teal Road, Parkstone, Poole, Dorset, BH14 8UB"
},
"assetId": {
"value": "T20"
},
"callerDetails": {
"children": [
{
"key": "CallerID",
"value": "CE21A"
},
{
"key": "FirstName",
"value": "James"
},
{
"key": "LastName",
"value": " Sopher"
},
{
"key": "CallerEmail",
"value": "jsopher1987@gmail.com"
},
{
"key": "Mobile",
"value": "07555 499877"
},
{
"key": "DOB",
"value": "1987-05-24T00:00:00.000Z"
},
{
"key": "Vulnerable",
"value": "N"
},
{
"key": "MobilityIssues",
"value": "N"
},
{
"key": "Vulnerability",
"value": ""
},
{
"key": "GenderPronoun",
"value": "he/him"
},
{
"key": "Financials",
"children": [
{
"key": "Rent",
"value": 145
},
{
"key": "CurrentBalance",
"value": 345
}
]
}
]
},
"tenancyDetails": {
"children": [
{
"key": "TenureType",
"value": "Assured"
},
{
"key": "HousingOfficer",
"value": "Tina Jones"
}
]
},
"property": {
"children": [
{
"key": "AddressLine1",
"value": "12 Teal Road"
},
{
"key": "AddressLine2",
"value": "Parkstone"
},
{
"key": "AddressLine3",
"value": "Poole"
},
{
"key": "AddressLine4",
"value": "Dorset"
},
{
"key": "AddressLine5",
"value": "BH14 8UB"
},
{
"key": "HeatingType",
"value": "Gas"
},
{
"key": "ComponentData",
"children": [
{
"key": "Component",
"children": [
{
"key": "Type",
"value": "Gas Boiler"
},
{
"key": "Make",
"value": "Worcester"
},
{
"key": "Model",
"value": "Greenstar 30"
},
{
"key": "InstallDate",
"value": "2020-03-24T00:00:00.000Z"
},
{
"key": "WarrantyPeriod",
"value": "24"
},
{
"key": "WarrantyExpiryDate",
"value": "2022-03-24T00:00:00.000Z"
},
{
"key": "NextServiceDate",
"value": "2035-03-24T00:00:00.000Z"
}
]
}
]
},
{
"key": "PlannedMaintenance",
"children": [
{
"key": "PMJob",
"children": [
{
"key": "ProgrammeDescription",
"value": "Windows"
},
{
"key": "NextPlannedDate",
"value": "03/01"
}
]
}
]
}
]
}
}Online (ROL/EOL)
{
"originatingSystem":{
"value":"https://yourdomain.com"
},
"company":{
"value":"Online_Live"
},
"mode":{
"value":"ROL"
},
"scriptSet":{
"value":"ROL"
},
"userName":{
"value":"KFROL_User"
},
"password":{
"value":""
},
"returnUrl":{
"value":"https://yourdomain.com/keyfax-completed?status={0}&co={1}&guid={2}&user={3}"
},
"tenant":{
"value":"James Sopher, 12 Teal Road, Parkstone, Poole, Dorset, BH14 8UB"
},
"assetId":{
"value":"T20"
},
"callerDetails":{
"children":[
{
"key":"CallerID",
"value":"CE21A"
},
{
"key":"FirstName",
"value":"James"
},
{
"key":"LastName",
"value":" Sopher"
},
{
"key":"CallerEmail",
"value":"jsopher1987@gmail.com"
},
{
"key":"Mobile",
"value":"07555 499877"
},
{
"key":"DOB",
"value":"1987-05-24T00:00:00.000Z"
},
{
"key":"Vulnerable",
"value":"N"
},
{
"key":"MobilityIssues",
"value":"N"
},
{
"key":"Vulnerability",
"value":""
},
{
"key":"GenderPronoun",
"value":"he/him"
},
{
"key":"Financials",
"children":[
{
"key":"Rent",
"value":145
},
{
"key":"CurrentBalance",
"value":345
}
]
}
]
},
"tenancyDetails":{
"children":[
{
"key":"TenureType",
"value":"Assured"
},
{
"key":"HousingOfficer",
"value":"Tina Jones"
}
]
},
"property":{
"children":[
{
"key":"AddressLine1",
"value":"12 Teal Road"
},
{
"key":"AddressLine2",
"value":"Parkstone"
},
{
"key":"AddressLine3",
"value":"Poole"
},
{
"key":"AddressLine4",
"value":"Dorset"
},
{
"key":"AddressLine5",
"value":"BH14 8UB"
},
{
"key":"HeatingType",
"value":"Gas"
},
{
"key":"ComponentData",
"children":[
{
"key":"Component",
"children":[
{
"key":"Type",
"value":"Gas Boiler"
},
{
"key":"Make",
"value":"Worcester"
},
{
"key":"Model",
"value":"Greenstar 30"
},
{
"key":"InstallDate",
"value":"2020-03-24T00:00:00.000Z"
},
{
"key":"WarrantyPeriod",
"value":"24"
},
{
"key":"WarrantyExpiryDate",
"value":"2022-03-24T00:00:00.000Z"
},
{
"key":"NextServiceDate",
"value":"2035-03-24T00:00:00.000Z"
}
]
}
]
},
{
"key":"PlannedMaintenance",
"children":[
{
"key":"PMJob",
"children":[
{
"key":"ProgrammeDescription",
"value":"Windows"
},
{
"key":"NextPlannedDate",
"value":"03/01"
}
]
}
]
}
]
}
}Custom Start-Up Data
You can supply custom / non-standard fields within the Keyfax start-up JSON using the customData property as shown below...
"customData": {
"key": "CustomRoot1",
"children": [
{
"key": "CustomRoot1_Child1",
"value": "Child 1 Value",
},
{
"key": "CustomRoot1_Child2",
"value": "Child 2 Value",
}
]
}This will be converted to the following start-up XML...
<CustomRoot1>
<CustomRoot1_Child1>Child 1 Value</CustomRoot1_Child1>
<CustomRoot2_Child1>Child 2 Value</CustomRoot1_Child1>
</CustomRoot1>This would then be accessible within Keyfax via import data boxes (i.e.e //CustomData/CustomRoot1/CustomRoot1_Child1/@text())
You can also nest custom properties as demonstrated below...
"customData": {
"key": "CustomProperty",
"children": [
{
"key": "Children",
"children": [
{
"key": "Child1",
"value": "Child 1 Value",
},
{
"key": "Child2",
"value": "Child 2 Value",
}
]
}
]
}This will produce the following start-up XML...
<CustomProperty>
<Children>
<Child1>Child 1 Value</Child1>
<Child2>Child 2 Value</Child2>
</Children>
</CustomProperty>Custom Start Up Data Example
Consider the following start-up JSON...
{
"originatingSystem": {
"value": "LaunchExample"
},
"company": {
"value": "LiveWest_Online_Test"
},
"mode": {
"value": "ROL"
},
"userName": {
"value": "KFROL_User"
},
"password": {
"value": ""
},
"returnUrl": {
"value": "http://keyfaxtest.com:8011/Completed.html?status={0}&co={1}&guid={2}&user={3}"
},
"assetId": {
"value": "0"
},
"clientId": {
"value": "0"
},
"customData": {
"key": "CustomData",
"children": [
{
"key": "TenancyTypeDescription",
"value": "Example tenancy type description"
},
{
"key": "CategoryTypeDescription",
"value": "Example category type description"
},
{
"key": "ActualHandoverDate",
"value": "2023-06-01"
}
]
}
}This would actually be supplied to Keyfax as XML in the form...
<KeyfaxData>
<Startup>
<OriginatingSystem>LaunchExample</OriginatingSystem>
<Mode>ROL</Mode>
<UserName>KFROL_User</UserName>
<Password />
<Company>LiveWest_Online_Test</Company>
<ClientId>0</ClientId>
<ReturnURL>
<![CDATA[http://keyfaxtest.com:8011/Completed.html?status={0}&co={1}&guid={2}&user={3}]]>
</ReturnURL>
<AssetID>0</AssetID>
<CustomData>
<TenancyTypeDescription>Example tenancy type description</TenancyTypeDescription>
<CategoryTypeDescription>Example category type description</CategoryTypeDescription>
<ActualHandoverDate>2023-06-01</ActualHandoverDate>
</CustomData>
<GUID>
<![CDATA[9f360185-82a1-4121-aa5b-ca3d0f4e1452]]>
</GUID>
<ScriptSet>
<![CDATA[ROL]]>
</ScriptSet>
<ROLDetail>
<![CDATA[]]>
</ROLDetail>
</Startup>
</KeyfaxData>So to access values within the <CustomData/> element you can use XPath expressions within existing Import data boxes as shown below...
Exporting Custom Start-Up Data
If you supply custom start-up data and wish to expose this within results produced by Keyfax the export template used by Keyfax will need to be updated to include any custom start-up data.
We would always suggest contacting Omfax Systems to better understand your requirements. We will work with you to tailor your start-up & export data to suit your integration and ensure you get the most from Keyfax.
Last updated