Attachment 13 NEMIS ACE Interface.pdf

Section J Attachment 13

9/6/2012

NEMIS ACE 3

Interface

Federal Emergency

Management Agency

NEMIS Human Services

ACE 3

Edit Check Plug In

Version 1.00 September 6, 2012

Submitted to:

Federal Emergency Management Agency

Washington, DC 20472

Revision History

Version Date Author Comments

1.00 12/5/02 Dave Marty Initial document. – Verified as current 7-27-2011 L Tederick

Table of Contents Table of Contents Introduction Overview The Edit Check Plug In Interface

ACE3 application initialization IDL Declaration C++ Declaration VB Declaration

ACE3 application termination IDL Declaration C++ Declaration VB Declaration

Inspection Opened to Edit IDL Declaration C++ Declaration VB Declaration

Inspection Screen Exit IDL Declaration C++ Declaration VB Declaration

Inspection Saved IDL Declaration C++ Declaration VB Declaration

Important Programming Guidelines General Guidelines Very Important Access Database Considerations Exceptions

Development Machine Installation Instructions Installation With Samples Installation Without Samples

Creating Plug Ins Creating an in process Ace3 C++ Plug In

Create ATL DLL Project Add ATL Object to Project Implement the Plug-In Interface

Creating an out of Process Ace3 C++ Plug In Create ATL DLL Project Add ATL Object to Project Implement the Plug-In Interface

Creating Visual Basic plug in implementations Deployment Instructions

Introduction This document describes the Ace3 Edit Check Plug In interface. It provides details regarding the interface and how to implement the interface.

Overview The Ace3 Edit Check Plug In interface allows external software to control certain behaviors of the Ace3 application. Specifically the interface allows software outside of Ace to be developed to perform “Edit Checks” or data validation on inspection data as the data is being gathered. In certain cases the Ace3 application will not continue to the next step unless the data is validated by the external edit check software.

To provide the greatest support for development languages and to provide tight integration between the two applications, COM is used to implement the Ace 3 Edit Check Plug In Interface.

Developers that are familiar with COM programming should have no difficulty implementing this interface.

The Edit Check Plug In Interface The Ace3 interface consists of five methods that need to be implemented by the edit check software developer. The methods are called at certain points during the execution of Ace3.

ACE3 application initialization After the user has successfully logged into Ace3 and the application has displayed the Inspection List screen this method is called. The plug in developer should initialize any global data in this method. There are neither parameters nor return values for this method.

Ace3 will not block on this call so reasonable length methods may be executed. However note that it is likely that other interface methods may be called before this method returns. It is the plug-in developer’s responsibility to handle this situation. Therefore it is advisable not to perform any lengthy operations in this function.

