Byggsøk Building 2010 / Page 1 of 22
Version 3.0 – description of SOAP interface / Version 1.3
Date: 03.05.2011


STATENS BYGNINGSTEKNISKE ETAT
BYGGSØK building 2010
Description of SOAP interface (Integration)

Byggsøk Building 2010 / Page 1 of 22
Version 3.0 – description of SOAP interface / Version 1.3
Date: 03.05.2011

Versions

Rev nr. / Date / Description / Author
0.1 / 08.02.2011 / Sent for comments. Services which doesn’t have comments should be implemented asap / Anna Schultz
1.0 / 21.02.2011 / Document sent for implementation. Method oppdaterVedlegg was updated. Description of method replaceSoknad was updated. / Anna Schultz
1.1 / 21.02.2011 / Updated two methods: nyByggesak and nySoknad / Anna Schultz
1.2 / 02.03.2011 / Changes due to implementation / Anna Schultz
1.3 / 03.05.2011 / Updated methods description & parameters. Added schema descriptions. / Dmitry Krambalev

SOAP service endpoint:

WSDL for methods described below is available at

Main XML schema definition for Byggesak application (also used for partial updates):

XML schema for returning error descriptions:

XML schema for list of projects:

XML schema for list of applications:

XML schema for list of PDF reports:

1General methods information.

All SOAP methods of EBS requires authorization – i.e. specifying ‘systemBruker’/’passord’ pair on each method call. Corresponding user login with role ‘External System’ should be created by server administrator for each external system which plans to access SOAP interface.

To update properties of user login (like address, email), it’s needed to log in from ‘welcome’ page of EBS server using user with role ‘External System’

Version number is specified as number at the end of XML schema name.

2Retrieve application data from ByggSok Bygning

Metode / Description
lesByggesakListeBruker / Gets list of projects which is stored for the given user.
lesSoknadListeByggesak / Gets list of applications which belong to the given project.
lesSoknad / Gets application content for given application.
lesVedlegg / Gets selected binary attachement from application.
lesUtskriftListe / Gets list of PDF reports available for the given application.
lesUtskrift / Gets selected PDF report.

2.1Read application data

2.1.1Methode: lesByggesakListeBruker

Gets list of projects, which is stored for the given user

Input parameters

systemBruker / string / System user for the application/system performing the service.
Passord / string / Password associated to system user
Brukernavn / string / ByggSok Username (application owner)
Brukerpassord / string / Application (applicant) owner password

Output parameters

byggesakListe / string / XML-string which contains complete list of projects. Schema location for XML file is
Feilbeskrivelse / string / XML-string which describes the error situation. Schema location for XML file is

Return

Feilkode / integer / 0=ok, 1=error (in case of errors, ‘feilbeskrivelse’ contains additional info).

XML schema for byggesakListe parameter:

<?xml version="1.0" encoding="ISO-8859-1"?>

xs:schema xmlns=" xmlns:xs=" attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="

xs:element name="Project_List">

xs:complexType

xs:sequence maxOccurs="unbounded" minOccurs="0">

xs:element name="Project">

xs:complexType

xs:sequence

xs:element name="DbId" type="xs:string"/>

xs:element minOccurs="0" name="Name" type="xs:string"/>

xs:element minOccurs="0" name="Start_Date" type="xs:string"/>

xs:element minOccurs="0" name="Status">

xs:simpleType

xs:restriction base="xs:string">

xs:enumeration value="In work"/>

xs:enumeration value="Completed"/>

</xs:restriction

</xs:simpleType

</xs:element

</xs:sequence

</xs:complexType

</xs:element

</xs:sequence

</xs:complexType

</xs:element

</xs:schema

Description of tags in XML byggesakListe:

DbId / String / Project identifier, used to reference to this project in other SOAP function calls
Name / String / Name of project as given by user
Start_Date / String / Date of project creation (free text format).
Status / String enum / ‘In work’ or ‘Completed’. Status can be changed manually by user, also it is set automatically to ‘Completed’ when ‘Ferdig’ application is sent for this project

