2/3/2015

ScadaBRdevelopersCERTIScadaBR

CERTI
Searchthesite

ScadaBR
Home
shortcourses
Development

Home>shortcourses>

ScadaBRdevelopers

APIScadaBR
ChecklistScadaBR
0.8

"ShortCourseDevelopers

Distribution

ModuleI:UsingtheAPIMinicourse8h(forjavausersandother

GUI

languages)

ITInfrastructure
Middleware
Protocols
Performancetests
UseofPLCs
VideoLessons

1.IntroductionAPI"WebServices"

ScadaBRReference
Document
Glossary

TheScadaBRAPIisawebservice(webservice)usingtheSOAP

Mango

technology.ThisallowsyoutoextendtheScadaBRthrougharchitecture

OtherScada'sOpen
Source

"clientserver"wheretheScadaBRactsasaserver,andanexternal
module(customdevelopment)actsasaclient.TheScadaBRand

Mango

ApplicationClientcanberunningonthesamemachine,oroncomputers

OpenScada

separate,providedtheyareconnectedandaccessibleviaIPnetwork.

TestsMango
Sitemap

TousetheAPI,youmustusetheinfrastructureaccesstoWebServices
https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

1/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

ofthechosenlanguagefordevelopment..Thisusuallycomesdowntouse
anaccesstotheSOAPlibrary,followingtheirspecificdocumentationIn
mostlanguages,especiallythosewithmoreautomatedsupportforSOAP
(suchasJavaand.NET),aremade
onlytwosteps:1)Creationthe

necessaryAPIclassesfromtheWSDLimportfile(webservices
descriptionlanguage)2)AccesstotheAPImethods.

Translate

TheScadaBRSOAPAPIexposesthemostimportantfeaturesofSCADA,
whicharereadingandwritingtags,queryhistoricaldataandaccessto
alarmsandevents,amongoutos.TheAPIcanbeextendedaccordingto
specificuserneeds.ThistypeofchangeinScadaBRwillbedisplayedin
themoduleIIoftheshortcoursedevelopers.

2.Listofmethodsavailable
Amongthemethodscurrentlyavailable,themostusedare:
getStatusreturns=operatingstatusofScadaBR
browseTags=liststhetagsavailable
readData=readreturnsoneormorevariables(Tags)
WriteData=writevalues
Tags

writeStringData=writevalues
inTags(forcustomerswithout

compatibilityAnyDatatype)
getDataHistory=historicalpullsatag
getActiveEvents=pullsactiveevents(egalarms)
getEventsHistory=pullshistoricalevents,eveninactive
https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

2/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

ackEvents="recognizes"anevent/alarm
browseEventsDefinitions=readsthetypesofdefinedevents
annotateEvent=addausermessageatanevent.
SomemethodsallowmoredetailedmanipulationofScadaBRsettings,
suchas:
configureDataPoint
removeDataPoint
browseDataPoints
removeDataSource
configureDataSource
browseDataSources

