Difference between revisions of "Orchard Housing"

From Keyfax Wiki
Jump to: navigation, search
(→‎Accessubg Configuration Details)
(→‎Error executing trigger action)
 
(15 intermediate revisions by the same user not shown)
Line 5: Line 5:
 
*'''Orchard Housing WEB''' (previously Archouse Plus)
 
*'''Orchard Housing WEB''' (previously Archouse Plus)
  
−
This page describes the Orchard Housing WEB product, hereinafter OH . This integration operates via a go-between program. When ready to run a Repair Diagnostic, OH  will launch the executable '''KF_arcHouse.EXE'''.  
+
This page describes the Orchard Housing WEB product, from now on OH . This integration operates via a go-between program. When ready to run a Repair Diagnostic, OH  will launch the executable '''KF_arcHouse.EXE'''.  
  
−
  The program KF_arcHouse.EXE is a component of the Keyfax Client and is supported by Omfax Systems Ltd. Should any error messages carrying KF_arcHouse.exe in the title appear, these should be referred to Omfax Systems Support.
+
  The program KF_arcHouse.EXE is a component of the Keyfax Client, Omfax Systems Ltd supports it. Should any error messages carrying KF_arcHouse.exe in the title appear, these should be referred to Omfax Systems Support.
  
 
Within OH, it is possible to configure the command-line arguments that are passed to KF_arcHouse.EXE (for further information on how to define these arguments please contact Orchard Information Systems or see the [http://help.keyfax.biz/Keyfax%20General%20Help%20and%20Technical%20Data%20HC%206/docs/Orchard%20Housing%20_Keyfax_System%20Administration%20Guide_v1%200.pdf Keyfax System Administration Guide]).
 
Within OH, it is possible to configure the command-line arguments that are passed to KF_arcHouse.EXE (for further information on how to define these arguments please contact Orchard Information Systems or see the [http://help.keyfax.biz/Keyfax%20General%20Help%20and%20Technical%20Data%20HC%206/docs/Orchard%20Housing%20_Keyfax_System%20Administration%20Guide_v1%200.pdf Keyfax System Administration Guide]).
Line 51: Line 51:
 
|XSLT TRANSFORMATION FILE
 
|XSLT TRANSFORMATION FILE
 
|/XS:
 
|/XS:
−
|Location of file used for XSLT tranformation of export XML. Note that this is not normally a requirement as this is a historical legacy since Inter•View and the earlier KEYFAXI32.DLL version 3.2.0.32 transformation is performed server-side.  
+
|Location of the file used for XSLT transformation of export XML. Note that this is not normally a requirement as this is a historical legacy since Inter•View and the earlier KEYFAXI32.DLL version 3.2.0.32 transformation is performed server-side.  
 
|-
 
|-
 
|DEBUG SWITCH
 
|DEBUG SWITCH
 
|/DB:
 
|/DB:
−
|Defines the debug level. Please avoid setting any value for this parameter unless Support have been advised. Values are '1' (debug to screen) or '2' (debug to file DEBUG.LOG).
+
|Defines the debug level. Please avoid setting any value for this parameter unless Support has been advised. Values are '1' (debug to screen) or '2' (debug to file DEBUG.LOG).
 
|-
 
|-
 
|}
 
|}
Line 63: Line 63:
  
 
  '''/UC:MJames /TD:"Harry Smith, 1 The Street, Sometown" /TT:1 /AI:12345AR /CO:CO_001 /FN:"C:\Program Files\Keyfax\Export.xml" /XS:"C:\Program Files\Keyfax\Export.xsl"'''
 
  '''/UC:MJames /TD:"Harry Smith, 1 The Street, Sometown" /TT:1 /AI:12345AR /CO:CO_001 /FN:"C:\Program Files\Keyfax\Export.xml" /XS:"C:\Program Files\Keyfax\Export.xsl"'''
 +
 +
Any arguments containing whitespace must be enclosed in quotes.
 +
 +
The configuration page within OH is as [[#Accessing Configuration Details|follows]]
 +
 +
[[File:AccessingConfigPage4.png]]
 +
 +
These settings will typically be established and maintained by Orchard Housing, however, there are two items worthy of note here:
 +
#Delete XML File checkbox; to housekeep after each repair is raised, switch this option ON, otherwise you could end up with thousands of files!
 +
#/FN: Parameter; this is the filename path to which Orchard appends the user id and datetime to make it unique when the workflow work item is created.
 +
 +
===Processing===
 +
In essence, the program will launch a Keyfax Repair Diagnostic which will delete any existing export XML file. Once complete will it generate a new Export.XML file (using the optional XSLT transformation), then terminate. On detecting the export XML file, OH regains focus and the works order etc is created.
 +
 +
===Installation===
 +
The '''KF_arcHouse.exe''' program is delivered as part of the Keyfax Client Installation (v3.2.0.22 or greater) or Keyfax Administrator Tools version 3.2.0.32 or greater (the latter also deploys the Keyfax Client components). The installation configuration file (KF32install.INI) must contain the following declaration:
 +
 +
'''HostApplication=arcHouse_Plus'''
 +
 +
This setting is used for both Archouse Plus and Orchard Housing).
 +
 +
===Transformation===
 +
The initial implementation performs the following transformation:
 +
 +
*FaultText 1,50 is moved to FaultDescription1
 +
*FaultText 51,50 is moved to FaultDescription2
 +
*FaultText 101,150 is moved to FaultExtendedText
 +
*Only output 1st Fault will accumulate Repair and Advice nodes from all Faults
 +
*Job descriptions for all faults concatenated in FaultDescription1, 2 and FaultExtendedText
 +
 +
Ensure that the target folder used for creating the Export XML is exclusive to each user and has Write permissions.
 +
 +
===Screenshots===
 +
 +
Note that this describes earlier versions of Orchard Housing. For versions since and including 2010A07_18, click [[#Orchard Housing Version 2010A07_18|here]].
 +
 +
'''Figure 1''' - Login Page
 +
 +
[[File:image013.jpg]]
 +
 +
'''Figure 2''' - Select 'New Contact'
 +
 +
[[File:image014b.jpg]]
 +
 +
'''Figure 3''' - Select Case type of 'Omfax Repair' then enter an address to lookup
 +
 +
[[File:image015.jpg]]
 +
 +
'''Figure 4''' - Select 'No' then choose Integration Type of 'KEYFAX'
 +
 +
[[File:image016b.jpg]]
 +
 +
'''Figure 5''' - Click 'New Repair'
 +
 +
[[File:image017.jpg]]
 +
 +
'''Figure 6''' - On return details are populated as below
 +
 +
[[File:image018b.jpg]]
  
 
==Accessing Configuration Details==
 
==Accessing Configuration Details==
 +
 +
The Keyfax Link page inside Orchard Housing contains all the parameters that govern the way the Keyfax integration works.
 +
 +
Please do not modify any configuration parameters without the approval of Orchard Housing and/or Omfax Systems representatives.
 +
 +
To access this page, you need to log on to Orchard Housing then go to the '''Maintenance Launchpad''' button and choose '''Entity Data''':
 +
 +
[[File:AccessingConfigPage1.png]]
 +
 +
Select the Entity Add Repair XML System:
 +
 +
[[File:AccessingConfigPage2.png]]
 +
 +
Select the Search button and you should see two results. Select the Keyfax Link and then the Enquiry button:
 +
 +
[[File:AccessingConfigPage3.png]]
 +
 +
You will then see the form below:
 +
 +
[[File:AccessingConfigPage4.png]]
 +
 +
If you are having problems launching Keyfax, try changing the /DB: (DeBug) setting to '1' and making it Active (no start/end delimiters are required). This enables debugging which will cause a number of message boxes to appear in the process leading up to the displaying of the Keyfax pop-up window (it will be useful to note or screengrab these messages for support purposes). If no message boxes appear, either the Keyfax Client is not installed or there is a problem on the host system.
 +
 +
By setting the /DB: parameter to '2', this will output trace messages to a file named c:\program files (x86)\Keyfax\DEBUG.LOG
  
 
==Orchard Housing Version 2010A07_18==
 
==Orchard Housing Version 2010A07_18==
 +
 +
There are differences between this and earlier versions of browser-based Orchard Housing. The screenshots below describe how to navigate through to calling Keyfax and handling the results.
 +
 
 +
[[File:OH1.png]]
 +
 +
Double click on New Contact:
 +
 +
[[File:OH2.png]]
 +
 +
Click the magnifying glass next to the Case Type option then chose Repairs Optitime:
 +
 +
[[File:OH3.png]]
 +
 +
Enter an address:
 +
 +
[[File:OH4.png]]
 +
 +
Double click the address required:
 +
 +
[[File:OH5.png]]
 +
 +
Click Create case and Contact:
 +
 +
[[File:OH6.png]]
 +
 +
Select Telephone and No to Communal Repair:
 +
 +
[[File:OH7.png]]
 +
 +
Click Launch Keyfax
 +
 +
[[File:OH8.png]]
 +
 +
On return from Keyfax, click Retrieve Keyfax Data and this will populate fields accordingly.
  
 
==Launching Keyfax==
 
==Launching Keyfax==
 +
 +
Login Page
 +
 +
[[File:OH9.png]]
 +
 +
Select 'New Contact'
 +
 +
[[File:OH10.png]]
 +
 +
Select Case type of 'Omfax Repair' then enter an address to lookup
 +
 +
[[File:OH11.png]]
 +
 +
Select ‘No’ then choose Integration Type of 'KEYFAX'
 +
 +
[[File:OH12.png]]
 +
 +
Click 'New Repair'
 +
 +
[[File:OH13.png]]
 +
 +
On return, details are populated as below
 +
 
 +
[[File:OH14.png]]
  
 
==Known Issues==
 
==Known Issues==
 +
 +
===Error executing trigger action===
 +
'''Error executing trigger action: "On Press" of "BUTTON1" run "FireIntegrationClick"...Error: Error running exe; Cannot run program c:\program" (in directory "C:\program files"): CreateProcess error=2. The system cannot find the file specified.'''
 +
 +
This may occur during an upgrade to Orchard Housing 2010A09_10.  SP9 requires an upgrade to version 7 of java. 
 +
 +
The problem lies with a function called 'RunExe' which the Orchard workflow uses to launch Inter•View.  It appears the Java Runtime Environment (JRE) is not escaping spaces passed to the command.
 +
 +
The problem surfaced on 07_21 of java but was supposed to be fixed in 25 (which didn’t fix it!). An old version (07_17) will resolve the issue. An alternative is to strip spaces from the command line by using a directory other than 'Program files'. 
 +
 +
Ideally, applications that need to launch programs with spaces in the program name should consider using the variants of Runtime.exec that allow the command and arguments to be specified in an array.
 +
 +
===Export XML file not being created===
 +
Following an upgrade of the Orchard Housing system, you may find that the Keyfax Client does not return the repair data to Orchard Housing. Normally, Keyfax will create an XML file in C:\Program Files\Keyfax\ with a unique filename (i.e. Export_<USERID>_<DATE>_<TIME>.XML), but you may find that it simply outputs to a file called EXPORT.XML.
 +
 +
This can be remedied by setting a new property within Orchard; it is a property called RUNEXESTRIPQUOTESCOMMANDLIST (with KF_arcHouse.exe set as it’s value) which should be set against a category. 
 +
 +
===Cannot launch Keyfax===
 +
Barring problems with the Keyfax Client installation, the most likely reason for this is that the 'User ID' of the logged in Orchard user has not been set up in Keyfax; check the settings on the List User page. If you need to find what parameters are being passed to KF_Archouse.EXE, if you rename the executable (c:\program files (86)\Keyfax\KF_Archouse.exe) on the fat or thin Client (for the latter, ensure no other active users) the command line will be displayed beneath the error message in Orchard.
 +
 +
===Error Converting XML to Object: XML is blank - XML Object cannot be created===
 +
Following the installation of McAfee software at an Orchard site, the following error appeared upon returning to Orchard Housing from Keyfax:
 +
 +
[[File:McAfee.png]]
 +
 +
The module within McAfee Endpoint Security causing this error was ‘Endpoint Security Threat Prevention’ / ‘On-Access Scan’. ‘Scan when copying from network folders and removable drives‘. Any file that is actively being scanned is unavailable until the scan completes. The description of what ‘On-Access Scan’ does is below:
 +
 +
Whenever you access files, folders, and programs, the on-access scanner intercepts the operation and scans the item, based on criteria defined by the administrator.
 +
 +
The problem was resolved by the administrator excluding the folder where the export XML files are stored by Keyfax (a shared network folder in this case).

Latest revision as of 11:36, 1 November 2018

General

Orchard Housing supply two housing management systems:

  • Orchard Housing GUI (previously Archouse)
  • Orchard Housing WEB (previously Archouse Plus)

This page describes the Orchard Housing WEB product, from now on OH . This integration operates via a go-between program. When ready to run a Repair Diagnostic, OH will launch the executable KF_arcHouse.EXE. 

The program KF_arcHouse.EXE is a component of the Keyfax Client, Omfax Systems Ltd supports it. Should any error messages carrying KF_arcHouse.exe in the title appear, these should be referred to Omfax Systems Support.

Within OH, it is possible to configure the command-line arguments that are passed to KF_arcHouse.EXE (for further information on how to define these arguments please contact Orchard Information Systems or see the Keyfax System Administration Guide).

Command-Line Arguments

The following arguments can be supplied:

Item Argument Description
USER CODE /UC: Unique user ID which must be defined in Keyfax (MANDATORY ARGUMENT)
TENANT DETAILS /TD: Name and address comprising Comma separated variables
TENANT ID /TI: Tenant ID (Note: only supported in Keyfax Client version 3.2.0.37 or greater)
TENANCY TYPE /TT: This defines which Repair Diagnostic script set to use
ASSET ID /AI: Optional Asset identifier
COMPANY /CO: Determines which instance of Keyfax to use. If omitted, the default company is used
FILENAME /FN: Location of Export XML filename.
XSLT TRANSFORMATION FILE /XS: Location of the file used for XSLT transformation of export XML. Note that this is not normally a requirement as this is a historical legacy since Inter•View and the earlier KEYFAXI32.DLL version 3.2.0.32 transformation is performed server-side.
DEBUG SWITCH /DB: Defines the debug level. Please avoid setting any value for this parameter unless Support has been advised. Values are '1' (debug to screen) or '2' (debug to file DEBUG.LOG).


An example call might be: 

/UC:MJames /TD:"Harry Smith, 1 The Street, Sometown" /TT:1 /AI:12345AR /CO:CO_001 /FN:"C:\Program Files\Keyfax\Export.xml" /XS:"C:\Program Files\Keyfax\Export.xsl"

Any arguments containing whitespace must be enclosed in quotes.

The configuration page within OH is as follows

AccessingConfigPage4.png

These settings will typically be established and maintained by Orchard Housing, however, there are two items worthy of note here:

  1. Delete XML File checkbox; to housekeep after each repair is raised, switch this option ON, otherwise you could end up with thousands of files!
  2. /FN: Parameter; this is the filename path to which Orchard appends the user id and datetime to make it unique when the workflow work item is created.

Processing

In essence, the program will launch a Keyfax Repair Diagnostic which will delete any existing export XML file. Once complete will it generate a new Export.XML file (using the optional XSLT transformation), then terminate. On detecting the export XML file, OH regains focus and the works order etc is created.

Installation

The KF_arcHouse.exe program is delivered as part of the Keyfax Client Installation (v3.2.0.22 or greater) or Keyfax Administrator Tools version 3.2.0.32 or greater (the latter also deploys the Keyfax Client components). The installation configuration file (KF32install.INI) must contain the following declaration:

HostApplication=arcHouse_Plus 

This setting is used for both Archouse Plus and Orchard Housing).

Transformation

The initial implementation performs the following transformation:

  • FaultText 1,50 is moved to FaultDescription1
  • FaultText 51,50 is moved to FaultDescription2
  • FaultText 101,150 is moved to FaultExtendedText
  • Only output 1st Fault will accumulate Repair and Advice nodes from all Faults
  • Job descriptions for all faults concatenated in FaultDescription1, 2 and FaultExtendedText 
Ensure that the target folder used for creating the Export XML is exclusive to each user and has Write permissions.

Screenshots

Note that this describes earlier versions of Orchard Housing. For versions since and including 2010A07_18, click here.

Figure 1 - Login Page

Image013.jpg

Figure 2 - Select 'New Contact'

Image014b.jpg

Figure 3 - Select Case type of 'Omfax Repair' then enter an address to lookup

Image015.jpg

Figure 4 - Select 'No' then choose Integration Type of 'KEYFAX'

Image016b.jpg

Figure 5 - Click 'New Repair'

Image017.jpg

Figure 6 - On return details are populated as below

Image018b.jpg

Accessing Configuration Details

The Keyfax Link page inside Orchard Housing contains all the parameters that govern the way the Keyfax integration works. 

Please do not modify any configuration parameters without the approval of Orchard Housing and/or Omfax Systems representatives.

To access this page, you need to log on to Orchard Housing then go to the Maintenance Launchpad button and choose Entity Data:

AccessingConfigPage1.png

Select the Entity Add Repair XML System:

AccessingConfigPage2.png

Select the Search button and you should see two results. Select the Keyfax Link and then the Enquiry button:

AccessingConfigPage3.png

You will then see the form below:

AccessingConfigPage4.png 

If you are having problems launching Keyfax, try changing the /DB: (DeBug) setting to '1' and making it Active (no start/end delimiters are required). This enables debugging which will cause a number of message boxes to appear in the process leading up to the displaying of the Keyfax pop-up window (it will be useful to note or screengrab these messages for support purposes). If no message boxes appear, either the Keyfax Client is not installed or there is a problem on the host system. 

By setting the /DB: parameter to '2', this will output trace messages to a file named c:\program files (x86)\Keyfax\DEBUG.LOG

Orchard Housing Version 2010A07_18

There are differences between this and earlier versions of browser-based Orchard Housing. The screenshots below describe how to navigate through to calling Keyfax and handling the results.

OH1.png

Double click on New Contact:

OH2.png

Click the magnifying glass next to the Case Type option then chose Repairs Optitime:

OH3.png

Enter an address:

OH4.png

Double click the address required:

OH5.png

Click Create case and Contact:

OH6.png

Select Telephone and No to Communal Repair:

OH7.png

Click Launch Keyfax

OH8.png

On return from Keyfax, click Retrieve Keyfax Data and this will populate fields accordingly.

Launching Keyfax

Login Page

OH9.png

Select 'New Contact'

OH10.png

Select Case type of 'Omfax Repair' then enter an address to lookup

OH11.png

Select ‘No’ then choose Integration Type of 'KEYFAX'

OH12.png

Click 'New Repair'

OH13.png

On return, details are populated as below

OH14.png

Known Issues

Error executing trigger action

Error executing trigger action: "On Press" of "BUTTON1" run "FireIntegrationClick"...Error: Error running exe; Cannot run program c:\program" (in directory "C:\program files"): CreateProcess error=2. The system cannot find the file specified.

This may occur during an upgrade to Orchard Housing 2010A09_10. SP9 requires an upgrade to version 7 of java.

The problem lies with a function called 'RunExe' which the Orchard workflow uses to launch Inter•View. It appears the Java Runtime Environment (JRE) is not escaping spaces passed to the command.

The problem surfaced on 07_21 of java but was supposed to be fixed in 25 (which didn’t fix it!). An old version (07_17) will resolve the issue. An alternative is to strip spaces from the command line by using a directory other than 'Program files'.

Ideally, applications that need to launch programs with spaces in the program name should consider using the variants of Runtime.exec that allow the command and arguments to be specified in an array.

Export XML file not being created

Following an upgrade of the Orchard Housing system, you may find that the Keyfax Client does not return the repair data to Orchard Housing. Normally, Keyfax will create an XML file in C:\Program Files\Keyfax\ with a unique filename (i.e. Export_<USERID>_<DATE>_

This can be remedied by setting a new property within Orchard; it is a property called RUNEXESTRIPQUOTESCOMMANDLIST (with KF_arcHouse.exe set as it’s value) which should be set against a category.

Cannot launch Keyfax

Barring problems with the Keyfax Client installation, the most likely reason for this is that the 'User ID' of the logged in Orchard user has not been set up in Keyfax; check the settings on the List User page. If you need to find what parameters are being passed to KF_Archouse.EXE, if you rename the executable (c:\program files (86)\Keyfax\KF_Archouse.exe) on the fat or thin Client (for the latter, ensure no other active users) the command line will be displayed beneath the error message in Orchard.

Error Converting XML to Object: XML is blank - XML Object cannot be created

Following the installation of McAfee software at an Orchard site, the following error appeared upon returning to Orchard Housing from Keyfax:

McAfee.png

The module within McAfee Endpoint Security causing this error was ‘Endpoint Security Threat Prevention’ / ‘On-Access Scan’. ‘Scan when copying from network folders and removable drives‘. Any file that is actively being scanned is unavailable until the scan completes. The description of what ‘On-Access Scan’ does is below:

Whenever you access files, folders, and programs, the on-access scanner intercepts the operation and scans the item, based on criteria defined by the administrator.

The problem was resolved by the administrator excluding the folder where the export XML files are stored by Keyfax (a shared network folder in this case).

Retrieved from ‘http://wiki.keyfax.biz/index.php?title=Orchard_Housing&oldid=863’