2.1.2Methode: lesSoknadListeByggesak

Gets list of applications, which belong to a given project (includes sent applications and those which are currently under work).

Input parameters

systemBruker / String / System user for the application/system performing the service.
Passord / String / Password associated to system user
byggesakID / String / Project ID (exactly as returned from method lesByggesakListeBruker in tag ‘Dbid’)

Output parameters

soknadListe / String / XML-string which contains list of applications. Schema location for XML file is
feilbeskrivelse / String / XML-string which describes the error situation. Schema location for XML file is

Return

Feilkode / Integer / 0=ok, 1=error (in case of errors, ‘feilbeskrivelse’ contains additional info).

XML schema for soknadListe parameter:

<?xml version="1.0" encoding="ISO-8859-1"?>

xs:schema xmlns=" xmlns:xs=" attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="

xs:element name="Application_List">

xs:complexType

xs:sequence maxOccurs="unbounded" minOccurs="0">

xs:element name="Application">

xs:complexType

xs:sequence

xs:element name="DbId" type="xs:string"/>

xs:element minOccurs="0" name="Name" type="xs:string"/>

xs:element minOccurs="0" name="Start_Date" type="xs:string"/>

xs:element minOccurs="0" name="Status">

xs:simpleType

xs:restriction base="xs:string">

xs:enumeration value="In work"/>

xs:enumeration value="Sent"/>

xs:enumeration value="Signing"/>

xs:enumeration value="Signing (paused)"/>

</xs:restriction

</xs:simpleType

</xs:element

xs:element minOccurs="0" name="Sent_Date" type="xs:string"/>

</xs:sequence

</xs:complexType

</xs:element

</xs:sequence

</xs:complexType

</xs:element

</xs:schema

Description of tags in XML soknadListe:

DbId / String / Application identifier, used to reference to this application in other SOAP function calls (it is unique among other applications from other projects as well).
Name / String / Type of application (rammetillatelse, ferdigattest, etc.)
Start_Date / String / Date of application creation (free text format)
Status / String enum / ‘In work’, ‘Signing’, ‘Signing (paused)’ or ‘Sent’, corresponding status is set automatically – ‘Signing …’ - when application is locked for signing, and ‘Sent’ – when application is sent to commune _electronically_
Sent_Date / String / Date when application was sent (if status is equal to ‘Sent’, otherwise empty)

2.1.3Methode: lesSoknad

Reads complete application from ByggSok Bygning. Retrieves only the application itself, without binary attachments.

Input parameters

systemBruker / String / System user for the application/system performing the service.
Passord / String / Password associated to system user
soknadID / String / Application ID (exactly as returned from method lesSoknadListeByggesak in tag ‘Dbid’)

Output parameters

Soknad / String / XML-string which contains complete application data. Schema location for XML file is
feilbeskrivelse / String / XML-string which describes the error situation. Schema location for XML file is

Return

feilkode / Integer / 0=ok, 1=error (in case of errors, ‘feilbeskrivelse’ contains additional info).

XML schema for Soknad parameter: it is an official Byggesak version 2.0 XML schema, published & documented separately. Example of returned XML data is shown below:

<?xml version="1.0" encoding="ISO-8859-1"?>

byggesak xmlns=" xmlns:ans=" xmlns:be=" xmlns:bns=" xmlns:fns=" xmlns:mens=" xmlns:my=" xmlns:xs=" xmlns:xsi=" identifier="11/82" xsi:schemaLocation="

sak soknadstype="ett-trinns soknad">

typetiltak

nyebygg

parkeringsplass/>

</nyebygg

</typetiltak

soknad/>

beskrivelseavtiltak/>

eiendom id="ID_1301918716808_1" type="byggeeiendom">

identifikasjon

adresse

fns:versjon1</fns:versjon

