Many of the following steps require you to use StreetLightOutages.com web services.  You can browse these web services and their WSDL documents by pointing your browser to the following:

• IFCommonService
• IFIncidentService

Create a new StreetLightOutages organization at http://www.streetlightoutages.com/signup.aspx. Once you have created a new organization, you can sign in with your credentials and use the Admin tab to manage your organization configurations.

This is an optional step.

It may be that the standard incident reporting form provided by StreetLightOutages.com does not address your needs.  In that case, you can provide your own HTML code to iFactor Consulting and we will configure your organization account to always use your own HTML code.

Your HTML code should include a <form> tag with suitable user input tags.  Note that the name attributes for the input elements will be the parameter names that will be sent to your POST API.

For example, if you provide HTML code like...

<form name="incidentReportDialog">
  <label for="name">Contact Name:</label><input type="textbox" name="
contactname">
  <label for="phone">Contact Phone:</label><input type="textbox" name="phone">
  <label for="email">Contact Email:</label><input type="textbox" name="email">
  <label for="agencyname">Agency Name:</label><input type="textbox" name="agencyname">
  <label for="agencyposition">Agency Position:</label><input type="textbox" name="agencyposition">
  <label for="polenumber">Pole Number:</label><input type="textbox" name="polenumber">
  <label for="problemtype">Trouble Type</label>
  <select id="problemtype" name="problemtype" width="173px" height="19px">
    <option value="Light out">Light out</option>
    <option value="Light on during day">Light on during day</option>
    <option value="Light dim">Light dim</option>
    <option value="Light noisy">Light noisy</option>
    <option value="Light cycling on/off">Light cycling on/off</option>
    <option value="Animal nest">Animal nest</option>
    <option value="Exposed wires - base">Exposed wires - base</option>
    <option value="Other">Other</option>
  </select>
  <label for="comments">Additional Comments:</label>
  <textarea name="comments"></textarea>
</form>

... we will provide the following corresponding POST request parameters to your provided API...

http://yourwebserviceURL/yourwebservicescript?contactname=<some contact name>&phone=<some phone number>
     &email=<some e-mail>&agencyname=<some agency name>&agencyposition=<some agency position>
     &polenumber=<some pole number>&problemtype=<some problem type>&comments=<some comments>
     &<a few other StreetLightOutages parameters...>

Your organization subscription can be configured to push streetlight incident reports. If you want StreetLightOutages.com to push new incident reports to you, you will need to expose a Web Service or HTTP script on your organization's public-facing server.  Once you have provided us with that URL, we can append all of our form-driven incident parameters plus a few standard parameters.  All of our standard parameters are prefixed with slo (Street Light Outage):

• sloLatitude : float - the latitude (in decimal degrees with positive values to the north) of the reported incident
• sloLongitude : float - the longitude (in decimal degrees with positive values to the east) of the reported incident
• sloIncidentID : integer - our internally unique identifier for this incident
• sloIncidentType : string - typically this string will be "streetlight"

NOTE: We expect that your POST API will return to us an ID string that uniquely identifies this outage to you in your system.  This will be useful to you in the future when you choose to notify StreetLightOutages.com of any changes to this outage.  In that case you may choose to use your own identifier or the sloIncidentID to reference the outage.

Based on the example we provided in the "Provide Customisations to Your Hosted Incident Reporting Form" section together with our standard slo parameters the following POST request would be sent.

http://yourwebserviceURL/yourwebservicescript?contactname=<some contact name>&phone=<some phone number>
     &email=<some e-mail>&agencyname=<some agency name>&agencyposition=<some agency position>
     &polenumber=<some pole number>&problemtype=<some problem type>&comments=<some comments>
     &sloLatitude=49.100&sloLongitude=-123.033&sloIncidentType=streetlight&sloIncidentID=4576

You can specify your own web service URL by logging into www.StreetLightOutages.com and choosing the Admin -> Integrate tabs and then specifying a URL in the Web Service Feed text box.

On your organization's street light outage reporting page, you can now replace your existing form markup code with a single link to StreetLightOutages.com using the <iframe> tag:

<iframe src="http://www.streetlightoutages.com/embed.aspx?width=770&height=200&username=<yourOrgName>guest">
   Your browser does not support iFrames
</iframe>

The parameters are:

• username : string - a concatenation of <your Organization Name> + "guest"
• width : integer - optional pixel width of map and search bar (defaults to 500)
• height : integer - optional pixel height of map and search bar (defaults to 500)

You may also include other attributes in the <iframe> tag to provide some layout control over the frame.

<iframe class="streetlightmap" src="http://www.streetlightoutages.com/embed.aspx?width=770&height=550&username=<yourOrgName>guest"
  style="width:770px;border:1px solid #a5b2bd" scrolling="no" width="770px" height="550px"
      frameborder="0">Your browser does not support iFrames</iframe>

