XML Web Services
for
Central One Dealers

            Central One dealers who have their own web site can easily add impressive capabilities for the benefit of their subscribers using our state of the art XML web services.  You may offer your subscribers the ability to view and change account information and call lists and to view alarm history, such as all events and open/close reports on line.  Your subscribers may do all of this without ever leaving your web site.  You will have complete control over what the subscriber is able to see and do.

What Is XML?

            XML is a mark-up language that is platform independent and readable by both humans and machines.  It is widely supported by all state of the art programming languages including database and scripting languages that run on both Windows and UNIX systems.

What are Web Services?

            You can think of a web service as a computer program sub-routine that exists in a different computer than the main program that calls it.  A computer sub-routine can receive data from the main program when it is called and can return data back to the main program when it finishes.

            In the case of a Central One dealer the main program is that which runs on the dealer’s web server.  The sub-routine or web service runs on Central One’s server.  The scenario is as follows:

  1. A subscriber logs in to the dealer’s web site.
  2. The subscriber clicks a button to request an open/close report.
  3. The dealer’s web server calls Central One’s “AlarmHistory” web service.
  4. Central One’s server returns all alarm history, not limited to openings and closings.
  5. The dealer’s web server program picks out and displays only the opening and closing signals to the subscriber.
  6. The subscriber clicks a button to view and update his callout list.
  7. The dealer’s web server calls Central One’s “CallList” web service.
  8. Central One’s server returns the subscriber’s callout list to the dealer’s web server.
  9. The dealer’s web server displays the list to the subscriber on a form that the subscriber can edit.
  10. The subscriber edits the call list and clicks submit.
  11. The dealer’s web server emails the requested changes to the dealer (or to dataentry@centralone.com if the dealer does not wish to review the changes first) and displays a message to the subscriber stating that the changes will be made with one business day.

From the subscriber’s perspective all of the actions above happen without ever leaving the dealer’s web site, reinforcing the idea that the dealer provides a total security solution and that all of the subscriber’s needs can be met in one place.

How Do I Get Started?

You need a web site and someone who knows how to write web programs.  Most any programming language will do but Visual Basic Dot Net will be used for the example in this document.  In the following example program you will see how to consume a Central One web service.  The web page first displays an account number prompt and submit button.  When an account number is entered and the submit button is clicked the example program calls the “VerifyAccount” web service which returns several fields of subscriber information.  The example program simply puts the subscriber’s name on the web page form.  Next, the program calls the “AlarmHistory” web service and displays the date and time, event type, description and disposition in a grid on the web page.  The web service retrieves all events but only displays open/close events to the subscriber.

If you are not a programmer the source code examples that follow may be Greek to you.  Don’t worry about that.  The point is that with only the following four pages of source code a programmer can build a web page that consumes XML web services and makes your site a sophisticated, interactive tool for the benefit of your subscribers.  You can download a sample project that includes full source code at www.CentralOne.com/webservices/SampleCode.zip.

Here is the source code for the ASPX/HTML portion of the web page:

<%@ Page Language="vb" AutoEventWireup="false" Codebehind="WebForm1.aspx.vb" Inherits="AlrmHist.WebForm1"%>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<HTML>

   <HEAD>

          <title>Alarm History</title>

          <meta name="GENERATOR" content="Microsoft Visual Studio.NET 7.0">

          <meta name="CODE_LANGUAGE" content="Visual Basic 7.0">

          <meta name="vs_defaultClientScript" content="JavaScript">

          <meta name="vs_targetSchema" content="http://schemas.microsoft.com/intellisense/ie5">

   </HEAD>

   <body>

          <form id="Form1" method="post" runat="server">

                 <P>

                        <asp:Label id="Label1" runat="server">Account Number:  </asp:Label>&nbsp;

                        <asp:TextBox id="txtAccount" runat="server" MaxLength="7"></asp:TextBox>&nbsp;

                        <asp:Button id="butHistory" runat="server" Text="Submit"></asp:Button></P>

                 <P>

                        <asp:Label id="lblSubName" runat="server"></asp:Label></P>

                 <P>

                        <asp:DataGrid id="dgHist" runat="server"></asp:DataGrid></P>

                 <P>

                        <asp:Label id="lblResult" runat="server"></asp:Label></P>

          </form>

   </body>

</HTML>

Here is the Visual Basic Program (code behind file) that consumes the web services and updates the web page:

Imports AlrmHist.com.centralone.www

Imports System.Diagnostics

 