IDL Declaration [id(1), helpstring("Called when Ace3 has completed ….”)]

HRESULT Ace3Init();

C++ Declaration STDMETHOD(Ace3Init)();

VB Declaration Private Sub Ace3EditCheckPlugIn_Ace3Init()

ACE3 application termination This method is called as the last action taken by Ace3 prior to exiting. Plug Ins should clean up any resources used. Ace3 will release its reference to the object immediately after calling this method.

IDL Declaration [id(2), helpstring("Called as the last thing ACE3 does when it exits")] HRESULT Ace3Terminate();

C++ Declaration STDMETHOD(Ace3Terminate)();

Private Sub Ace3EditCheckPlugIn_Ace3Terminate()

Inspection Opened to Edit This method is called after Ace3 has fully loaded an inspection for edit. The edit check software could perform any initialization required for a specific inspection. The keys for the given inspection are passed as parameters. There is no return value. The method has no affect on the behavior of Ace3.

IDL Declaration [id(3), helpstring("Called after an inspection has been loaded")] HRESULT InspnLoaded([in] long RgsnID, [in] long DstrNR, [in] long XferSeqNR);

C++ Declaration STDMETHOD(InspnLoaded)(/*[in]*/ long RgsnID, /*[in]*/ long DstrNR, /*[in]*/ long XferSeqNR);

Private Sub Ace3EditCheckPlugIn_InspnLoaded(ByVal RgsnID As Long, _

ByVal DstrNR As Long, ByVal XferSeqNR As Long)

Inspection Screen Exit This method is called when a user is attempting to exit a screen after Ace3 has validated and saved data for that screen. The edit check software could perform screen specific edit checks and prevent the user from exiting the screen until those edit checks are satisfied. This method returns one of the values in the Ace3EditCheckStatus enumeration (ecSuccess or ecFailure). The edit check software should return ecSuccess to indicate that all edit checks have passed and to allow the user to continue to the next screen. If the edit checks fail, return ecFailure to keep the ace3 user on the same screen. In this case, the edit check software must present some sort of user interface to display the errors that the user must correct. Typically, this is done via a message box or dialog box.

The screens are specified by the Ace3Screen enumeration.

Enumeration Description asRgsnInfo The first screen displayed when an inspection is edited. This screen edits data such as name, addresses, phone numbers, insurance data and others.

asComments Comments edit screen asDwellInfo Dwelling, custom questions and occupants asRealProp Rooms and real property asPersonalProp Rooms and personal property asUnmetNeeds Vehicles, unmet needs, essential tools and Miscellaneous purchases asPostInspn Home and inspection status

IDL Declaration [id(5), helpstring("Called when attempting to exit an inspection screen")] HRESULT InspnScreenExit([in] long RgsnID, [in] long DstrNR, [in] long XferSeqNR, [in] Ace3Screen screen, [out, retval] Ace3EditCheckStatus* ecStatus);

C++ Declaration STDMETHOD(InspnScreenExit)(/*[in]*/ long RgsnID, /*[in]*/ long DstrNR, /*[in]*/ long XferSeqNR, /*[in]*/ Ace3Screen screen, /*[out, retval]*/ Ace3EditCheckStatus* ecStatus);

Private Function Ace3EditCheckPlugIn_InspnScreenExit(ByVal RgsnID As Long, _

ByVal DstrNR As Long, ByVal XferSeqNR As Long, _ ByVal screen As ACE3PlugIn.Ace3Screen) As ACE3PlugIn.Ace3EditCheckStatus

Inspection Saved This method is called after Ace3 has validated and saved an inspection and is attempting to return to the inspection list screen. The edit check software should perform any final validation on the inspection in this method.

Note that this method is called every time an inspection is exited. The inspector may not have changed the inspection status values. This means that this method may be called on inspections that are still considered “open”. It is up to the edit check software to determine the appropriate set of checks to run according to the inspection status.

The keys for the given inspection are passed as parameters. This method returns one of the values in the Ace3EditCheckStatus enumeration (ecSuccess or ecFailure). The edit check software should return ecSuccess to indicate that all edit checks have passed and to allow the user to continue to the inspection list screen. If the edit checks fail, return ecFailure to keep the ace3 user on the same screen. In this case, the edit check software must present some sort of user interface to display the errors that the user must correct. Typically, this is done via a message box or dialog box.

This method also allows the edit check software to log comments. Return non-empty values in both pbstrEvtSummary and pbstrEvtText and a comment will be logged with that summary text and event text. Both pbstrEvtSummary and pbstrEvtText need to be strings with printable characters. Do not attempt to put binary data in these strings. The summary text (pbstrEvtSummary) may be up to 50 characters in length. The comment text (pbstrEvtText) may be up to 2000 characters. Return the pointers untouched or with empty strings in both to suppress comment logging.

IDL Declaration [id(4), helpstring("Called after an inspection has been saved")] HRESULT InspnSaved([in] long RgsnID, [in] long DstrNR, [in] long XferSeqNR, [in, out] BSTR* pbstrEvtSummary, [in, out] BSTR* pbstrEvtText, [out, retval] Ace3EditCheckStatus* ecStatus );

C++ Declaration STDMETHOD(InspnSaved)(/*[in]*/ long RgsnID, /*[in]*/ long DstrNR, /*[in]*/ long XferSeqNR, /*[in, out]*/ BSTR* pbstrEvtSummary, /*[in, out]*/ BSTR* pbstrEvtText, /*[out, retval]*/ Ace3EditCheckStatus* ecStatus );

Private Function Ace3EditCheckPlugIn_InspnSaved(ByVal RgsnID As Long, _

ByVal DstrNR As Long, _ ByVal XferSeqNR As Long, _ pbstrEvtSummary As String, _ pbstrEvtText As String) As ACE3PlugIn.Ace3EditCheckStatus

Important Programming Guidelines General Guidelines Some of the function calls in the interface will block continued Ace3 processing. Because of this, it may appear to the user that the Ace3 application is “hung” or “locked up” if the plug-in performs lengthy operations. Therefore it is important that you do not perform any lengthy operations in the edit check software. Also it is important that any modal dialogs are displayed on top of the Ace3 screen so that the user can see them.

It is not recommended, but it is permissible to have a non-modal GUI screen available during Ace3 execution. Having multiple screens that requires that they switch back and forth between applications may be confusing to novice users. However, if the edit check developers feel that the users are capable of understanding and using such a system, the plug-in interface would support that sort of design.

Very Important Access Database Considerations Microsoft Access is not a synchronous multi-user database. It implements a database caching mechanism that is not shared across connections. Because of this, database actions committed by a transaction on one connection are not immediately visible by other connections. The solution to this depends on the database access technology used in your plug-in. Please refer to the following Microsoft Knowledge Base articles regarding this subject. Generally, we have found that closing and re-opening the connection will flush all cache data to the database.

http://support.microsoft.com/default.aspx?scid=KB;en-us;q200300 http://support.microsoft.com/default.aspx?scid=kb;EN-US;180223

Exceptions Your plug-in should not raise exceptions of any kind under any circumstances. Any exceptions raised by your plug-in implementation will result in the Ace3 application disabling your plug in for that execution cycle. Also, the user will be presented with a dialog box that would allow them to disable your plug in implementation for future executions of Ace3. In order to re-enable your plug-in, you would need to set the “Enabled” registry setting to “Yes”. Therefore it is critical that your plug-in handle any and all exceptions internally.

Development Machine Installation Instructions Sample plug in implementations are provided in C++ and Visual Basic. You can install the samples and the required type library or just install the type library alone if you are comfortable with COM development.

The VC in process example program has code that will launch an executable from the dll.

Installation With Samples Simply unzip all files in ace3PlugIn.zip into C:\Ace3PlugIn. Selecting your c:\ root drive and unzipping to the folder structure will do this. Follow the instructions below to develop your plug

in. Review the samples in the c:\Ace3PlugIn\Samples folder.

Installation Without Samples Unzip Ace3PlugIn.tlb to a directory of your choice. Follow the directions below to develop your plug in.

Creating Plug Ins Detailed instructions follow for creating either in or out of process implementations of this interface in C++. There are various ways to do this, however this is the easiest process to follow.

The instructions here should take less than ½ hour to complete.

Creating an in process Ace3 C++ Plug In Create ATL DLL Project

1. Start Visual Studio

2. Select File->New menu to open the “New” dialog

3. Click on the Projects tab.

4. Select ATL Com Wizard

5. Set your project name and location.

6. Click OK to start the ATL Com Wizard

7. Select Dynamic Link Library. It is also recommended to select “Support MFC”

8. Click Finish

Add ATL Object to Project

1. Select Insert->New ATL object menu.

2. Select “Objects” category and “Simple Object” and click next.

3. Type your class name. SamplePlugIn for example.

4. Leave attributes tab at defaults. Apartment Threaded, Dual Interface.

Implement the Plug-In Interface

1. Open the Class View tab in the workspace window.

2. Right click on the class you just created.

3. Select “implement interface”. Click OK to select from a list of available type libraries.

4. If Ace3Plugin 1.0 Type Library(1.0) appears in the list, select that. If not select the browse button to find the Ace3PlugIn.tlb file.

5. Select IAceEditCheckPlugIn and click OK. This will add all of the interface methods to your class.

6. Implement the interface as you desire.

Creating an out of Process Ace3 C++ Plug In Create ATL DLL Project

9. Start Visual Studio

10. Select File->New menu to open the “New” dialog

11. Click on the Projects tab.

12. Select ATL Com Wizard

13. Set your project name and location.

14. Click OK to start the ATL Com Wizard

15. Select Executable.

16. Click Finish

Add ATL Object to Project

5. Select Insert->New ATL object menu.

6. Select “Objects” category and “Simple Object” and click next.

7. Type your class name. SamplePlugIn for example.

8. Leave attributes tab at defaults. Single Threaded, Dual Interface.

Implement the Plug-In Interface

7. Open the Class View tab in the workspace window.

8. Right click on the class you just created.

9. Select “implement interface”. Click OK to select from a list of available type libraries.

10. If Ace3Plugin 1.0 Type Library(1.0) appears in the list, select that. If not select the browse button to find the Ace3PlugIn.tlb file.

11. Select IAceEditCheckPlugIn and click OK. This will add all of the interface methods to your class.

12. Implement the interface, as you desire.

Creating Visual Basic plug in implementations The instructions for in proc and out of proc implementations are essentially the same except the type of project chosen.

1. Create a new Active-X dll project (in proc) or an Active X exe project (out of proc).

2. Add the reference to the Ace3PlugIn.tlb to the references.

3. Rename the project and classes as needed.

4. In the default class provided type “Implements Ace3EditCheckPlugIn”

5. Select Ace3EditCheckPlugIn in the left code pane drop down.

6. Select all five functions in the right code pane drop down to add them to the class.

7. Implement them as desired.

Deployment Instructions

1. Install all requirements for your plug in software.

2. Register your plug in component on the Ace3 machine.

3. Edit the following string registry setting to be the COM progID of your plug-in.

HKLM\SOFTWARE\FEMA\NEMIS\ACE3\PlugIn\ProgID

4. Edit the following string registry setting to be “Yes”

HKLM\SOFTWARE\FEMA\NEMIS\ACE3\PlugIn\Enabled.