You can see the exact form of your iframe URL by logging into www.StreetLightOutages.com and choosing the Admin -> Main tabs and then referencing the Page IFrame text box.

The final part of the implementation is for you to provide messages back to StreetLightOutages.com whenever your incident has been fixed or repaired.  Whether you do that as a batch process or provide a manual interface to your administrative users, the mechanism for telling us about the change is the same.  You need to use our web services to send us the message.

The following example shows how you could implement code in ASP.NET with C# code to mark an incident as 'fixed' in StreetLightOutages.com

1. In your web application project reference Web Service http://www.streetlightoutages.com/webservices/IFCommonService.asmx.  For this example, we rename our reference to IFCommonService.
2. In your web application project reference Web Service http://www.streetlightoutages.com/webservices/IFIncidentService.asmx.  For this example, we rename our reference to IFIncidentService.
3. The following C# code snippet shows how you can mark an incident as repaired.  We leave it up to the web site developer to determine how to integrate this into your business process.

    {
        // first create a new instance of the IFCommonService. You may want to store this
        // on a class variable if you will be referring to it repeatedly.
        IFCommonService.IFCommonService commonService = new IFCommonService.IFCommonService();
        
        // create a new instance of the IFIncidentService. You may want to store this
        // on a class variable if you will be referring to it repeatedly.
        IFIncidentService.IFIncidentService incidentService = new IFIncidentService.IFIncidentService();
        
        // for most calls to the StreetLightOutages.com web services, you need to have
        // a valid user token.  NOTE: for many of these Administrative tasks, the web service confirms
        // that the user token being presented is suitable authorised.  So, while you can get a user token
        // for any user in the system for which you know the username and password, not all web service
        // methods will work with that token.
        String myUserToken = commonService.GetUserToken("myUserName", "myUserPassword", 200);

        // SetIncidentStatusBySLOID takes three parameters myUserToken, Streetlightoutages.com's ID and status type.
        // This method will set the current status type to the next transition status type. If the current status type
        // is "reported" the next transition status type is "resolved". Similary, from resolved to closed.  
        
        // For Example to transit from 'reported' to 'resolved' status type 
        // 9999 is the SLO Incident ID
        Boolean isIncidentFixed = incidentService.SetIncidentStatusBySLOID(myUserToken, 9999, "resolved");

        // to transit from 'resolved' to 'closed' status type 
        isIncidentFixed = incidentService.SetIncidentStatusBySLOID(myUserToken, 9999, "closed");
    }
            

If the language you plan to use for automating the indicent update functionality does not support SOAP, you can use HTTP POST or GET requests to accomplish the same thing.  Note that this example is more pseudo-code than actual code.  The URLs are valid but depending on your scripting language you will need to send the URL using different functions.

    // for most StreetLightOutages.com web services that make changes to the database, we
    // also track the user that made the change for auditing purposes.
    http://www.streetlightoutages.com/webservices/IFCommonService/GetUserToken?user=myUserName&password=myUserPassword&expiryMinutes=200

     // ... or you can 'resolve' the incident by specifying StreetLightOutages.com's ID and status type for the incident.
    http://www.streetlightoutages.com/webservices/IFIncidentService/SetIncidentStatusBySLOID?userToken=myUserToken&SLOID=9999&statusType=statysTypeName

See Using Javascript proxies to consume web services for an elegant way to consume web services from Javascript functions.

Thanks to Matthias Hertel's AjaxEngine project we can also provide you with client-side Javascript proxy functions that consume these web services.

For example, let's say that you wanted to call the IFCommonService.GetUserToken operation from Javascript.

1. In the <header> section of your HTML place the following <script> tags:
   
   

   <script type="text/javascript" src="http://www.streetlightoutages.com/webservices/JavaScriptProxy/ajax.js"></script>
   <script type="text/javascript" src="http://www.streetlightoutages.com/webservices/JavaScriptProxy/GetJavaScriptProxy.aspx?service=/webservices/IFCommonService.asmx"></script>       

 
2. In your Javascript code you can now access the Web Service:
   • Synchronously...
      

     // set the .func property to null if we want the call to be synchronous.
     proxies.IFCommonService.GetUserToken.func = null;
     
     // now call the web service
     var username = "myUserName";
     var password = "myPassword";
     var expiryMinutes = 200;
     
     var userToken = proxies.IFCommonService.GetUserToken(username,password,expiryMinutes);
     

   • ... or Asynchronously...
      

     // if we want the call to be asynchronous, set the .func property to a callback function.
     proxies.IFCommonService.GetUserToken.func = function(returnValue) {
         someGlobal.usertoken = returnValue;
     };
     
     // now call the web service
     var username = "myUserName";
     var password = "myPassword";
     var expiryMinutes = 200;
     
     proxies.IFCommonService.GetUserToken(username,password,expiryMinutes);