3.UsestepbystepAPI
1.Importingthewebservice
Java
Note:ThisstepbystepwasdoneusingEclipseasIDE,sothe
waytoimportWebServicevaryfromIDEtoIDE.
CreateaJavaproject
Copytheprojecttothe.wsdlfile
Forthe.wsdlfile,withScadaBRrunning,entertheaddress
wheretheWSDLislocated(eg"http://localhost:8080/
ScadaBR/services/APIwsdl"andsavethepagein.wsdl
format(originally.xml)

Thenrightclickonthefileintheprojectandselect"WebServices
>GenerateClient"

https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

3/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

Onthescreenthatappears,clickFinishandEclipsewillgenerate
thenecessaryproxiesforyoutousetheAPI.

TocreateaninstanceoftheAPIclient:
APILocatorlocator=newAPILocator();
ScadaBRAPIservice=null;
try{
service=(APISoapBindingStub)locator.getAPI();
}Catch(ServiceExceptione){
//ExceptionTreatment
https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

4/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

}
VB.NET
ThiswalkthroughwascreatedusingMicrosoftVisualBasic2010Express
andpresentsthesequenceofstepsforcreatingacustomerusingVB
.NET.
1. TheinstallationofMicrosoftVisualBasic2010Expressisfairly
straightforward.Itshouldberealizedthewebinstallerdownloado
from:
http://www.microsoft.com/express/downloads
Afteragreeingtotheterms,afilecalled'vb_web.exe'canbe
downloaded.Savethisfiletotheappropriatelocationand
thenrunit.
Theinstallerwillguidetheuserthroughallthestepsneeded
touseMicrosoftVisualBasic2010Expressandwillalso
performthedownloadofalldependencies.
2. Oncetheinstallationiscomplete,youmustruntheMicrosoftVisual
Basic2010Express.Ifthereisnoshortcutontheuser'sdesktop,
youmustruntheprogram:
3. Start>Programs>MicrosoftVisualStudio2010Express>Microsoft
VisualBasic2010Express

4. Youmustcreateanewprojectoftype'WindowsForms
Application'.

https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

5/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

5. Thenewdesigncanberenamedandsavedinasuitableplace.
6. ToimporttheAPIScadaBR,youmustclickwiththerightmouse
buttonontheprojectnameandselect"AddServiceReference..."

7. Anewwindowwillopenandinthe'Address'mustbeinformedof
theWebServicesaddressthatprovidestheScadaBRAPI.Inthe
'Namespace'fieldyoucanedittheservicenametosomethingmore
friendly.

https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

6/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

8. Iftheaddressprovidediscorrectandavailableforaccess,methods
ofereceidostheAPIwillbelisted.Thefollowingimageshowsthe
methodsAVAILABLEforaccessathttp://localhost:8080/
ScadaBR/services/APIwsdl?.Inthisexamplewealsochanged
thenamespaceforScadaBR_API.

9. WiththeavailableWebServicescanbewritteninVB.NETfor
customerstoconsumeScadaBRAPI.Allmethodsdevelopedfor
thestepbystepwereintendedtobeisolatedandthereforeall
instantiateviatheAPIcode

DimMyAPITheNewScadaBR_API.ScadaBRAPIClient
https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

7/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

PHP
NOTE:ForPHPinstallationonubuntuandtheNuSoaplibrarycheckthe
stepsbelow:1)InstallPHPandApache:1.1)$sudoaptgetinstall
apache21.2)$sudoaptgetinstallphp51.3)$sudoaptgetinstall
libapache2modphp51.4)$/etc/init.d/apache2restart1.5)Ifapache
isalreadyinstalledyoucanomittheitem1.1.1.6)Thewebfileswillbe
in"/var/www/"1.7)Toverifythattheinstallationofapache+phpis
working.pleaseabrowserandtype"localhost"intheaddressbar2)
DownloadtheNuSoaplibrary>http://sourceforge.net/projects/nusoap/3)
Placetheclientinthe"/var/www/"orsomeotherofyourchoicein"/
var/www/directory_name/"4)Extractthelibraryintothedirectory
previouslychosen,whichwillbethecustomer.5)Enterabrowserand
typeintheaddressbartheclientyouwanttorun.Ex:"localhost/
browseTags"or"localhost/directory_name/browseTags"

//Setsthelocalizationofthewsdl
$wsdl=
'http://150.162.164.129:8080/ScadaBR/services/API?wsdl';
//Creationofaclientinstantiates
$client=newnusoap_client($wsdl,true);
https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

8/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

2.Readingthelistoftags
Java

BrowseTagsOptionsbrowseTagsOptions=newBrowseTagsOptions()
browseTagsOptions.setMaxReturn(20)//Optionalparameter(default=
100)
BrowseTagsParamsbrowseTagsParams=newBrowseTagsParams()
browseTagsParams.setOptions(browseTagsOptions)
browseTagsParams.setItemsPath(path)//Optionalparameter(tolist
all,justsendanemptyStringorsendnull)
BrowseTagsResponsebrowseTagsResponse=null
try{
browseTagsResponse=service.browseTags(browseTagsParams)
}Catch(RemoteExceptione){
e.printStackTrace()
}
ItemInfo[]=ITEMLISTbrowseTagsResponse.getItemsList()

Stringresponse=""
ApiError[]errors=browseTagsResponse.getErrors()
if(errors[0].getCode()!=ErrorCode.OK){
response="Error:"+errors[0].getDescription()
}Else{
response="Tagsfound:\n"
for(inti=0i<itemList.lengthi++){
response+=("\n"+ITEMLIST[i].getItemName())
}
}
Result:

https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

9/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

VB.NET

