2. The DGP protocol

2.1. SOAP Encoding

Communication between portal and data servers takes place by exchanging SOAP 1.2 messages over HTTP. The SOAP messages are always grouped as synchronous request / response pairs. A protocol client sends out a request which in turn is answered by a proper response.

Each SOAP message (request or response) contains only a single communication object. The object is send within a single SOAP Body element. The SOAP Header element is not used by the DGP. All possible communication objects are specified by the DGP communication model described in INTERLIS 2 (see also appendix A).

All request messages have to be authenticated. Authentication is done by sending a user / password with each request message. Servers should not accept request, if they are not authenticated correctly.

2.2. Data Server Interface

The following request / response messages have to be implemented by a data server:

2.2.1. CalculatePrice

Request Object

DGP10.DataServer.CalculatePriceRequest.

Response Object

DGP10.DataServer.CalculatePriceResponse.

Response Error Object

DGP10.DataServer.ErrorResponse.

Call Semantics

With CalculatePrice the portal server can request the price of any known data product in the data network. A data server has to process the request and deliver a valid CalculatePriceResponse object or an ErrorResponse. Data servers have take into account that a product has product parameters and that the parameter values may affect the price.

Because the price calculation is done interactively on the portal server the price has to be delivered within 15 seconds by each data server.

Example 1. CalculatePrice Request

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Body>
    <DGP10.DataServer.CalculatePriceRequest>
      <User>test</User>
      <Password>test</Password>
      <Product>
        <DGP10.DataProduct>
          <ProductName>INTERLIS1</ProductName>
          <ModelName>DM01AVCH24D</ModelName>
          <TopicNames>FixpunkteKategrie1,Liegenschaften</TopicNames>
          <Range>
            <SURFACE>
              <BOUNDARY>
                <POLYLINE>
                  <COORD><C1>480000.000</C1><C2>70000.000</C2></COORD>
                  <COORD><C1>850000.000</C1><C2>70000.000</C2></COORD>
                  <COORD><C1>850000.000</C1><C2>310000.000</C2></COORD>
                  <COORD><C1>480000.000</C1><C2>310000.000</C2></COORD>
                  <COORD><C1>480000.000</C1><C2>70000.000</C2></COORD>
                </POLYLINE>
              </BOUNDARY>
            </SURFACE>
          </Range>
        </DGP10.DataProduct>
      </Product>
    </DGP10.DataServer.CalculatePriceRequest>
  </env:Body>
</env:Envelope>

Example 2. CalculatePrice Response

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Body>
    <DGP10.DataServer.CalculatePriceResponse>
      <Price>85.50</Price>
      <Currency>CHF</Currency>
    </DGP10.DataServer.CalculatePriceResponse>
  </env:Body>
</env:Envelope>

2.2.2. ExecuteOrder

Request Object

DGP10.DataServer.ExecuteOrderRequest.

Response Object

DGP10.DataServer.ExecuteOrderResponse

Response Error Object

DGP10.DataServer.ErrorResponse.

Call Semantics

With ExecuteOrder the portal server can order datasets from a connected data server. Each data server has to process the request and deliver a valid ExecuteOrderResponse object or an ErrorResponse. The ExecuteOrderResponse object contains the requested data as zipped dataset embedded with base64 encoding in the data stream.

There are no response time limits for ExecuteOrderRequest, because a large order request may take a long time to process. The portal server handles this delay by sending the resulting dataset by e-mail to the customer after it has merged all the partial results from the data servers. The customer doesn't have to wait interactively for the finished result.

