Client API

Software Answers offers its Oscar Enterprise/Orion clients the ability to subscribe to the Client API. There is a monthly fee for this service. The Client API is a Microsoft .NET WCF Service that exposes numerous methods/functions for retrieving data as well as inserting and updating certain data elements within the application. New methods are added every couple of months. The service documentation can be found here.

Oscar Enterprise and Oscar Orion use the exact same database. If necessary, simultaneously. Thus, the Client API will work the same with both applications. If you are a client migrating from Enterprise to Orion, there is no need to change any of the code that has been written against the Client API. Any API assembly references to SoftwareAnswers.Oscar.Enterprise... also work with Orion.

Using C#/VB .NET as your development platform will greatly reduce time and cost. It has tools that make working with our API much easier. The API can be used by other development environments such as Java, ASP, or PHP. It is just a bit more cumbersome.

ChatGPT

ChatGPT is an option for reading the WSDL and generating code for specific methods. For best results, download the WSDL from the service url https://api-domain-name-goes-here/Oscar.svc?wsdl and save it to a text file you can upload to ChatGPT. Give it the following instructions:

Analyze this Microsoft WCF Service WSDL and generate PHP code to call the GetReservationsByReservationSearchQuery method.

Add code to populate the Request node's MethodApiKey collection with the method name of GetReservationsByReservationSearchQuery and a sample uniqueidentifier / C# System.Guid value. The MethodApiKey parameter is a child collection of the Request node.

Add code to print all the xml node names and values from $response.

Add code to validate the AsyncResult node's OperationSuccessful boolean is true or false. If false, display the AsyncResult node Message and RuleExceptions that are returned in $response.

How To

The Oscar system is very large and its data/concepts quite complex. It will take time for the developer(s) interacting with our API to learn how the system works. This is especially true if the developer(s) have little to no experience using our front end application. With that in mind, we offer a few suggestions for expediting that process.

Collaboration

Assign someone highly familiar with the front application to be a liaison to the development team. This relationship will expedite the development cycle especially when it comes to saving data. If possible, set up an environment where the developer(s) can use the front end application by themselves or in partnership with the liaison. Our documentation is pretty thorough but there is no substitute for real world experience with the front end application.

Understanding Data

Learning the various data values is the first step. We recommend having an Oscar user create/modify a record(s) in the front application to match the desired functionality. Then, provide that record id to the development team. They would use the appropriate "get" object method (i.e. GetUnit or GetProperty) to return that specific record to review the class property values. If necessary, rinse and repeat with different values for the same record. This tactic will expedite the learning process. A great example of this would be staging a reservation with all its financial settings, populate a few custom field values on the reservation, a couple of tenants with a few custom field values populated, a few charges including the rent charge, foreign currency (if applicable), and perhaps multiple rent rates. Upon completion, call GetReservationContainer with that same reservation id to review the reservation, notes, tenants, tenant charge definitions, and tenant charge definition rate records. All of the billing frequency settings will be there, any custom field values, and various other settings.

Custom Fields

Custom fields can be defined on many of the data object types available. No two Oscar installations/configurations are the same. GetCustomFieldDefinitions and GetCustomFieldComboBoxDefinitions are the two methods that hold field customizations for all the tables/data objects. Many of the table names in Oscar lack modern naming standards. The API attempts to hide that from developers but the custom field definitions expose that a bit. The CustomFieldValues collection on these data objects is where the captured values are stored. The following are commonly confused Oscar tables and their corresponding object type:

reservlst = Reservation
userlst = User
propertylst = Property
udefinitionlst = Unit Definition (field of the Unit object)
tenantlst = Tenant
cclientlst = Corporate Client

There is a C# .NET code sample below that demonstrates how to iterate the CustomFieldValues collection.

Inserting Data

Oscar data validation requirements are complex. In most cases, any object that is permitted to be saved via the API has a matching method for just calling the validation. i.e. SaveUnit and ValidateUnit. SaveUnit will call ValidateUnit internally. So, it isn't necessary to call them both at runtime. Validate is there more for development purposes enabling you to submit a record to see if it would pass all the business rule requirements without fear of modifying data if it did pass.

