Beredskabsalarm API. 1 Indhold Indledning .................................................................................................................................................. 4 API beskrivelse opdateret.............................................................................................................................. 5 07-12-2015.................................................................................................................................. 5 14-12-2015.................................................................................................................................. 5 17-12-2015.................................................................................................................................. 5 22-03-2016.................................................................................................................................. 5 25-03-2016.................................................................................................................................. 5 04-08-2016.................................................................................................................................. 5 20-10-2016.................................................................................................................................. 5 08-11-2016.................................................................................................................................. 5 Beskrivelse af Dataset/Datatable .................................................................................................................. 6 Opret en reference til webservicen i Visual Studio ....................................................................................... 7 Beskrivelse af funktioner ............................................................................................................................... 7 createSmsGroup ........................................................................................................................................ 7 Eksempel 1 på brug af createSmsGroup i .NET C# (send til adresse) .............................................. 8 Eksempel 2 på brug af createSmsGroup i .NET C# (send til alle i et postnummer) ........................ 10 createSmsGroup3 .................................................................................................................................... 11 GroupProperties ....................................................................................................................... 11 Eksempel på brug af createSmsGroup3 i .NET C# (send til adresse) ............................................. 12 createSmsGroup4Benchmark .................................................................................................................. 13 prepareSmsGroup ................................................................................................................................... 13 Eksempel på brug af prepareSmsGroup i .NET C# (send til adresse) ........................................... 14 prepareSmsGroupClear ........................................................................................................................... 15 deleteDelayedSmsGroup ......................................................................................................................... 16 Klasser brugt i deleteDelayedSmsGroup: ................................................................................... 16 DeleteGroup .................................................................................................................................... 16 DeleteGroupStatus .......................................................................................................................... 16 deliveryReport ......................................................................................................................................... 17 Eksempel på brug af deliveryReport i .NET C# ............................................................................ 17 deliveryReportByGroupIdAndRefId ......................................................................................................... 17 smsGroups ............................................................................................................................................... 17
40
Embed
Beredskabsalarm API. · Beredskabsalarm API. 6 Beskrivelse af Dataset/Datatable I API’et arbjedes der med et dataset bestående af 4 forskellige datatables. Det første er SmsGroup
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
API beskrivelse opdateret. ............................................................................................................................. 5
Beskrivelse af Dataset/Datatable .................................................................................................................. 6
Opret en reference til webservicen i Visual Studio ....................................................................................... 7
Beskrivelse af funktioner ............................................................................................................................... 7
Eksempel på deliveryReoprtByRefId: ......................................................................................... 28
Status koder ................................................................................................................................................. 29
Eksempel på smsStatusList: ....................................................................................................... 29
SMS 2 WEB .................................................................................................................................................. 30
Denne function adskiller sig fra “createSmsGroup3” ved at den gør brug af klassen ”SmsGroupJSON” og give
muligheden for at give en Benchmark med ved udsendelse oprettelse. Hvis der ikke ønskes at oprette en
benchmark sammen med udsendelsen, anbefaledes det at bruge ”createSmsGroup4” i sted for.
”SmsGroupJSON” samme parameter som “createSmsGroup3”, med undtagelse at From og to -number er en sting. Dette skyldes at det i Sverige er muligt at havde – med i husnummeret. ” BenchmarkJSON” indeholder disse parametre: public DateTime Start { get; set; } public DateTime EstimatedEnd { get; set; } public string Cause { get; set; } public string Category { get; set; } public string ProjectId { get; set; } public string InfoPotalCause { get; set; } public string InfoPotalComment { get; set; }
Hvor Start, EstimatedEnd og Category er påkravet. Category skal match en officiel kategori indenfor bruger typen. InfoPotalCause og InfoPotalCause bliver kun benyttet hvis brugeren har en tilknytning til InfoPotal’en.
Denne funktion har kun et formål, den sletter en evt. forberedt udsendelse. Den returner en tekst streng der indiker om der er fundet og slettet en udsendelse eller ej.
AddPhoneToAdressAuthCode tilføjer et mobilnummer til medsendte adresse. Hvis nummeret ønskes fjerne sættes removeNumber = true. Denne funktion skal også bruge en ”authCode”, hvilket er en bekræftelseskode der sendes pr. SMS. Bekræftelseskoden genereres med addPhoneGenerateAuthCode og sendes pr. SMS til det mobilnummer der medsendes som parameter til funktionen. Funktionen addPhoneConfirmAuthCode kan bruges, hvis man ønsker at bekræfte en authCode er valid, funktionen returner en boolean. AddPhoneConfirmAuthCode kan kun bruges EN gang da en authCode slettes efter brug. AuthCode bør bruges før f.eks. før addedAddressList eller addPhoneToAdress.
Beredskabsalarm API.
20
Eksempel på brug af addPhoneToAddress: //Reference to webservice
String email) Funktionen addedAddressList undersøger, hvilke adresser der kendes for henholdsvis et mobilnummer og/eller en e-mail adresse. Returnere en liste af klassen:
AddedAdress { String Phone
String Email
String ZipCode
String Street
String Number
String Letter
String Floor
String Door
String Country
String KVHx
Boolean Blocked
}
Parameteren Blocked sættes hvis en adresse er blokeret for modtagelse af beskeder. Så f.eks. hvis en
adresse er ”Blocked” for et givet mobilnummer vil dette mobilnummer ikke modtage en besked hvis der
sendes til den pågældende adresse (Også selv om adresse står i telefonbogs databaserne).
Eksempel på brug afaddedAddressList: //Reference to webservice
Funktioner med eksternt kundenummer/reference ID API’et er 6. februar 2012 blevet udvidet med fire nye funktioner, fælles for alle disse funktioner er, at de
alle har en large integer ”refId” som parameter. Denne integer kan bruges som eksternt referencenummer
f.eks. et kunde nummer. De nye funktioner består af en SMS-gateway ”createSingelSms” denne udsender
en enkelt SMS med refId som reference ID. En funktion der heder ”createSingleAddressBroadcast” der
opretter en udsendelse til en enkelt adresse. Tredje og fjerde funktion (deliveryReportByRefId og
deliveryReportByUserName) returnerer en udsendelsesrapporter ud fra refId og/eller fromDate (dato/tid).
createSingleSms(String UserName, String Password,
String Cellphone,
String SmsSendAs,
String Message,
Int64 refId)
CreateSingleSms udsender en SMS til mobilnummeret givet i Cellphone. Der skal angives en afsender på
maks 11 karakter (og minimum 4 karakter) i SmsSendAs og SMS-teksten medsendes hver SMS i Message.
Der skal også medsendes et reference nummer, dette nummer bruges til at trække leveringsrapporter via
funktionen deliveryReportByRefId. CreateSingleSms returnere en large integer forskelig fra 0 hvis SMS
CreateSingleAddressBroardcast opretter en udsendelse til en enkelt adresse eller en husnummerserie på samme vej/gade via fromNumber og toNumber. Ønsker man kun, at oprette en udsendels til et enkelt husnummer angives fromNumber og toNumber til samme nummer. Letter, floor og door parameterne er opligatoriske og kan angives til NULL hvis de ikke bruges. Hvis postnummer (ZipCode) og vejnavn (StreetName) kombinationen ikke kendes af vores system smider funktionen følgende Exception ("Street name: lykkevej does not exist in this zip code: 8270")
Eksempel på createSingleAddressBroadcast: //Reference to webservice
new BeredskabsAlarmTestApi.sRefBeredskabsalarm.beredskabsalarmSoapClient();
//Int64 from return value witch id the LogID.
Int64 logId;
//Open the webservice
bAlarm.Open();
//Create address broardcast
logId = bAlarm.createSingleAddressBroadcast
("username","password",8000,"Lykkevej",24,"A","","","From me","Test API Adresse funktion", 1213);
//Close the webservice connection.
bAlarm.Close();
Beredskabsalarm API.
27
checkAddress(String UserName, String Password,
address[] addressList)
CheckAddress er en funktion der bruges til at validere adresser op imod Beredskabsalarm. Funktionen skal bruge brugernavn, password og et array af adresser der skal undersøges. Der kan max sendes 1000 adresser af gangen. Typen address indeholder et resultat (result) for adressen, dette resultat er en enum og kan have følgende statuser: enum CheckAddressResult{StreetNotFound = 0, NoMobile = 1, MobileExists = 2,KvhxNotFound = 4}
Eksempel på checkAddress: //Reference to webservice
CheckAddressSumByRefId er en funktion der er en gruppering af resultatet fra checkAddress(). Grupperingen er via RefId, så dette er unikt og med en summering af hvor mange mobilnumre der er fundet på de adresser der har været markeret med RefId’et. Resultatet kunne være som følgende:
SmsToWebGetMessageFromDateToDate fungere stort set som ovenstående og returnere samme type. Her
har man blot mulighed for at hente alle beskeder inden for et defineret datotid område.
smsTowebMessage klassen der bruges i smsToWebGEtMessage er defineret som:
public class smsTowebMessage { public Int64 Id { get; set; }
Beredskabsalarm API.
31
public String UserName { get; set; } public DateTime FromDateTime { get; set; } public DateTime ToDateTime { get; set; } public String Header { get; set; } public String Message { get; set; } public String InternalMessage { get; set; } public Boolean CriticalStatus { get; set; } public Boolean Attention { get; set; } public Boolean? Completed { get; set; } public String SmsToWebType { get; set; } public smsTowebMessageAddress Address { get; set; } public Int32 TypeId { get; set; } }
smsTowebMessageAddress klassen der bruges i smsTowebMessage klassen er defineret som:
public class smsTowebMessageAddress { public String Kvhx { get; set; } public Int32 Zip { get; set; } public String City { get; set; } public String Street { get; set; } public Int16 HouseNumber { get; set; } public String Letter { get; set; } public String Floor { get; set; } public String Door { get; set; } }
Funktionen smsToWebGetTypes henter en liste af smsTowebType som er defineret nedenstående. Listen bruges kun af ganske få kunder til indrapportering af gadelys fejl. Så ved du ikke, hvad det er, skal du ikke bruge listen til noget. public class smsTowebType { public Int32 Id { get; set; } public String TypeName { get; set; } }
SmsToInternalGetMessages funktionen returner en liste af typen (klassen) smsToInternalMessage. De
beskeder der findes i listen er alle aktive beskeder, det vil sige beskeder hvor dagsdato (og nu værende
tidspunk) ligger mellem fromDateTime og toDateTime.
Hvis userName og password er på et kunde-login, vil funktionen returnere beskeder for alle bruger-login
under kunden. Hvor beskederne høre hjemme, kan bestemmes ud fra UserName i klassen
smsToInternalMessage.
smsTointernalMessage klassen der bruges i smsToInternalGetMessage er defineret som:
public class smsToInternalMessage { public Int64 Id { get; set; } public String UserName { get; set; } public Int64 SmsGroupId { get; set; } public DateTime FromDateTime { get; set; } public DateTime ToDateTime { get; set; } public String Header { get; set; } public String Message { get; set; } }
Beredskabsalarm API.
34
SMS Skabeloner Der kan på administrations og brugerniveau oprettes SMS skabeloner der kan bruges ved udsendelser.
Disse skabeloner kan hentes via API’et ved at bruge funktionen getSmsTemplates. Funktionen henter
skabeloner der er oprettet på brugerniveau og det administrations niveau der evt. ligger over brugeren (En
bruger har ikke nødvendigvis administrationsniveauet over sig).
getSmsTemplates(String userName, String password)
getSmsTemplates funktionen returner en liste af typen (klassen) SmsTemplate.
SmsTemplate klassen der returneres fra getSmsTemplates er defineret som:
public class SmsTemplate { public Int32 TemplateId { get; set; } public String TemplateName { get; set; } public String SmsText { get; set; } }
Asynkron oprettelse af SMS udsendelse Det er muligt at oprette en SMS udsendelse asynkron. Denne metode anbefales, hvis SMS udsendelsen
indeholder mere end 1000 elementer. Et element er en adresse eller et adresseinterval. Hvis SMS
udsendelsen er mindre, så se afsnit ”Beskrivelse af funktioner” sektionen om createSmsGroup.
Den asynkrone udsendelse metode kan godt tage længere tid om at processer en SMS udsendelse end
createSmsGroup3 API kaldet, men er helt afkoblet fra klienten. Dvs. at klienten kan slukke m.m. når først
udsendelsen er afsendt, hvilket ikke vil påvirke processeringen af udsendelsen.
Procesbeskrivelse
Den asynkrone udsendelse virke via upload af en procesfil til en FTP server. Resultatet skrives ned på
samme FTP server, i en resultatfil.
Der skal gøres opmærksom på at det kan tage flere minutter, før systemet starter med at processer en fil.
Det vil dog ofte tage starte processeringen indenfor 5 minutter.
FTP adgang til den asynkrone udsendelse metode, gives pr. kunde og efter anmodning her om.
Det frarådes at brugeren sletter, eller flytter filer på FTP’seren.
Procesfil
Procesfilen indeholder SMS udsendelse. Den indeholder klassen SmsGroupItemJSON serialize til JSON
format (den er beskrevet længere nede). Navnet på file er et unikt nummer (kunne være en GUID, eller et
tidspunkt) og et procesniveau.
Der findes disse procesniveauer
Navn Beskrivelse
Beredskabsalarm API.
35
Ready Filen er klar til processering. Brugeren sætter filen i dette niveau,
Processing Systemet er i gang med at processer filen. Systemet sætter automatisk filen i dette niveau.
Done Systemet er færdig med at processer filen. Systemet sætter automadisk filen i dette niveau.
Det anbefales at filer uploades uden en procesniveauangivelse. Først når filen er helt uploadede skal
”Ready” procesniveauangivelse sættes.
Et eksempel på et forløb kunne være:
1. Brugeren uploaderen procesfilen CF78B35768CF.txt til FTP serven.
2. Brugeren omdøber filen ”CF78B35768CF.txt” til ”ReadyCF78B35768CF.txt” (den er nu klar til
processering)
3. Systemet starter med at processer filen og omdøber den til ”ProcessingCF78B35768CF.txt”
4. Systemet er færdig med at processer filen og omdøber den til ”DoneCF78B35768CF.txt”
a. Systemet opretter en ny fil (resultatfil) ved navn ”ResultCF78B35768CF.txt”
SmsGroupItemJSON
Procesfilen indeholder klassen SmsGroupItemJSON serialize til JSON format.
Her er en C# version af klassen SmsGroupItemJSON (se at den indeholder en liste af SmsGroupItemJSON)
class SmsGroupJSON { public string SmsSendAs { get; set; } public string BroadcastName { get; set; } public string Message { get; set; } public bool OverruleBlockedNumber { get; set; } public bool SendToAddress { get; set; } public bool SendToAdmin { get; set; } public bool SendToOwner { get; set; } public DateTime? DelayBroadcastTo { get; set; } public bool SendToDefaultReceiver { get; set; } public bool SaveBroadcast { get; set; } public string SaveBroadcastUserName { get; set; } public bool LookupPrivate { get; set; } public bool LookupBusiness { get; set; } public List<SmsGroupItemJSON> SmsGroupItems { get; set; } } class SmsGroupItemJSON { public long? Id { get; set; } public string KVHX { get; set; } public int? Zip { get; set; } public string StreetName { get; set; } public int FromNumber { get; set; } public int ToNumber { get; set; } public string Letter { get; set; } public string Floor { get; set; } public string Door { get; set; } public short EvenOdd { get; set; } public string CellPhone { get; set; }
Beredskabsalarm API.
36
public long? ExternalRefId { get; set; } public bool ZipAllIn { get; set; } } Et JSON eksempel med 10 SmsGroupItemJSON elementer:
Resultatfil
Resultatfilen indeholder resultatet af SMS udsendelsen. Den indeholder klassen ResultJSON serialize til JSON format (den er beskrevet længere nede). Filen bliver oprettet når systemet er færdig med at processer SMS udsendelsen. Filen indeholder evt. fejlbeskeder (hvis den er tom, så er de fordi at der ikke
har vært nogen fejlbeskeder), Sms gruppe ID’et på den SMS grupper der er oprettet til SMS udsendelsen og de SmsGroupItemJSON systemet ikke kunne finde.
ResultJSON
Resultatfilen indeholder klassen ResultJSON serialize til JSON format.
Her er en C# version af klassen ResultJSON (se at den indeholder en liste af SmsGroupItemJSON, beskrevet i
afsnit SmsGroupItemJSON)
class ResultJSON { public long? SmsGroupId { get; set; } public string ErrorMessage { get; set; } public List<SmsGroupItemJSON> NotFoundStreets { get; set; } }
Et JSON eksempel med 2 ikke funden SmsGroupItemJSON elementer
Oprydning af filer
For at sikker overskuelighed på FTP serveren, så er der indbygget oprydning af filer i forbindelsen med en
asynkron udsendelse. Oprydningen flytter/sletter filer efter disse regler.
1. Efter 2 dage bliver filer flyttet ind i en ”oldFiles” mappe.
2. Efter 100 dage bliver filer slettet.
Driftsrapportering/Benchmark På sms-service.dk er der mulighed for at liste, oprettet, slette og rediger driftsforstyrrelser (Benchmarks).
Der er også mulighed for at lise alle adresser, der er tilknyttet en række driftsforstyrrelser. Der er udviklet
en API der udstiller disse funktioner, som en web-service. Denne API dækker alle funktioner på fanebladet
”Rappotering” og Adresseoplysninger på fanebladet ”Statistik”.
Webservicen findes på følgende adresser
For dansksproglag: https://beredskabsalarm.dk/services/BenchmarkService.asmx
For svensksproglag: https://sms-direkt.se/services/BenchmarkService.asmx
Komplekse objekter Web-servicen bruger en række forskellige komplekse objekter. De er beskrevet i denne sektion
public class SmsGroup { public long Id { get; set; } public string Name { get; set; } public DateTime Created { get; set; } public string Company { get; set; } public string UserName { get; set; } public DateTime? DelayTo { get; set; } }
(En driftsforstyrrelse)
(InfoPortal- felterne bliver kun brugt hvis det er en ’el’ kategori. Hvis der ikke er sat en
End date, så bliver EstimatedEnd brugt i sted for.)
public class Benchmark
{ public long id { get; set; } public int? CategoryId { get; set; } public DateTime? Start { get; set; } public DateTime? End { get; set; } public DateTime? EstimatedEnd { get; set; } public string InfoPortalCause { get; set; } public string InfoPortalComment { get; set; } public int? CauseId { get; set; } public string ProjectId { get; set; } public long SmsGroupId { get; set; } }
(En driftsforstyrrelseskategori)
(En driftsforstyrrelse kan kun være en kategori. En driftsforstyrrelse kan ikke oprettes uden en kategori.)
public class Category { public int Id { get; set; } public string Name { get; set; } public string CountryCode { get; set; } public int UserTypeId { get; set; } }
(En driftsforstyrrelsesårsag)
(En driftsforstyrrelse kan godt oprettes uden en driftsforstyrrelsesårsag)
public class Cause { public int Id { get; set; } public string Text { get; set; } public int? CauseNumber { get; set; } public int UserTypeId { get; set; } }
(En brugertype)
(en bruger kan kun være en brugertype. CountryCode kan kun være ’dk’ eller ’se’)
Beredskabsalarm API.
39
public class UserType { public int Id { get; set; } public string Name { get; set; } public string CountryCode { get; set; } }
(Driftsforstyrrelseskategorier og brugertyper)
public class CategorysAndUserTypes { public List<Category> Categories { get; set; } public List<UserType> UserTypes { get; set; } }
(En adresse)
public class Addres { public string Kvhx { get; set; } public int? Zipcode { get; set; } public string Street { get; set; } public int? Number { get; set; } public string Letter { get; set; } public string Floor { get; set; } public string Door { get; set; } public long? BenchmarkMinutes { get; set; } public string CategoryName { get; set; } public int? CategoryId { get; set; } public string UserTypeName { get; set; } public DateTime? BenchmarkStart { get; set; } public DateTime? BenchmarkEnd { get; set; } public string ProjectID { get; set; } public string BenchmarkCauseName { get; set; } public int? UserTypeId { get; set; } public string UserName { get; set; } public int? BenchmarkCount { get; set; } public int? Meters { get; set; } public double? Latitude { get; set; } public double? Longitude { get; set; } public int? BenchmarkId { get; set; } }
Funktioner Denne sektion vil beskrive de forskellige funktioner i Driftsrapportering/Benchmark API’en. Alle funktioner,
undtage getCauses, kræver et login. Dette login udleveres af Blue Idea, og er særlig tilknyttet API’en. Dvs.
at et normalt bruger login, skal gives særlig adgang til API’en.