Web Service Request and Responses 

This documentation is designed to inform advanced users on the "behind the scenes" communication between the Open Dental Web Version and the web service.  In this document, the web version will be referenced as the "client" and the web service will be referenced as the "server". This is not the same as our Middle Tier for the OpenDentalServer.

Requests

Requests sent from the client are always handled using data transfer objects or dto.  A typical request will look like:

<DtoGetTable>
    <MethodName>Patients.GetPtData</MethodName>
    <Params>
        <DtoObject>
            <TypeName>bool</TypeName>
            <Obj>
                <bool>1</bool>
            </Obj>
        </DtoObject>
        <DtoObject>
            <TypeName>bool</TypeName>
            <Obj>
                <bool>0</bool>
            </Obj>
        </DtoObject>
    </Params>
</DtoGetTable>

The XML format of the DTO is identical in both the web version and the older middle tier.  But the underlying code has now changed to avoid reflection entirely.  This was required because JavaScript does not support reflection, and this change should also result in much better speed.  The new DTO contains a list of strings called ParamTypes that directly correlates with the list of parameters so that we can quickly determine each parameter's type.  There is also a string called Type which holds the type of DTO request that was sent which is set based on the parent node of the request.

Note: There will be some form of credentials that will get passed along with every message.  The DTO request example will change in the future to reflect those changes.

Request Breakdown:
Type:  The parent node of the request is always the type of dto being sent.  Examples:
DtoGetTable
DtoGetString
DtoGetObject
DtoGetVoid
For all the supported types of DTO messages, refer to the code: OpenDentalWebService/Remoting/DataTransferObject.cs

MethodName: The method to call.  This must always be in "Class.Method" format.

Params: A list of DtoObjects.  This node will typically contain a DtoObject for each parameter of the calling method.  It is possible that the Params list will be empty if the calling method does not require parameters.

DtoObjects:
DtoObjects contain a string called TypeName and an object called Obj.  TypeName stores type of the object and Obj stores the object itself.  Another example of a DtoObject is:

<DtoObject>
    <TypeName>Account</TypeName>
    <Obj>
        <Account>
            <AccountNum>1234</AccountNum>
            <Description>Account Desc</Description>
            <AcctType>2</AcctType>
            <BankNumber>123456789</BankNumber>
            <Inactive>0</Inactive>
            <AccountColor>16777215</AccountColor>
         </Account>
    </Obj>
</DtoObject>

Note:  Some objects in the Obj section will be handled differently due to restrictions in JavaScript.  To see how the Obj portion is created, refer to OpenDentalWeb/com/opendental/odweb/client/remoting/Serializing.java's GetSerializedObject method.  Otherwise, these DtoObjects are identical to the older web service DtoObjects.

All requests are executed by the server and then a response message is sent back.

Responses

The different types of responses will directly correlate to the type of DTO request that is being made.  Meaning, a DtoGetInt object will return an int and a DtoGetTable will return a DataTable.  However, there will always be a possibility that a DtoException will get returned.  The code needs to be able to handle both types of responses.  Some examples of how those responses would look are:

Int response:
<int>8317</int>

Object response:
<Account>
    <AccountNum>1234</AccountNum>
    <Description>Account Desc</Description>
    <AcctType>2</AcctType>
    <BankNumber>123456789</BankNumber>
    <Inactive>0</Inactive>
    <AccountColor>16777215</AccountColor>
</Account>

Void response:
<ack/>

Data table response:
<DataTable>
    <Name>Accounts</Name>
    <Cols>
        <Col>type</Col>
        <Col>Description</Col>
        <Col>balance</Col>
        <Col>BankNumber</Col>
        <Col>inactive</Col>
        <Col>color</Col>
        <Col>AccountNum</Col>
    </Cols>
    <Cells>
        <y>
            <x>Asset</x>
            <x>Accumulated Amort, Intagibles</x>
            <x>-99.00</x>
            <x/>
            <x/>
            <x>-1</x>
            <x>123</x>
        </y>
    </Cells>
</DataTable>

DtoException response:
<DtoException>
    <msg>Error message text goes here.</msg>
</DtoException>

Response Breakdown:
Responses from the server are going to be very straightforward much like the int example, except data tables and the exceptions.

Data Tables:  The node "Name" is the name of the table.  "Cols" will contain child nodes called Col which hold the name of each column.  Eventually we will enhance the DTO to hold the types of the columns as well.  "Cells" will hold the information that will populate the rows and columns, or in our case, the y's and x's.  There can be any number of rows (y's) but there has to be an x for every column or Col.

Note:  Notice that empty columns are represented as <x/>.

DtoExceptions: For now, any exceptions that occur on the server will respond with a DtoException that just has the error message text nested in the msg node.