3rd Party Integration, ActiveX OCX - Properties, methods and events

3rd Party Integration - ActiveX OCX - Properties, methods & events

Document data

Document Date:	28 July 2006 - revision 3
Keyfax version :	2.7.0.0 (or greater)
Software required:	IIS 5.0+, Internet Explorer 6.0+, SQL Server 2000+
User skill requirements:	NT administration. SQL Server DBA. IIS configuration. NT security policies. MSXML editing.
Author:	Technical Services keyfax@touch-base.com

Control Properties and Methods:

The following table lists the controls properties and methods available to the programmer. A brief description will outline any additional information to be considered when using the control to exchange data.

Name	Mode	Usage	Parameters	Returns	Notes
ActionCode	FL	Read only	Item (Long)	String	Keyfax action code (generated from script path)
ActionCodeDesc	FL	Read only	Item (Long)	String	FL action code description
ActionCount	FL	Read only	None	Long	Count of returned action code sections
Additional_Info	RD	Read only	None	String	RD additional information entered by user
AdviceCode	RD/FL	Read only	Item (Long)	String	RD/FL advice code (generated from script path)
AdviceCodeDesc	RD/FL	Read only	Item (Long)	String	RD/FL advice code description
AdviceCount	RD/FL	Read only	None	Long	Count of returned advice code sections
AdvicePlainText	RD/FL	Read only	Item (Long)	String	RD/FL advice code full message body text
Asset	RD	Read/write	Svalue (String)	File path	RD asset XML file. Must have <Asset> node.
AssetID	RD	Read/write	sValue (String)	String	Sets/gets the Asset ID for the current script.
AssetString	RD	Write only	Svalue (String)	String	RD asset XML string. Must have <Asset> node.
Bookmark	RD	Read/write	Svalue (String)	File path	RD bookmark XML file name (including path).
CloseExport	RD/FL		None	None	Used after returned XML data is read
Contractor	RD	Read Only	Item (Long)	String	RD repair code Contractor ID
Communal	RD	Read/write	sValue (String)	String	Sets/gets Communal start-up item (not currently used)
Communal_Type	RD	Read only	None	String	RD communal type returned from script
Company	RD/FL	Read/write	sValue (String)	String	If this property is to be used (by default Keyfax assumes a single company environment), it MUST be set EVERY TIME the Keyfax.OCX is launched, initialized or after the ‘InitStartup’ method is called. This property is only available in version 3.2.0.0 of the OCX or greater. If supplied, Keyfax will attempt to locate a configuration file of the same name, e.g. .Company = "HOSTCO01" will cause Keyfax to look for a configuration file named : HOSTCO01_CONFIG.XML
CompleteBy	RD	Read only	Item (Long)	String	RD complete by date for repair code returned
Contractor	RD	Read only	Item (Long)	String	RD/FL contractor for repair code returned
CustomCount	RD	Read only	None	Long	Count of returned custom code sections (under development)
EnquiryCategory	FL	Read only	None	String	FL enquiry script category title
EnquiryCatRef	FL	Read only	None	String	FL enquiry script category ID
EnquiryDialog	FL	Read only	None	String	FL enquiry script ID
EnquiryText	FL	Read only	None	String	FL enquiry script description (with recorded responses)
Export	RD/FL	Read/write	sValue (String)	String	Sets/gets export exchange method (only required if not XML)
ExportXML	RD/FL	Read only	None	XML Document	MSXML2 XML Document stream of export.xml
Fault_Dialog	RD	Read only	None	String	RD fault script ID
FaultText	RD	Read only	None	String	RD fault script description (with recorded responses)
GetBookmarkFolder	RD	Read only	None	String	Path to Keyfax Bookmark folder
GetKeyfaxWnd	RD/FL	Read only	None	Long	Windows Handle to Keyfax application
GetKeyfaxStatus	RD/FL	Read only	None	Long	Keyfax export status value from registry
GetKeyfaxStatusText	RD/FL	Read only	None	String	Keyfax export status value description
GetNodeByXPath	RD/FL	Read only	sXpath (String)	String	Return XML node text by specifying an Xpath query as parameter. (same as GetStartNodeByXPath)
GetSingleNode	RD/FL	Read only	sNode(String), sXPath(String)	String	Return XML node text by specifying sXPath ("Main" = no XPath required if sNode under Enquiry or Fault node, "Common" = no XPath required as sNode is under XML Root, otherwise full Xpath and then Node) and sNode (Name of Node to return text for)
GetStartNodeByXPath	RD/FL	Read only	sXpath (String)	String	Return XML node text by specifying an Xpath query as parameter. (same as GetNodeByXPath)
HasSubActions	FL	Read only	Item (Long)	Boolean	FL action section has sub action section(s) (see SubActionCode )
History	RD	Read/write	sValue (String)	File path	RD history XML file. Must validate to history.dtd file.
HistoryString	RD	Write only	Svalue (String)	String	RD history XML string. Must validate to history.dtd file.
InitStartup	RD/FL		None	None	Used before setting start-up data to clear last values
IsKeyfaxActive	RD/FL	Read only	None	Boolean	Check to see Keyfax is loaded into memory
IsKeyfaxActive2	RD/FL	Read only	None	Boolean	Check to see Keyfax is loaded into memory. This is the preferred method - it enumerates all open windows. Note: this will return True if the Keyfax Administrator Tools program (KFAdmin.exe) is loaded)
Item	RD/FL	Read/write	lValue (Long)	Long	Sets/gets current fault/enquiry (use for multiple faults/enquiries returned in export) by default is set at '1'
ItemCount	RD/FL	Read only	None	Long	Count of faults/enquiries returned in export data
LA_Code	FL	Read/write	sValue (String)	String	Sets/gets start-up Local Authority code for add-in database functions of FL
LaunchKeyfax	RD/FL		sParam (string)	Long	Used to start Keyfax, the sParam parameters are the usual startup command line parameters (ie '/S:XML /E:XML /M:RD /V:MIN /U:operator /P:Global /H:1'). Will return the Status.
LoadExport	RD/FL		None	None	Used to open export xml file prior to reading properties
LogDate	RD/FL	Read only	None	String	Date/time of script process (ie '30 /04/2001 13:45:14')
MainCustom	RD/FL	Read only	sNode (String)	String	Custom export node associated to the Repair/Enquiry data. The sNode parameter is used to define the XML Node name required (ie 'Location')
Mode	RD/FL	Read/write	sValue (String)	String	Sets/gets start-up Mode, sValue parameter = 'FL' or 'RD'. Mandatory in launch, start-up and export xml (this value must be set before any other properties are set or read) *Note: from version 3.2 RD/FL has superseded the previous modes 'Jobfax'/'Keyfax', although these can at present still be used.*
NotifyStatus	RD/FL		bToggle(Boolean)	None	Used to enable/disable StatusX event for early bound OCX integration
OAP_Disability	RD/FL	Read/write	sValue (String)	String	Sets/gets OAP disability start-up item (not currently used)
ParentActionCode	FL	Read only	Item (Long)	String	Identifies FL action code parent section from sub action section
Password	RD/FL	Read/write	sValue (String)	String	Sets/gets start-up user's password (mandatory in launch and start-up xml), this can use the Global password for users other than administrators
Priority	RD/FL	Read only	Item (Long)	String	RD repair/FL action code priority code
Reason_Code	RD	Read only	None	String	RD fault reason code
Reason_Text	RD	Read only	None	String	RD fault reason code description
Recharge	RD	Read only	None	String	RD fault repair is chargeable '1' or '0'
Recharge_Code	RD	Read only	None	String	RD fault recharge code (generated from script path)
Recharge_Cost	RD	Read only	None	String	RD fault recharge code description
Repair_No	RD	Read only	None	String	RD fault repair reference as passed from host
Repair_Status	RD	Read only	None	String	RD fault repair status (ie '2' = logged)
RepairCode	RD	Read only	Item (Long)	String	RD fault repair code (SOR code generated from script path)
RepairCodeDesc	RD	Read only	Item (Long)	String	RD fault repair code short description
RepairCount	RD	Read only	None	Long	Count of returned repair code sections
RepairNo	RD	Read/write	sValue (String)	String	Sets/gets start-up repair reference (optional in start-up xml), this value will be returned in export Repair_No item
Schedule_ID	RD	Read only	None	String	Recorded reference to script, for use in audits and orders.mdb
Scheme_Code	FL	Read/write	sValue (String)	String	Sets/gets start-up Housing Scheme code for add-in database functions of FL
ScriptPath	RD/FL	Read only	None	String	RD/FL script navigation path
SendStartup	RD/FL		None	None	Used once start-up properties have been set (this will generate the start-up xml file)
SetExportLoadRequestFlag	RD/FL		None	Boolean	Used to set export status to -4 at initial load for time out processing
SetStartupFlag	RD/FL		None	None	Used once start-up properties have been set and SendStartup method has been called (this will give Keyfax the focus for a script session)
Site_Visit	RD	Read only	None	String	RD instructions for site visit by contractor/inspector
Special_Instructions	RD	Read only	None	String	RD special instructions for contractor/inspector
Startup	RD/FL	Read/write	sValue (String)	String	Sets/gets start-up exchange method (only required if not XML)
StartupXML	RD/FL	Write only	oData (MSXML2 DomDocument)	None	MSXML2 XML Document object to load into startup.xml. note: SendStartup method not required.
Status	RD/FL	Read only	None	Long	FL/RD export status (see status section)
StatusX	RD/FL	Event	Status (Long)	Long	Keyfax Status event. Only if OCX is Early Bound and NotifyStatus method has been set at True. This replaces the GetKeyfaxStatus property.
SubActionCode	FL	Read only	Item (Long)	String	FL sub action code (see ParentActionCode for parent action section)
SubActionCount	FL	Read only	None	Long	Count of returned sub action code sections
SubActionKey	FL	Read only	Item (Long)	String	FL sub action named export section (use in IFX exchange to define INI section key name)
SubActionValue	FL	Read only	Item (Long)	String	FL sub action data associated to SubActionKey
SubCustom	RD/FL	Read only	Item (Long) sNode (String)	String	Custom export node associated to Repair / Action code. The sNode parameter is used to define the XML Node name required (ie 'Location')
Tenancy	RD	Read/write	sValue (String)	String	Sets/gets current fault Q&Aset to select scripts (will use FL.INI default value if not supplied)
Tenancy_Type	RD/FL	Read only	None	String	FL/RD Q&Aset used in script
Tenant	RD/FL	Read/write	sValue (String)	String	Sets/gets current caller name/address for RD/FL script (displayed in title bar)
Tenant ID	RD/FL	Read/write	sValue (String)	String	Sets/gets current caller ID for RD/FL script (passed back to host in TenantID_Ex )
TenantID_Ex	RD/FL	Read only	None	String	FL/RD TenantID reference passed from host
Tenure_Code	FL	Read/write	sValue (String)	String	Sets/gets current enquiry Q&Aset to select scripts (will use FL.INI default value if not supplied)
UnitOfMeasure	RD	Read only	Item (Long)	String	RD unit of measure for repair code returned
UnitOfMeasureQuantity	RD	Read only	Item (Long)	Long	RD quantity of units for repair code returned
UpdateAssetID	RD	Read Only	Item (Long)	String	Requested property Asset ID requiring updating
UpdateCount	RD	Read only	None	Long	Count of returned asset update sections
UpdateNewValue	RD	Read only	Item (Long)	String	Requested property Asset node's new value.
UpdateXPath	RD	Read only	Item (Long)	String	Requested property Asset node to update.
UserCode	RD/FL	Read only	None	String	FL/RD UserName reference passed from host
UserName	RD/FL	Read/write	sValue (String)	String	Sets/gets current user for RD/FL script (passed back to host in UserCode )
Visibility	RD/FL	Read/write	sValue (String)	String	Sets/gets application start-up visibility (should only be used in LaunchKeyfax method ie /V:MIN = start minimized)

The list of properties refer to matching named elements in the start-up and export XML named elements returned from Keyfax to the OCX.

However, since version 3.2 of Keyfax some additional elements have been added to the export XML, which cannot be read directly from named OCX properties.

In version 3.2 of Keyfax we have added the ability to specify additional elements in the Export XML by configuration templates. This allows customers to define custom elements without the need to recode the OCX interface.

The GetNodeByXPath property can be used to fetch data from these bespoke elements as required.

Sample Keyfax Result reading code, using GetNodeByXPath

With oKeyfax
  '=== Set the Mode to 'RD' or 'FL'
  .Mode = "RD"
  '=== Load result XML and Assign OCX properties
  .LoadExport
  '=== Read the location element of returned XML data
  <location> =   .GetNodeByXPath("Fault/Location")
  <advicecode> = .GetNodeByXPath("//Fault[@name='Fault1']/Advice[@name='Advice1']/AdviceCode")
  <isdeleted> =  .GetNodeByXPath("//Fault[@name='Fault1']/Repair[@name='Repair1']/IsDeleted")
  '=== Close the XML document
  .CloseExport
End With

Items shown in arrow bracketing (<host variables>) indicate host application variables.