ans:tilleggsnavnKildeKode

fns:versjon1</fns:versjon

fns:kodeverdi/>

fns:beskrivelse/>

</ans:tilleggsnavnKildeKode

ans:postnr1234</ans:postnr

ans:poststedqqq</ans:poststed

ans:representasjonspunkt

fns:point

fns:coordinates/>

</fns:point

</ans:representasjonspunkt

ans:matrikkelenhetIdent

mens:kommunenr2012</mens:kommunenr

mens:gardsnr1</mens:gardsnr

mens:bruksnr2</mens:bruksnr

mens:festenr4</mens:festenr

mens:seksjonsnr5</mens:seksjonsnr

</ans:matrikkelenhetIdent

ans:bruksenhetIdent

bns:byggIdent

bns:bygningsnr/>

</bns:byggIdent

</ans:bruksenhetIdent

ans:matrikkeladresseIdent

ans:kommunenr/>

ans:gardsnr0</ans:gardsnr

ans:bruksnr0</ans:bruksnr

</ans:matrikkeladresseIdent

</adresse

andregnrbnr3</andregnrbnr

</identifikasjon

</eiendom

ansvarsomradebeskrivelser/>

</sak

</byggesak

2.1.4Method: lesVedlegg

The applicant attaches an arbitrary number of attachments to the application in ByggSok. Method is described for retrieval of binary attachments linked to the application. Only attachments having the location ”electronic attachment in the database” can be retrieved from application.

To get info for which attachment exists in the application, see the retrieved information on tag ‘Vedlegg’ in XML returned from method lesSoknad. Documents stored in ByggSok may be of ”arbitrary” type, PDF, Word, JPG etc.

Input parameters

systemBruker / String / System user for the application/system performing the service.
passord / string / Password associated to system user
soknadID / string / Application ID (exactly as returned from method lesSoknadListeByggesak in tag ‘Dbid’)
vedleggID / string / Attachment ID (this is a value of ‘id’ attribute of tag ‘vedlegg’ in XML returned by method lesSoknad)

Output parameters

dokument / base64Binary
(byte array) / The attached document.
feilbeskrivelse / string / XML-string which describes the error situation. Schema location for XML file

Return

feilkode / integer / 0=ok, 1=error (in case of errors, ‘feilbeskrivelse’ contains additional info).

2.2Retrieve printouts

BYGGSØK can generate various printouts (PDF reports) in an application. In this section methods are described for retrieving lists of available printouts, and the possibility to get generated and returned printouts as documents. Usually new printout is generated on each method invocation.

2.2.1Methode: lesUtskriftListe

Gets list of printouts (PDF reports) available for the given application. For retrieving a specific printout, the method lesUtskrift is used.

Input parameters

systemBruker / string / System user for the application/system performing the service.
passord / string / Password associated to system user
soknadID / String / Application ID (exactly as returned from method lesSoknadListeByggesak in tag ‘Dbid’)

Output parameters

utskriftListe / String / XML-string containing list of printouts in the application. Schema location for XML file
Feilbeskrivelse / String / XML-string which describes the error situation. Schema location for XML file

Return

Feilkode / Integer / 0=ok, 1=error (in case of errors, ‘feilbeskrivelse’ contains additional info).

XML schema for utskriftListe parameter:

<?xml version="1.0" encoding="ISO-8859-1"?>

xs:schema xmlns=" xmlns:xs=" attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="

xs:element name="Printout_List">

xs:complexType

xs:sequence maxOccurs="unbounded" minOccurs="0">

xs:element name="Printout">

xs:complexType

xs:sequence

xs:element name="DbId" type="xs:string"/>

xs:element minOccurs="0" name="Type">

xs:simpleType

xs:restriction base="xs:string">

xs:enumeration value="Varsling"/>

xs:enumeration value="Søknader"/>

xs:enumeration value="Ansvar og kontroll"/>

