OData Connector - Source Code

<?xml version="1.0" encoding="utf-8"?>
<ApiConfig Name="OData" 
	Version="3" Id="20D2A29F-D8F3-404E-9344-66D3CF7C1FAB"
	Slug="odata-connector"
	Desc="OData Connector can be used to integrated any REST API which supports OData Standard. You can view tables, read data from tables using this connector. It also comes with some example OData Services to get started."
	HelpLink="https://www.odata.org/getting-started/"
	Logo="https://www.odata.org/assets/ODataLogo-96.png"
	EngineVersion="2" 
	>

  <VersionHistory>
	  <Change Date="2024-06-11" Type="New">Added PageSize parameter to control Max Rows Per Response ($top) setting.</Change>	  
    <Change Date="2023-08-15" Type="New">Added SslVersion Property for Connection</Change>	  
    <Change Date="2023-08-15" Type="New">Added IgnoreSSLCertificateErrors Property to support self-signed certificates (Ignore not trusted error)</Change>	
    <Change Date="2021-03-15">Renamed $filter to SearchCriteria and $format to DataFormat</Change>
    <Change Date="2020-12-01">Initial version</Change>
  </VersionHistory>

  <ServiceUrls>
    <ServiceUrl Name="Example-1 : Northwind OData Service" Url="https://services.odata.org/V3/Northwind/Northwind.svc" />
    <ServiceUrl Name="Example-2 : Sample OData Service" Url="https://services.odata.org/V3/OData/OData.svc" />
    <ServiceUrl Name="Example-3 : TripPin OData Service" Url="https://services.odata.org/TripPinRESTierService" />
  </ServiceUrls>

  <Auths>
    <Auth Type="HTTP"  Label="No Authentication" ConnStr="URL=https://ignored;" TestEndPoint="list_tables_json" >
      <Params>
        <Param Name="RetryMode" Value="RetryWhenStatusCodeMatch" Options="None;RetryAny;RetryWhenStatusCodeMatch;" Hidden="True" />
        <Param Name="RetryStatusCodeList" Value="429" Hidden="True" />
        <Param Name="RetryCountMax" Value="5" Hidden="True" />
        <Param Name="RetryMultiplyWaitTime" Value="True" Hidden="True" />  		
        <Param Name="IgnoreSSLCertificateErrors" Options=";True;False" />  				
		<Param Name="SslVersion" Type="Property" />  				
		
      </Params>              
    </Auth>
    <Auth Type="HTTP" Name="WinAuth" Label="Windows Authentication" ConnStr="URL=https://ignored;CredentialType=Windows;" TestEndPoint="list_tables_json" >
    </Auth>
    <Auth Type="HTTP" Name="BasicAuth" Label="Basic Authentication" ConnStr="URL=https://ignored;CredentialType=Basic;" TestEndPoint="list_tables_json" >
      <Params>
        <Param Name="UserName" Required="True"/>
        <Param Name="Password" Secret="True"  Required="True"/>
        <Param Name="RetryMode" Value="RetryWhenStatusCodeMatch" Options="None;RetryAny;RetryWhenStatusCodeMatch;" Hidden="True" />
        <Param Name="RetryStatusCodeList" Value="429" Hidden="True" />
        <Param Name="RetryCountMax" Value="5" Hidden="True" />
        <Param Name="RetryMultiplyWaitTime" Value="True" Hidden="True" />  		
        <Param Name="IgnoreSSLCertificateErrors" Options=";True;False" />  			
        <Param Name="SslVersion" Type="Property" />  						
      </Params>              
    </Auth>
    <Auth Type="HTTP" Name="NtlmAuth" Label="NTLM Authentication" ConnStr="URL=https://ignored;CredentialType=NTLM;" TestEndPoint="list_tables_json" >
      <Params>
        <Param Name="UserName" Label="UserName (i.e. Domain\UserName)" Required="True"/>
        <Param Name="Password" Secret="True"  Required="True"/>
        <Param Name="RetryMode" Value="RetryWhenStatusCodeMatch" Options="None;RetryAny;RetryWhenStatusCodeMatch;" Hidden="True" />
        <Param Name="RetryStatusCodeList" Value="429" Hidden="True" />
        <Param Name="RetryCountMax" Value="5" Hidden="True" />
        <Param Name="RetryMultiplyWaitTime" Value="True" Hidden="True" />  
        <Param Name="IgnoreSSLCertificateErrors" Options=";True;False" />  		
        <Param Name="SslVersion" Type="Property" />  								
      </Params>
    </Auth>
    
    <Auth Type="HTTP" Name="TokenAuth" Label="Token Authentication" ConnStr="URL=https://ignored;CredentialType=Token;AuthScheme=[$AuthScheme$];TokenAuthHeader=[$AuthHeader$];" TestEndPoint="list_tables_json" >
      <Params>
        <Param Name="AuthScheme" Value="Bearer" />
        <Param Name="AuthHeader" Value="Authorization" />        
        <Param Name="Password" Label="Token" Secret="True" Required="True"/>
        <Param Name="RetryMode" Value="RetryWhenStatusCodeMatch" Options="None;RetryAny;RetryWhenStatusCodeMatch;" Hidden="True" />
        <Param Name="RetryStatusCodeList" Value="429" Hidden="True" />
        <Param Name="RetryCountMax" Value="5" Hidden="True" />
        <Param Name="RetryMultiplyWaitTime" Value="True" Hidden="True" />  		
        <Param Name="IgnoreSSLCertificateErrors" Options=";True;False" /> 
        <Param Name="SslVersion" Type="Property" />  								
      </Params>
    </Auth>   

    <Auth Type="OAuth" Name="OAuthAuth" Label="OAuth Connection for OData API" Help="https://zappysys.com/s=odata"
          ConnStr="Provider=Custom;OAuthVersion=OAuth2;ScopeSeparator={space};UseCustomApp=True;"
           TestEndPoint="list_tables_json">
      <Params>
        <Param Name="GrantType"  Value="Default" />
        <Param Name="OAuthVersion" Value="Default" />
        <Param Name="ClientId"  />
        <Param Name="ClientSecret" Secret="True"  />
        <Param Name="UserName" Desc="Only used with password grant type" Hidden="False" VisibleIf="GrantType==Password" />
        <Param Name="Password" Desc="Only used with password grant type" Secret="True" Hidden="False" VisibleIf="GrantType==Password" />
        
        <Param Name="Scope" Value="" Editor="MultiLine"/>
        <Param Name="AuthUrl" Value="https://some-domain.com/api/auth" VisibleIf="GrantType==Default | GrantType==AuthorizationCode" />
        <Param Name="TokenUrl" Value="https://some-domain.com/api/token" />
        <Param Name="ReturnUrl" Value="https://zappysys.com/oauth" />
        <Param Name="ExtraAttributesForTokenRequest" Type="Property" Hidden="False"/>
        <Param Name="ExtraAttributesForAuthRequest" Type="Property" Hidden="False" VisibleIf="GrantType==Default | GrantType==AuthorizationCode"/>
		
        <Param Name="RetryMode" Value="RetryWhenStatusCodeMatch" Options="None;RetryAny;RetryWhenStatusCodeMatch;" Hidden="True" />
        <Param Name="RetryStatusCodeList" Value="429" Hidden="True" />
        <Param Name="RetryCountMax" Value="5" Hidden="True" />
        <Param Name="RetryMultiplyWaitTime" Value="True" Hidden="True" />  		
        <Param Name="IgnoreSSLCertificateErrors" Options=";True;False" />  		
        <Param Name="SslVersion" Type="Property" />  								
      </Params>
    </Auth>
  </Auths>

  <Template>
    <!-- When name not specified in EndPoints node .. its considered as base for all other template -->
    <EndPoint>
      <Params>
        <Param Name="IgnoreSSLCertificateErrors" Type="Property" Options=";True;False" Desc="Set this option to True if you are getting Certificate Not Trusted error and you like to continue regardless (Only do it if you trust the remote server). This usually happens when Self-Signed certificate is used on ElasticSearch Instance and you did not trust that certificate on this machine" /> 
        <Param Name="Filter" Type="Property" Desc="Filter for JSON (e.g. $.rows[*] ). See sample JSON response to findout array name." Value="$.value[*]" Required="True" />
        <Param Name="Format" Key="$format" Type="Query" Desc="Response format" Value="json" Hidden="True" />
		    <Param Name="PageSize" Label="PageSize (Keep blank for default)" Key="$top" Type="Query" Desc="Number which indicates max rows per response. Keep it blank to use API default vlaue. Read your API documentation to findout default value." Hidden="True" />
        <Param Name="SearchCriteria" Key="$filter" Label="Search Criteria" Type="Query" Options="None=;Equal Serach=SomeColumn eq 'SomeValue';Sub String Serach=substringof(SomeField,'abc');Starts With=startswith(SomeField, 'abc');Value Greater Than=filter=mynumericfield gt 1234" Desc="Data filter (e.g. somecolumn -eq 'somevalue' )"  HelpLink="https://zappysys.com/links?url=https://docs.microsoft.com/en-us/dynamics-nav/using-filter-expressions-in-odata-uris"/>
        <Param Name="DataFormat" Type="Property" Value="OData" Hidden="True" />
      </Params>
    </EndPoint>
  </Template>

  <EndPoints>
    <EndPoint Name="list_tables_json" Label="List Tables (JSON API)" Url="/" Cached="True" CachedTtl="60" />
    <EndPoint Name="list_tables_xml" Label="List Tables (XML API)" Url="/" Cached="True" CachedTtl="60" />
    <EndPoint Name="read_data_json" Label="Generic Read Data (JSON API)" ResponseFormat="Json" Url="/[$TableName$]">
      <Params>
        <Param Name="TableName" Desc="Read data from specified module (Json Format API)" Value="" OptionsEndPoint="list_tables_json" OptionsEndPointValueColumn="name" />
      </Params>
    </EndPoint>
    <EndPoint Name="read_data_xml" Label="Generic Read Data (XML API)" ResponseFormat="Xml" Url="/[$TableName$]">
      <Params>
        <Param Name="TableName" Desc="Read data from specified module (Xml Format API)" Value="" OptionsEndPoint="list_tables_xml" OptionsEndPointValueColumn="name" />
      </Params>
    </EndPoint>

    <EndPoint Name="get_[$parent.name$]"
              Expand="True"
              DataEndPoint="list_tables_json"
              ResponseFormat="Json"
              Label="Read [$parent.name$]"
              Url="[$parent.url$]" >
    </EndPoint>

  </EndPoints>
  
  <Tables>
    <Table Name="[$parent.name$]" Expand="True" DataEndPoint="list_tables_json"
      SelectEndPoint="get_[$parent.name$]">
    </Table>
  </Tables>
  <Examples>
    <Example Group="ODBC" Label="Read all records from an JSON OData Service Table" Code="SELECT * FROM Customers"></Example>
    <Example Group="ODBC" Label="Read all records from an XML OData Service Table" Code="SELECT * FROM read_data_xml WITH(TableName='MyTable')"></Example>
    <Example Group="ODBC" Label="Filter records using server side criteria" Code="SELECT * FROM Customers WITH( SearchCriteria='Country -eq ''USA'' ')"></Example>
    <Example Group="ODBC" Label="Filter records using client side criteria" Code="SELECT * FROM Customers WHERE Country = 'USA'"></Example>
    <Example Group="ODBC" Label="List all Tables (JSON Based Format)" Code="SELECT * FROM list_tables_json"></Example>  
    <Example Group="ODBC" Label="List all Tables (XML Based Format)" Code="SELECT * FROM list_tables_xml"></Example>  
  </Examples>
</ApiConfig>