Many clients do not have QA or test environments which requires 3rd party vendors to develop against their production database. This helps with that. Another tactic used is to create fake markets, properties, units, corporate clients, and vendors. Again, enabling the development team to work against a production environment without near as much risk modifying production data.

The learning tactic we suggest is to create a new instance of the desired data object and do not populate any values. Then, call the validate method. If there are validation failures, they will show up in the AsyncResult.RuleExceptions collection. Depending on the object, you will either get all the failures in the collection or only those critical values that were missing to even attempt further validation. So, you may have to repeat this process until you ultimately get an AsyncResult.OperationSuccessful = true.

Copying Data

In virtually all cases, a developer can query an existing record, set its primary key to 0 (i.e. ReservationID=0 or UnitID=0), and call the applicable "save" object method (i.e. SaveReservation or SaveUnit). You end up with a copy of the original record. A few vendors create "base" or "copy from" reservations, vendors, or units that have specific default values the client wants set on records. At runtime, query this "base" record, alter its id, change a few property values, and save the new record.

Updating Data

We strongly recommend the "get" object method be called to get the current state of the object prior to attempting to save it. If you opt to create your own instance of the object with what you think are "all" of its current property values, you will almost always overwrite existing property values with the wrong/empty values. Our system always takes the whole object and attempts to save all of its property values.

Integration Strategies

Oscar clients are a very, very diverse group each needing to query data in their own unique way. There are a gazillion different ways data might need to be extracted. With that in mind, the Client API features data retrieval methods to acquire the primary keys/unique ids of various record types that have been created or updated within a given timeframe. These timeframes could be the entire history of use or just the last few minutes and everywhere in between. Using the collection of ids returned, the API methods for retrieving specific records would be used. This strategy enables development teams to export and store data externally from Oscar for use with their own custom queries and functionality. Exporting unit availability and reservation data for use on an external web site is a common scenario. Scheduled jobs could run throughout the day looking for updated data in Oscar that needs to be synchronized with an external data storage solution. Many clients run this as often as every five minutes looking for changes in the last few minutes. At the end of the day, many will run a query looking for ids that have changed in the last couple of days to try and make sure nothing was missed.

Challenges

Oscar clients can define numerous aspects of their installation with each client being quite different from the other. One example is unit types. The UnitTypeID in one client does not mean the same thing with other clients. 3rd party API users will need to accommodate these differences and create their own internal codes and match up the correlating data in the Oscar installation.

The accounting functionality in Oscar is highly customized. One example is with what Reservation charge amounts get written to which ledgers. The API will most likely override any charge definition account ids sent in with those dictated by that client's Oscar configuration. 3rd party vendors wishing to submit reservations are encouraged to submit a tenant charge for rent and then include all other charges in a single note. The Oscar user can manually use that note to create the charges and assign them to the appropriate accounts.

Future

Software Answers is constantly updating the Client API with new methods. Most will follow the strategy mentioned above concerning the retrieval of records changed within a given timeframe in conjunction with a method to retrieve that specific method type. If your development team/3rd party vendor need to query data that isn't available via this strategy, please submit a support ticket. Only requests from actual Oscar users will be considered. 3rd party vendors should refrain from asking us to customize the Client API.

Access Rights

The Client API has two use case scenarios: internal development team and external third party development teams. The .config file for the API has a setting labeled EnabledMethodByMethodAccess. By default, this is set to false. The .config file also includes the global ClientApiKey that is provided to each client by Software Answers at installation of the Client API. The default configuration enables internal development teams complete access. The developers simply need to include the ClientApiKey on the Request object for each method call.

If EnableMethodByMethodAccess is set to true (for 3rd party vendor access this is almost always true), then the client will need to define one or more API users in Oscar, select the methods to grant access, and export a license file for delivery to the 3rd party development team. This feature is available from within Oscar under the Settings menu with the option labelled Client API Permissions. Each API user defined can have completely different access rights. By default, SOFTWARE ANSWERS is created as an API user and is granted complete access to the Client API. This includes new API methods as they are made available. However, an Oscar user can turn off specific methods even for SOFTWARE ANSWERS should they choose to.

Creating the API License File in Oscar

Step 1: click the settings menu option below:

Step 2: define an API User (this is often the company name of the vendor using the client's instance of the API) by clicking the API Users button (screenshot below). Upon completion, return to this screen and follow the instructions at the top.

How to use the API License File

Each request to the API requires a Request object as an input parameter. Most 3rd party vendors create a single instance of the Request object, load it up with all the MethodApiKeys they are licensed for, and reuse it every time they call an API method. You can just send in the MethodApiKey for that specific method but it will become cumbersome.

Sample Code (C# .NET)

var url = "web service url goes here";
var bind = new BasicHttpBinding();
var endPoint = new EndpointAddress(url);
bind.Security.Mode = BasicHttpSecurityMode.Transport;
bind.MaxReceivedMessageSize = 2147483647;
bind.MaxBufferSize = 2147483647;
bind.MaxBufferPoolSize = bind.MaxBufferSize;
bind.ReaderQuotas.MaxArrayLength = 2147483647;
bind.ReaderQuotas.MaxBytesPerRead = 2147483647;
bind.ReaderQuotas.MaxDepth = 2147483647;
bind.ReaderQuotas.MaxNameTableCharCount = 2147483647;
bind.ReaderQuotas.MaxStringContentLength = 2147483647;
bind.SendTimeout = TimeSpan.FromSeconds(60);
var wcf = new Test.Console.OscarService.OscarClient(bind, endPoint);
var request = new Request();
var licenseFileName = "Full Path To License Filename Provided To You By Oscar Client";
var xml = new XmlDocument();
xml.Load(licenseFileName);
request.ClientApiKey = new Guid(xml.SelectSingleNode("//Configuration/Client/ClientApiKey").InnerText);
request.MethodApiKeys = new List<MethodApiKey>();
var nodes = xml.SelectNodes("//Configuration/Methods/Method");
if (nodes == null) return;
foreach (XmlNode node in nodes)
{
    var methodApiKey = new MethodApiKey();
    methodApiKey.Name = node.Attributes["name"].Value.Trim();
    methodApiKey.MethodApiKeyID = new Guid(node.Attributes["apikey"].Value.Trim());
    request.MethodApiKeys.Add(methodApiKey);
}
// Store this request object somewhere globally in your app and reuse it whenever a WCF method is called.
var workOrderID = 132;  // Random/Sample work order id
var record = wcf.GetWorkOrder(request, workOrderID, out asyncResult);
if (record != null)
{
    System.Console.WriteLine(record.AssignedToUserID);
    if (record.CustomFieldValues != null)
    {
        foreach (var item in record.CustomFieldValues)
        {
            System.Console.WriteLine(item.ColumnName + " " + item.Value);
        }
    }
}
else
{
    System.Console.WriteLine("return value is null");
    System.Console.WriteLine(asyncResult.Message);
    if (asyncResult.RuleExceptions != null)
    {
        foreach (var exception in asyncResult.RuleExceptions)
        {
            System.Console.WriteLine(exception.Message);
        }
    }
}

Sample SOAP XML for PHP

If the development team does not have a SOAP Client component, then they will need to issue HttpPost requests and include SOAP XML in the stream and then parse the SOAP XML response that comes back.

All of the xml nodes are required to ensure proper serialization/deserialization. The only exception to that is the MethodApiKeys collection. You can leave out MethodApiKey nodes that are not relevant to your method call. The service supports loading all the available method api keys at once and just reuse them to make coding easier. It does make for a larger block of data though.

*** To learn the xml structure of a given object, query it first for review. That same structure will be used when saving changes to the object.

Request Message Structure for GetReservationIDsBySearch

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <Action s:mustUnderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">
      http://tempuri.org/IReservation/GetReservationIDsBySearch
    </Action>
  </s:Header>
  <s:Body>
    <GetReservationIDsBySearch xmlns="http://tempuri.org/">
      <request xmlns:d4p1="http://schemas.datacontract.org/2004/07/SoftwareAnswers.Oscar.Enterprise.DataObjects"
               xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <d4p1:ClientApiKey>{Client API Key Goes Here}</d4p1:ClientApiKey>
        <d4p1:IsEnterprise>true</d4p1:IsEnterprise>
        <d4p1:MethodApiKeys>
          <d4p1:MethodApiKey>
            <d4p1:MethodApiKeyID>{Method Api Key Goes Here}</d4p1:MethodApiKeyID>
            <d4p1:Name>GetDataBaseServerDateTime</d4p1:Name>
          </d4p1:MethodApiKey>
          <d4p1:MethodApiKey>
            <d4p1:MethodApiKeyID>{Method Api Key Goes Here}</d4p1:MethodApiKeyID>
            <d4p1:Name>GetReservation</d4p1:Name>
          </d4p1:MethodApiKey>
          <d4p1:MethodApiKey>
            <d4p1:MethodApiKeyID>{Method Api Key Goes Here}</d4p1:MethodApiKeyID>
            <d4p1:Name>GetReservationIDsBySearch</d4p1:Name>
          </d4p1:MethodApiKey>
          <d4p1:MethodApiKey>
            <d4p1:MethodApiKeyID>cad1d750-ae30-44e2-a8b0-e1e905d175a5</d4p1:MethodApiKeyID>
            <d4p1:Name>GetWebServerDateTime</d4p1:Name>
          </d4p1:MethodApiKey>
        </d4p1:MethodApiKeys>
        <d4p1:OscarUserID>0</d4p1:OscarUserID>
      </request>
      <startDate>2021-01-01T00:00:00</startDate>
      <endDate>2021-09-30T00:00:00</endDate>
    </GetReservationIDsBySearch>
  </s:Body>
</s:Envelope>

Response Message Structure

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header />
  <s:Body>
    <GetReservationIDsBySearchResponse xmlns="http://tempuri.org/">
      <GetReservationIDsBySearchResult
          xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays"
          xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:int>392823</a:int>
        <a:int>391608</a:int>
        <a:int>390279</a:int>
        <a:int>392833</a:int>
        <a:int>391606</a:int>
        <a:int>391675</a:int>
        <a:int>392759</a:int>
        <a:int>392680</a:int>
      </GetReservationIDsBySearchResult>
      <asyncResult xmlns:a="http://schemas.datacontract.org/2004/07/SoftwareAnswers.ErrorManagement"
                   xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:IsRuleException>false</a:IsRuleException>
        <a:Message i:nil="true" />
        <a:OperationSuccessful>true</a:OperationSuccessful>
        <a:RuleExceptions />
        <a:StackTrace i:nil="true" />
      </asyncResult>
    </GetReservationIDsBySearchResponse>
  </s:Body>
</s:Envelope>

Request Message Structure for GetReservation — using the first reservation id returned above to get the whole record.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <Action s:mustUnderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">
      http://tempuri.org/IReservation/GetReservation
    </Action>
  </s:Header>
  <s:Body>
    <GetReservation xmlns="http://tempuri.org/">
      <request xmlns:d4p1="http://schemas.datacontract.org/2004/07/SoftwareAnswers.Oscar.Enterprise.DataObjects"
               xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <d4p1:ClientApiKey>{Client API Key Goes Here}</d4p1:ClientApiKey>
        <d4p1:IsEnterprise>true</d4p1:IsEnterprise>
        <d4p1:MethodApiKeys>
          <d4p1:MethodApiKey>
            <d4p1:MethodApiKeyID>{Method Api Key Goes Here}</d4p1:MethodApiKeyID>
            <d4p1:Name>GetDataBaseServerDateTime</d4p1:Name>
          </d4p1:MethodApiKey>
          <d4p1:MethodApiKey>
            <d4p1:MethodApiKeyID>{Method Api Key Goes Here}</d4p1:MethodApiKeyID>
            <d4p1:Name>GetReservation</d4p1:Name>
          </d4p1:MethodApiKey>
          <d4p1:MethodApiKey>
            <d4p1:MethodApiKeyID>{Method Api Key Goes Here}</d4p1:MethodApiKeyID>
            <d4p1:Name>GetReservationIDsBySearch</d4p1:Name>
          </d4p1:MethodApiKey>
          <d4p1:MethodApiKey>
            <d4p1:MethodApiKeyID>cad1d750-ae30-44e2-a8b0-e1e905d175a5</d4p1:MethodApiKeyID>
            <d4p1:Name>GetWebServerDateTime</d4p1:Name>
          </d4p1:MethodApiKey>
        </d4p1:MethodApiKeys>
        <d4p1:OscarUserID>0</d4p1:OscarUserID>
      </request>
      <reservationID>392823</reservationID>
    </GetReservation>
  </s:Body>
</s:Envelope>