</xs:restriction

</xs:simpleType

</xs:element

xs:element minOccurs="0" name="Name" type="xs:string"/>

</xs:sequence

</xs:complexType

</xs:element

</xs:sequence

</xs:complexType

</xs:element

</xs:schema

Description of tags in XML utskriftListe:

DbId / String / Printout identifier, used to reference this printout in other SOAP function calls
Type / String enum / ‘Varsling’, ’Søknader’, or ’Ansvar og kontroll’ (’Søknader’ is a main report for application).
Name / String / Name of printout document (same as could be seen on printouts page in Byggesak GUI)

Notice: This ’DbId’ is an internal key in BYGGSØK, and must not be stored in external system for later use. ‘DbId’ is only meant to be temporary use for retrieving one or more printouts through method ‘lesUtskrift’.

2.2.2Methode: lesUtskrift

Retrieves one of the available printouts for an application. ByggSok will generate the printout on-the-fly and return it to the client as a document. To get information for which printouts that can be generated for a given application, see method lesUtskriftListe. Printouts are in PDF format, but other formats may become possible.

Input parameters

systemBruker / String / System user for the application/system performing theservice.
Password / String / Password associated to system user
soknadID / String / Application ID (exactly as returned from method lesSoknadListeByggesak in tag ‘Dbid’)
utskriftID / String / Printout ID (exactly as returned by method lesUtskriftListe in tag ‘Dbid’).

Output parameters

Document / base64Binary
(byte array) / Complete generated printout as document. (currently only PDF)
Feilbeskrivelse / String / XML-string which describes the error situation. Schema location for XML file

Return

Feilkode / Integer / 0=ok, 1=error (in case of errors, ‘feilbeskrivelse’ contains additional info).

3Send application data to ByggSok Bygning

Methode / Description
nyByggesak / Create new project (together with its first application)
nySoknad / Create new application in existing project
replaceSoknad / Replace content of existing application.
oppdaterVedlegg / Replace/add binary attachments.
oppdaterForetak / Update company information

3.1Creating and updating application

3.1.1Methode: nyByggesak

Method for creating a new project in ByggSok Bygning. Initial application for the project will be automatically created – empty. To fill application out with data use method replaceSoknad. (notice that only certain combinations of ‘tiltaksType’ and ‘soknadType’ are allowed).

Input parameters

systemBruker / string / System user for the system performing the service.
Password / string / Password associated to system user
Brukernavn / string / ByggSok username (this is the user who will be set as owner of the project)
Brukerpassord / string / User (applicant) password
byggesakNavn / string / Name for new project
soknadType / base64Binary
(byte array) / XML data continaing soknad (application) type. This will be type of initial application which is created automatically with new project. Not all soknad types are allowed for initial application in project. Schema location for XML file is

tiltaksType / base64Binary
(byte array) / XML data continaing tiltaks (project) type. This type will be same for all further applications in this project (notice that currently XML schema allows only one project type, while Byggesak GUI allows multiple selection). Schema location for XML type is

Output parameters

nyByggesakID / string / Project ID of newly created project
nySoknadID / string / Application ID of newly created application (initial application of the project)
Feilbeskrivelse / String / XML-string which describes the error situation. Schema location for XML file

Return

Feilkode / Integer / 0=ok, 1=error (in case of errors, ‘feilbeskrivelse’ contains additional info).

XML schema for soknadType parameter: it is an official Byggesak version 2.0 XML schema, published & documented separately. For this parameter, only tags related to application type need to be filled in (others will be skipped if present). Below is an example of XML data (notice that it’s important to state correct XML namespace for main element and correct accessible schema location for that namespace as well):

<?xml version="1.0" encoding="ISO-8859-1"?>

byggesak xmlns=" xmlns:xs=" xmlns:xsi=" xsi:schemaLocation="

sak soknadstype="soknad rammetillatelse">

soknad/>

</sak

</byggesak

