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": "[email protected]"
			},
			{
				"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":"[email protected]"
         },
         {
            "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...

Using Start-Up Data Within a Keyfax Script via Import Databoxes

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.