DimMyAPITheNewScadaBR_API.ScadaBRAPIClient
DimrespAsNewScadaBR_API.BrowseTagsResponse
DimparamsAsNewScadaBR_API.BrowseTagsParams
DimoptionsAsNewScadaBR_API.BrowseTagsOptions
params.itemsPath=""
resp=myAPI.browseTags(params)
AsIntegerDimlistSize
listSize=resp.itemsList.GetLength(0)
DimiAsInteger
Fori=0To(listSize1)
ListBox1.Items.Add(resp.itemsList(i).itemName)
Next
Result:

PHP
$Proxy=$client>getProxy();
$param=array();
//CallthemethodbrowseTags
$result=$Proxy>call('browseTags',$param);

https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

10/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

3.Readingthevalueofsometags
Java

ReadDataOptionsreadDataOptions=newReadDataOptions()
ReadDataParamsreadDataParams=newReadDataParams()
readDataParams.setOptions(readDataOptions)
readDataParams.setItemPathList(itemPathList)//Listofalltagstobe
read
ReadDataResponsereadDataResponse=newReadDataResponse()
try{
readDataResponse=service.readData(readDataParams)
}Catch(RemoteExceptione){
e.printStackTrace()
}
ItemValue[]=itemsValuereadDataResponse.getItemsList()
Stringresponse=""
ApiError[]errors=readDataResponse.getErrors()
if(errors[0].getCode()!=ErrorCode.OK)
response="Error:"+errors[0].getDescription()
else
response=path+"\n"+itemsValue[0].getValue()

Result:
https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

11/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

VB.NET
DimMyAPITheNewScadaBR_API.ScadaBRAPIClient
DimrespAsNewScadaBR_API.ReadDataResponse
DimparamsAsNewScadaBR_API.ReadDataParams
DimoptionsAsNewScadaBR_API.ReadDataOptions
Dimitems()AsString={"tag1","tag2"}
=params.itemPathListitems
resp=myAPI.readData(params)
TextBox3.Text=resp.itemsList(0).value
=TextBox4.Textresp.itemsList(1).value
Result:

https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

12/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

PHP
$Proxy=$client>getProxy();
$itemPathList=array('itemPathList'=>'humidity');
$param=array($itemPathList);
//CallthemethodreadData
$result=$Proxy>call('readData',$param);

4.Writingatag
Java
WriteDataOptionswriteDataOptions=newWriteDataOptions()
writeDataOptions.setReturnItemValues
(false)

ItemValueitemValue=newItemValue()
itemValue.setItemName(path)//Pathofthetagtoreceivethewrite
operation
itemValue.setTimestamp(Calendar.getInstance())
itemValue.setQuality(QualityCode.GOOD)
itemValue.setDataType(DataType.STRING)
itemValue.setValue(novoValor)
ItemValue[]=newitemValueListItemValue[1]//Tochangemorethan
onetag,justaddmoreItemValueobjectsinthelist
https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

13/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

itemValueList[0]=itemValue
WriteDataParamswriteDataParams=newWriteDataParams()
writeDataParams.setItemsList(itemValueList)
WriteDataResponsewriteDataResponse=newWriteDataResponse()
try{
writeDataResponse=service.writeData(writeDataParams)
}Catch(RemoteExceptione){
e.printStackTrace()
}
Stringresponse=""
ApiError[]errors=writeDataResponse.getErrors()
if(errors[0].getCode()!=ErrorCode.OK){
response="Error:"+errors[0].getDescription()
}Else{
response=path+"\n"+novoValor
}
Result:

https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

14/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

BeforeAfter

VB.NET
DimMyAPITheNewScadaBR_API.ScadaBRAPIClient
DimrespAsNewScadaBR_API.WriteStringDataResponse
DimparamsAsNewScadaBR_API.WriteStringDataParams
DimoptionsAsNewScadaBR_API.WriteDataOptions
options.returnItemValues
=True

=params.optionsoptions
iValue0DimAsNewScadaBR_API.ItemStringValue
iValue0.itemName="tag1"
iValue0.dataType=ScadaBR_API.DataType.INTEGER
iValue0.value=TextBox6.Text
DimiL()TheScadaBR_API.ItemStringValue={}iValue0
params.itemsList=iL
resp=myAPI.writeStringData(params)

Result:

https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

15/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

PHP
$Proxy=$client>getProxy();
$Tag1=array("itemName"=>"humidity","dataType"=>
'Double',"value"=>'79','quality'=>'GOOD',
"timestamp"=>time());
$Tag2=array("itemName"=>"Temperature","dataType"
=>'Double',"value"=>'19','quality'=>'GOOD',
"timestamp"=>time());
$itemsList=array($Tag1,Tag2$),
$param=array($itemsList);
//CallthemethodWriteData
$result=$Proxy>call('WriteData',$param);