Public Class WebForm1

    Inherits System.Web.UI.Page

    Protected WithEvents Label1 As System.Web.UI.WebControls.Label

    Protected WithEvents butHistory As System.Web.UI.WebControls.Button

    Protected WithEvents txtAccount As System.Web.UI.WebControls.TextBox

    Protected WithEvents dgHist As System.Web.UI.WebControls.DataGrid

    Protected WithEvents lblSubName As System.Web.UI.WebControls.Label

    Protected WithEvents lblResult As System.Web.UI.WebControls.Label

    '

    ' You MUST supply your dealer number and password in order for the

    ' web services to give you access!

    '

    Public Const dealer As Int32 = 0

    Public Const password As String = "PASSWORD"

 

#Region " Web Form Designer Generated Code "

 

    'This call is required by the Web Form Designer.

    <System.Diagnostics.DebuggerStepThrough()> Private Sub InitializeComponent()

 

    End Sub

 

    Private Sub Page_Init(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Init

        'CODEGEN: This method call is required by the Web Form Designer

        'Do not modify it using the code editor.

        InitializeComponent()

    End Sub

 

#End Region

 

    Private Sub Page_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load

        'Put user code to initialize the page here

    End Sub

 

    Dim octypes() As String = {"OPN-SIL", "CLO-SIL", "LTO-SIL", "LTC-SIL"}

 

    Private Sub butHistory_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles butHistory.Click

        '

        '  Make sure there is a number value in the txtAccount text

        '  box.  You should either display an appropriate error message

        '  if there is no value or you should use the validator

        ' controls supplied by Visual Basic on the web form.

        Dim account As Int32 = Val(txtAccount.Text)

        If account < 1 Then Exit Sub

        Dim column As New DataColumn()

        Dim dthist As New DataTable()

        Dim drhist As DataRow

        Dim ad As New accountdata()

        Dim h As New history()

        Dim s As New signal()

        Dim m As New AlrmHist.com.centralone.www.WebServices()

        '

        ' call the "VerifyAccount" web service:

        '

        Try

            ad = m.VerifyAccount(account, dealer, password)

        Catch ex As Exception

            lblResult.Text = ex.Message

            Exit Sub

        End Try

        If ad.returncode <> "Success" Then

            lblResult.Text = ad.returncode

            Exit Sub

        End If

        '

        '  at this point you have all the data from the verify account

        '  web service in an object called ad.  You can use it any way

        '  you see fit.  Here we will just put the subscriber name in a

        '  label control:

        lblSubName.Text = ad.acct_name

        '

        '  call the "AlarmHistory" web service:

        '

        Try

            h = m.AlarmHistory(account, dealer, password, 90, 100)

        Catch ex As Exception

            lblResult.Text = ex.Message ' error message from Visual Basic

            Exit Sub

        End Try

        If h.returncode <> "Success" Then

            lblResult.Text = h.returncode   ' error message from the web service

            Exit Sub

        End If

        '

        ' Here we will create four columns of alarm signal data to

        ' display to the web user.  Much more is available and you are

        ' free to use all of the columns exposed by our web service.

        '

        column = New DataColumn()

        column.DataType = System.Type.GetType("System.DateTime")

        column.ColumnName = "DateTime"

        dthist.Columns.Add(column)

        column = New DataColumn()

        column.DataType = System.Type.GetType("System.String")

        column.ColumnName = "EventType"

        dthist.Columns.Add(column)

        column = New DataColumn()

        column.DataType = System.Type.GetType("System.String")

        column.ColumnName = "Description"

        dthist.Columns.Add(column)

        column = New DataColumn()

        column.DataType = System.Type.GetType("System.String")

        column.ColumnName = "Disposition"

        dthist.Columns.Add(column)

        '

        '  In the following example we filter the history and show the

        '  user only open/close events.  To show all events simply

        '  delete the "If" and "End If" statements:

        '

        For Each s In h.signals

            If Array.IndexOf(octypes, s.sig_atp) > -1 Then

                drhist = dthist.NewRow

                drhist("DateTime") = s.sig_date

                drhist("EventType") = s.sig_atp

                drhist("Description") = s.sig_zdes

                drhist("Disposition") = s.sig_disp

                dthist.Rows.Add(drhist)

            End If

        Next

        dgHist.DataSource = dthist

        dgHist.DataBind()

    End Sub

End Class

 

            Now, wasn’t that easy!  Obviously you will want to build on this example and provide your subscriber with additional information and options.  Central One is dedicated to providing our dealers with the tools they need to meet the needs of their subscribers.  Our existing web services have been built upon the requests of dealers and we will continue to add to the technology when requested to do so.

 

            Let’s take a look at the data returned by the “VerifyAccount” web service call.

  <?xml version="1.0" encoding="utf-8" ?>

- <accountdata xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.centralone.com">

  <acct_num>897555</acct_num>

  <acct_name>Mike McIntosh</acct_name>

  <acct_add1 />

  <acct_add2>5555 Sugar Pine Drive</acct_add2>

  <acct_city>Boca Raton</acct_city>

  <acct_state>FL</acct_state>

  <acct_zip>33487-2209</acct_zip>

  <acct_mph>561-999-5555</acct_mph>

  <acct_aph>561-239-5555</acct_aph>

  <acct_active>true</acct_active>

  <acct_idate>0001-01-01T00:00:00.0000000-05:00</acct_idate>

  <acct_cdate>1998-07-15T00:00:00.0000000-04:00</acct_cdate>

  <acct_grp>1</acct_grp>

  <acct_pnm>FBI-XL31</acct_pnm>

  <acct_ddf>AR#1234567</acct_ddf>

  <acct_dls>2002-11-20T00:00:00.0000000-05:00</acct_dls>

  <acct_ani>561-000-0000</acct_ani>

  <acct_fmt>Pulse Undefined!</acct_fmt>

  <returncode>Success</returncode>

  </accountdata>

 

Field Name

Description

Type

acct_name

subscriber name

string

acct_add1

address (line one of two)

string

acct_add2

address (line two of two)

string

acct_city

city

string

acct_state

state

string

acct_zip

zip code

string

acct_mph

main premises telephone number

string

acct_aph

alternate telephone number

string

acct_active

is the account active? (true or false)

Boolean

acct_idate

inactive date (1/1/0001 if account is active)

date

acct_cdate

contract date

date

acct_grp

group number (same as dealer number)

integer

acct_pnm

type of alarm panel installed

string

acct_ddf

dealer defined field

string

acct_pmt

permit number

string

acct_pex

permit expiration date

date

acct_eml

subscriber’s email address

string

acct_dls

date and time of last signal from panel

date

acct_ani

phone number from which last signal was received

string

acct_fmt

communicator format of last signal

string

acct_tst

date and time through which account is on test

date

returncode

contains “Success” if call succeeded, otherwise this field contains an appropriate error message

string

           

            Let’s take a look at the data returned by the “AlarmHistory” web service call.

  <?xml version="1.0" encoding="utf-8" ?>

- <history xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.centralone.com">

  <returncode>Success</returncode>

- <signals>

- <signal>

  <sig_acct>897555</sig_acct>

  <sig_date>2003-02-14T19:27:22.0000000-05:00</sig_date>

  <sig_code>401</sig_code>

  <sig_atp>CLO-SIL</sig_atp>

  <sig_zone>22</sig_zone>

  <sig_zdes>Cleaners</sig_zdes>

  <sig_ani>954-000-0000</sig_ani>

  <sig_disp>scheduled</sig_disp>

  <sig_enum>44216</sig_enum>

  </signal>

- <signal>

  <sig_acct>897555</sig_acct>

  <sig_date>2003-02-14T19:12:00.0000000-05:00</sig_date>

  <sig_code>401</sig_code>

  <sig_atp>OPN-SIL</sig_atp>

  <sig_zone>22</sig_zone>

  <sig_zdes>Cleaners</sig_zdes>

  <sig_ani>954-000-0000</sig_ani>

  <sig_disp>scheduled</sig_disp>

  <sig_enum>43377</sig_enum>

  </signal>

- <signal>

  <sig_acct>897555</sig_acct>

  <sig_date>2003-02-14T18:10:50.0000000-05:00</sig_date>

  <sig_code>401</sig_code>

  <sig_atp>CLO-SIL</sig_atp>

  <sig_zone>8</sig_zone>

  <sig_zdes>Carol Johnson</sig_zdes>

  <sig_ani>954-000-0000</sig_ani>

  <sig_disp>scheduled</sig_disp>

  <sig_enum>40412</sig_enum>

  </signal>

- <signal>

  <sig_acct>897555</sig_acct>

  <sig_date>2003-02-14T07:45:52.0000000-05:00</sig_date>

  <sig_code>401</sig_code>

  <sig_atp>OPN-SIL</sig_atp>

  <sig_zone>10</sig_zone>

  <sig_zdes>LINDA SMITH</sig_zdes>

  <sig_ani>954-000-0000</sig_ani>

  <sig_disp>scheduled</sig_disp>

  <sig_enum>13982</sig_enum>

  </signal>

- <signal>

  <sig_acct>897555</sig_acct>

  <sig_date>2003-02-13T18:56:34.0000000-05:00</sig_date>

  <sig_code>401</sig_code>

  <sig_atp>CLO-SIL</sig_atp>

  <sig_zone>8</sig_zone>

  <sig_zdes>Carol Johnson</sig_zdes>

  <sig_ani>954-000-0000</sig_ani>

  <sig_disp>scheduled</sig_disp>

  <sig_enum>44036</sig_enum>

  </signal>

- <signal>

  <sig_acct