XML schema for tiltaksType parameter: it is an official Byggesak version 2.0 XML schema, published & documented separately. For this parameter, only tags related to project type need to be filled in (others will be skipped if present). Below is an example of XML data (notice that it’s important to state correct XML namespace for main element and correct accessible schema location for that namespace as well):

<?xml version="1.0" encoding="ISO-8859-1"?>

byggesak xmlns=" xmlns:xs=" xmlns:xsi=" xsi:schemaLocation="

sak

typetiltak

nyebygg

nyttbygg

over70m2/>

</nyttbygg

</nyebygg

</typetiltak

</sak

</byggesak

3.1.2Methode: nySoknad

Method for creating a new application in the existing project. New application is always based on already existing application (as in Byggesak GUI). All existing data will be “cloned” from base (source) application with some modifications (same rules as in GUI). Created application will be placed into the same project folder as “source” application. Notice that only certain combinations of ‘tiltaksType’ and ‘soknadType’ are allowed.

Input parameters

systemBruker / String / System user for the system performing the service.
Password / String / Password associated to system user
sourceSoknadID / String / Application ID (exactly as returned from method nyByggesak or lesSoknadListeByggesak) to be used as base (source) application.
soknadType / base64Binary
(byte array) / XML data containing soknad (application) type. Not all soknad types are allowed for non-initial application in project (also, some types of application can appear only once in a project). Schema location for XML file is

Output parameters

nySoknadID / string / Application ID of newly created application
Feilbeskrivelse / string / XML-string which describes the error situation. Schema location for XML file

Return

Feilkode / integer / 0=ok, 1=error (in case of errors, ‘feilbeskrivelse’ contains additional info).

XML schema for soknadType parameter: it is an official Byggesak version 2.0 XML schema, published & documented separately. For this parameter, only tags related to application type need to be filled in (others will be skipped if present). Below is an example of XML data (notice that it’s important to state correct XML namespace for main element and correct accessible schema location for that namespace as well):

<?xml version="1.0" encoding="ISO-8859-1"?>

byggesak xmlns=" xmlns:xs=" xmlns:xsi=" identifier="10/228" xsi:schemaLocation="

sak soknadstype="soknad ferdigattest">

soknad

ferdigattest/>

</soknad

</sak

</byggesak

3.1.3Method: replaceSoknad

Method for replacing content of existing application in ByggSok: delete all the old data and insert all the new data. Updating/merging of partial data is not possible by this method. This method doesn’t handle binary attachments. “TiltaksType” and

“SoknadType” should be present in incoming data, but need to be same as in target application, to prevent prohibited modifications (Allowed combinations of ‘tiltaksType’ and ‘soknadType’ described in spreadsheet “Mapping GUI-XML”).

Input parameters

Systembruker / string / System user for the system performing the service.
Password / string / Password associated to system user
soknadID / string / Application ID of the target application (exactly as returned from method nyByggesak or lesSoknadListeByggesak).
Soknad / base64Binary
(byte array) / XML data containing complete application data. Schema location for XML file is

Output parameters

Feilbeskrivelse / string / XML-string which describes the error situation. Schema location for XML file

Return

Feilkode / integer / 0=ok, 1=error (in case of errors, ‘feilbeskrivelse’ contains additional info).

XML schema for Soknad parameter: it is an official Byggesak version 2.0 XML schema, published & documented separately. For this parameter, full data including application and project types need to be filled in (notice that types should be same as in target application – they can’t be changed through this method). Below is an example of XML data (notice that it’s important to correctly state all needed XML namespaces for elements and accessible schema location for namespace of main element as well):

<?xml version="1.0" encoding="ISO-8859-1"?>

byggesak xmlns=" xmlns:ans=" xmlns:be=" xmlns:bns=" xmlns:fns=" xmlns:mens=" xmlns:my=" xmlns:xs=" xmlns:xsi=" identifier="11/82" xsi:schemaLocation="