Exorsys International Inc.

The challenge was to connect to the Canadian Food Inspection Agency's (CFIA) Automated Import Reference System (AIRS) Validation Web Service from a basic scripting language (such as Revelations's OpenInsight). CFIA does not permit access via HTTP GET or POST while SOAP generates byte array data types for the XML content that the scripting language does not support.

We elected to use Visual Studio 2008's built-in functions to perform the byte-string data conversions and generate the SOAP interface. We also used Interop to make the properties and methods accessible via COM/OLE from the script. A setup project was created to generate the install package that automatically registered the COM objects on the client machine. All project documents are available on the AIRS download page

Terms of use

These resources and information are provided as freeware. Please provide a link back to this page (http://www.exorsys.com/AIRS) if you find this useful.

Specifications

The AIRSGateway project accepts all standard AIRS web service input parameters as properties and returns all available AIRS web service results as properties, substituting BYTE data types with STRING.

The GetResponse method returns a boolean response that evaluates to true (-1) when a successful web service call has been effected. Otherwise it returns zero with the Soap exception information in the "Error" properties.

Input properties

• XmlRequest (required): input XML document
• AirsVersion: defaults to "1.0"
• Broker Key (required): Your actual Broker Key as assigned by the CFIA
• Language: defaults to "1" (english) set to "2" for French
• AirsURL: defaults to current web service URL

Output Properties

• XmlResponse: XML document returned by Web Service
• ErrorCode: from Soap Call
• ErrorMessage: from Soap Call
• ErrorDetail: from Soap Call

Download the complete AIRS Web Service Specifications

Create the project

• Start Visual Studio 2008
• Select: CreateProject/Window/ClassLibrary
• Specify Solution Name: "AirsGateway"
• OK

Prepare the main class module

• Open Solution Explorer
• Right-click Class1.vb, Rename, "AirsValidation"
• Add the following lines before the class name;Imports System Imports System.Diagnostics Imports System.Web.Services Imports System.Web.Services.Protocols Imports System.Xml.Serialization
• Add the following code after the class name to create variables, define the interface and set default values;#Region "Members" Private mXmlRequest As String Private mAirsVersion As String Private mBrokerKey As String Private mLanguage As LanguageType Private mAirsUrl As String Private mXmlResponse As String Private mErrorCode As String Private mErrorMessage As String Private mErrorDetail As String #End Region #Region "Properties" Public Property XmlRequest() As String Get Return mXmlRequest End Get Set(ByVal value As String) mXmlRequest = value End Set End Property Public Property AirsVersion() As String Get Return mAirsVersion End Get Set(ByVal value As String) mAirsVersion = value End Set End Property Public Property BrokerKey() As String Get Return mBrokerKey End Get Set(ByVal value As String) mBrokerKey = value End Set End Property Public Property Language() As Integer Get Return mLanguage End Get Set(ByVal value As Integer) mLanguage = value End Set End Property Public Property AirsUrl() As String Get Return mAirsUrl End Get Set(ByVal value As String) mAirsUrl = value End Set End Property Public Property XmlResponse() As String Get Return mXmlResponse End Get Set(ByVal value As String) mXmlResponse = value End Set End Property Public Property ErrorCode() As String Get Return mErrorCode End Get Set(ByVal value As String) mErrorCode = value End Set End Property Public Property ErrorMessage() As String Get Return mErrorMessage End Get Set(ByVal value As String) mErrorMessage = value End Set End Property Public Property ErrorDetail() As String Get Return mErrorDetail End Get Set(ByVal value As String) mErrorDetail = value End Set End Property #End Region #Region "Constructor" Sub New() mXmlRequest = String.Empty mAirsVersion = "1.0" mBrokerKey = String.Empty mLanguage = 1 mAirsUrl = "http://airs-sari.inspection.gc.ca/avs/bvs.svc?wsdl" mXmlResponse = String.Empty mErrorCode = String.Empty mErrorMessage = String.Empty mErrorDetail = String.Empty End Sub #End Region

Reference the AIRS Web Service

• Right-click the solution name "AirsGateway" in the Solution explorer
• Select: AddServiceReference/Advanced/AddWebReference
• Specify URL: "http://airs-sari.inspection.gc.ca/avs/bvs.svc?wsdl"
• Click GO to find the bvs service
• Remove the (invalid) hyphen in the generated Web Reference Name suffix("-sari")
• Click Add Reference

Call the Web Service

Create the method "GetResponse" to be used by the calling script by adding the following lines immediately before the "End Class" statement. This uses the dotNet GetBytes and GetString functions to convert to/from the Byte Array data type which is generated by the Web Service WSDL and is not supported by the scripting environment.Public Function GetResponse() As Boolean Dim ws As ca.gc.inspection.airs.BrokerValidationService = New ca.gc.inspection.airs.BrokerValidationService Try Dim response As Byte() ws.Url = mAirsUrl response = ws.ValidateRequirements(System.Text.Encoding.UTF8.GetBytes(mXmlRequest), mAirsVersion, mBrokerKey, mLanguage, True) mXmlResponse = System.Text.Encoding.ASCII.GetString(response) Return True Catch ex As SoapException mErrorCode = ex.Code.Name mErrorDetail = ex.Detail.InnerText mErrorMessage = ex.Message Return False Catch unhandledException As Exception Throw (unhandledException) End Try End Function

Generate the COM interface

• Define the standard COM interface variables by "wrapping" the Class declaration as follows;<ComClass(AirsValidation.ClassId, AirsValidation.InterfaceId, AirsValidation.EventsId)> _ Public Class AirsValidation Public Const ClassId As String = "xxx" Public Const InterfaceId As String = "yyy" Public Const EventsId As String = "zzz"
• Add the COM GUID generator to VS2008 menus: Tools/External Tools/Add/Title: "Create GUID"/ Command: browse to "C:\Program Files\Microsoft Visual Studio 9.0\Common7\Tools\guidgen.exe"/OK
• Generate unique GUID keys: VS2008/Tools/Create GUID/4. Registry Format/New GUID
• Cut-and-paste the Result value displayed to replace "xxx" in ClassID
• Repeat previous 2 steps to assign unique GUIDs for InterfaceID and EventsID

Test the dotNet project

Create a simple Windows forms application that references the AIRSValidation project and executes the following code;Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click Try Dim request As AIRSValidation.Entities.Request = New AIRSValidation.Entities.Request Dim sw As ca.gc.inspection.airs.BrokerValidationService = New ca.gc.inspection.airs.BrokerValidationService Dim reader As IO.TextReader = File.OpenText("C:\AIRSTEST.xml") Dim airs As New AIRSValidation.AIRSInterface.AIRSValidation Dim reply As AIRSValidation.Entities.Reply request.XmlRequest = reader.ReadToEnd() request.BrokerKey = "ABC123def456" reply = airs.GetResponse(request) MessageBox.Show(reply.XmlResponse) Catch ex As Exception Throw ex End Try End Sub

Test the COM interface

The following OpenInsight program demonstrates how the generated COM object can be accessed from a simple scriptcompile Subroutine AIRS_Validate(strNull) $Insert MSG_Equates declare Function MSG Declare subroutine OlePutProperty OSRead xmldoc FROM DocDir:'C:\AIRSTEST.xml' Else xmldoc = '' objAirs = OleCreateInstance('AIRSGateway.AIRSValidation') OlePutProperty(objAirs, "XmlRequest", xmldoc) OlePutProperty(objAirs, "BrokerKey", "TABC123def456") Resp = OleCallMethod(objAirs,'GetResponse') If Resp = -1 Then xmlResponse = OleGetProperty(objAirs, "XmlResponse") Def = "" Def<MCaption$> = "AIRS Validation Sucess!" x = Msg(@Window, Def) End Else ErrorCode = OleGetProperty(objAirs, "ErrorCode") ErrorMessage = OleGetProperty(objAirs, "ErrorMessage") ErrorDetail = OleGetProperty(objAirs, "ErrorDetail") Def = "" Def<MCaption$> = "AIRS Validation SOAP Error" Def<MText$> = "- IT support will be notified -" Def<MText$,-1> = "||Code = ":ErrorCode Def<MText$,-1> = "||Message = ":ErrorMessage Def<MText$,-1> = "||Detail = ":ErrorDetail x = Msg(@Window, Def) end Return

Creating the Windows Installer Setup Package

While the AIRSGateway project is open in VS;

• Select File/New Project/Setup and Deployment
• Name: "Setup"
• Solution: "Add to Solution"
• OK
• Right-click "Setup" in Solution Explorer
• Select: View/File System
• Right-click "application folder"
• Select: Add/Project Output/Pirmary Output/OK
• Right-Click "AirsGateway.dll"
• Select Properties Window
• Set Register Property to "vsdraCOM"
• Right-click "Setup" in Solution Explorer
• Select Build to create setup.exe and .msi files

To access all project resources and results: view the AIRS download page.