https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

16/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

5.Gettinghistoricaldata
Java
Calendarini=Calendar.getInstance();
ini.set(2010,10,18,15,10,00);
CalendarendCalendar.getInstance=();
fim.set(2010,10,18,15,10,10);
GetDataHistoryOptionsdataHistoryOptions=new
GetDataHistoryOptions();
dataHistoryOptions.setInitialDate(ini);
dataHistoryOptions.setFinalDate(order);
dataHistoryOptions.setMaxReturn(100);//optional
parameter(default=500)
GetDataHistoryParamsdataHistoryParams=new
GetDataHistoryParams();
dataHistoryParams.setOptions(dataHistoryOptions);
dataHistoryParams.setItemName(path);
GetDataHistoryResponsedataHistoryResponse=null;
try{
dataHistoryResponse=service.getDataHistory
(dataHistoryParams);
}Catch(Exceptione){
e.printStackTrace();
}
ItemValue[]=itemsListdataHistoryResponse.getItemsList
();
https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

17/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

intsize;
if(itemsList!=null)
size=itemsList.length;
else
size=1;

String[][]=newStringhistoric[size][2];
ApiError[]errors=dataHistoryResponse.getErrors();
if(errors[0].getCode()!=ErrorCode.OK){
historical[0][0]="Error";
History[0][1]=errors[0].getDescription();
}Else{
for(inti=0;i<size;i++){
historical[i][0]=itemsList[i].getValue().
toString();
Datedate=itemsList[i].getTimestamp()getTime().;
StringdateFormat=getPrettyTimestamp(date);//
methodcreatedtoformatthetimestamps
historical[i][1]=dateFormat;
}
}
Stringresponse="Value|Timestamp:\n";
for(inti=0;i<historico.length;i++){
response+=("\n"+historic[i][0]+"|"+historic
[i][1]);
}
Result:

VB.NET

DimMyAPITheNewScadaBR_API.ScadaBRAPIClient
DimrespAsNewScadaBR_API.GetDataHistoryResponse
DimparamsAsNewScadaBR_API.GetDataHistoryParams
DimoptionsAsNewScadaBR_API.GetDataHistoryOptions
https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

18/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

options.initialDate=DateTimePicker1.Value
options.finalDate=DateTimePicker2.Value
If(TextBox7.Text="")Then
options.maxReturn=50
Else
options.maxReturn=TextBox7.Text
EndIf
params.options=options
params.itemName=ComboBox1.SelectedItem.ToString
resp=myAPI.getDataHistory(params)
DimlistSize1TheNewInteger
=listSize1resp.itemsList.GetLength(0)
DimiAsInteger
Fori=0To(listSize11)
ListBox2.Items.Add(resp.itemsList(i)
.itemName.ToString+","+
resp.itemsList(i)+
.timestamp.ToString""+
resp.itemsList(i)
.value.ToString)
Next
Result:

PHP
$Proxy=$client>getProxy();
$tags=array("itemName"=>"tag");
$HistoryOptions=array("initialDate"=>"%",
"finalDate"=>"%","maxReturn"=>"%");
https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

19/20

2/3/2015

ScadaBRdevelopersCERTIScadaBR

$param=array($HistoryOptions,$tag);
//CallthemethodgetDataHistory
$result=$Proxy>call('getDataHistory',$param);

4.Moreinformation
WheninstallingScadaBR,isinstalledafolderwithexamplesofclient
applications.<whereisthefolder,whichcustomersavailable>Foraccess
toothermethodsofAPI,pleaserefertodetaileddocumentationinthe
WIKIpageScadaBRproject.<linktogetinAPIhelppage>Forspecific
informationonobjectcreationanduseofwebservicemethodsinits
language,seespecificdocumentationofthechosenlanguage.

INSTALL_PHP(1k) rba@certi.org.br,30Nov.201010:31
v.1

clienteBrowseTag rba@certi.org.br,30Nov.201010:33
v.1

clienteReadData.p rba@certi.org.br,30Nov.201010:34
v.1

clienteWriteData.p rba@certi.org.br,30Nov.201010:34
v.1

Comments
Youdonothavepermissiontoaddcomments.

Signin | RecentSiteActivity | ReportAbuse | PrintPage | PoweredBy GoogleSites

https://sites.google.com/a/certi.org.br/certi_scadabr/home/minicursos/scadabr

20/20