Example 3. ExecuteOrder Request

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Body>
    <DGP10.DataServer.ExecuteOrderRequest>
      <User>test</User>
      <Password>test</Password>
      <Order>
        <Customer>
          <Name1>infoGrips GmbH</Name1>
          <Street>Obstgartenstrasse 7</Street>
          <Zip>8035</Zip>
          <City>Z&#252;rich</City>
          <EMail>info@infogrips.ch</EMail>
        </Customer>
        <Product>
          <DGP10.DataProduct>
            <ProductName>INTERLIS1</ProductName>
            <ModelName>DM01AVCH24D</ModelName>
            <TopicNames>FixpunkteKategrie1,Liegenschaften</TopicNames>
            <Range>
              <SURFACE>
                <BOUNDARY>
                  <POLYLINE>
                    <COORD><C1>480000.000</C1><C2>70000.000</C2></COORD>
                    <COORD><C1>850000.000</C1><C2>70000.000</C2></COORD>
                    <COORD><C1>850000.000</C1><C2>310000.000</C2></COORD>
                    <COORD><C1>480000.000</C1><C2>310000.000</C2></COORD>
                    <COORD><C1>480000.000</C1><C2>70000.000</C2></COORD>
                  </POLYLINE>
                </BOUNDARY>
              </SURFACE>
            </Range>
          </DGP10.DataProduct>
        </Product>
      </Order>
    </DGP10.DataServer.ExecuteOrderRequest>
  </env:Body>
</env:Envelope>

Example 4. ExecuteOrder Response

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Body>
    <DGP10.DataServer.ExecuteOrderResponse>
      <Dataset>XTLJILUOLJ808mmkmluOLKJLKJLKLRA...</Dataset>
    </DGP10.DataServer.ExecuteOrderResponse>
  </env:Body>
</env:Envelope>

2.3. Portal Server Interface

The following request / response messages have to implemented by the portal server:

2.3.1. MetadataUpload

Request Object

DGP10.PortalServer.MetadataUploadRequest.

Response Object

DGP10.PortalServer.MetadataUploadResponse

Response Error Object

DGP10.PortalServer.ErrorResponse.

Call Semantics

Notifies the portal server that a new dataset is available on the dataserver. The dataset name has to be unique within the datasets of the same data model / data server.

Example 5. MetadataUpload Request

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Body>
     <DGP10.PortalServer.MetadataUploadRequest>
        <User>test</User>
        <Password>test</Password>
        <MetaData>
          <DGP10.MetaData>
            <ModelName>DM01AVCH24D</ModelName>
            <DatasetName>test</DatasetName>
            <Range>
              <SURFACE>
                <BOUNDARY>
                  <POLYLINE>
                    <COORD><C1>480000.000</C1><C2>70000.000</C2></COORD>
                    <COORD><C1>850000.000</C1><C2>70000.000</C2></COORD>
                    <COORD><C1>850000.000</C1><C2>310000.000</C2></COORD>
                    <COORD><C1>480000.000</C1><C2>310000.000</C2></COORD>
                    <COORD><C1>480000.000</C1><C2>70000.000</C2></COORD>
                  </POLYLINE>
                </BOUNDARY>
              </SURFACE>
            </Range>
          </DGP10.MetaData>
        </MetaData>
     </DGP10.PortalServer.MetadataUploadRequest>
  </env:Body>
</env:Envelope>

Example 6. MetadataUpload Response

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Body>
    <DGP10.PortalServer.MetadataUploadResponse>
    </DGP10.PortalServer.MetadataUploadResponse>
  </env:Body>
</SOAP-ENV:Envelope>

2.3.2. MetadataDelete

Request Object

DGP10.PortalServer.MetadataDeleteRequest.

Response Object

DGP10.PortalServer.MetadataDeleteResponse

Response Error Object

DGP10.PortalServer.ErrorResponse.

Call Semantics

Requests from the portal server to delete a previously uploaded meta data dataset.

Example 7. MetadataDelete Request

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Body>
     <DGP10.PortalServer.MetadataDeleteRequest>
        <User>test</User>
        <Password>test</Password>
        <ModelName>DM01AVCH24D</ModelName>
        <DatasetName>test</DatasetName>
     </DGP10.PortalServer.MetadataDeleteRequest>
  </env:Body>
</env:Envelope>

Example 8. MetadataDelete Response

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Body>
    <DGP10.PortalServer.MetadataDeleteResponse>
    </DGP10.PortalServer.MetadataDeleteResponse>
  </env:Body>
</env:Envelope>