Reference

Source code

---

<?xml version="1.0" encoding="utf-8"?>
<ApiConfig Name="OData" 
  Version="5" Id="20D2A29F-D8F3-404E-9344-66D3CF7C1FAB"
  Slug="odata-connector"
  Desc="Read and write OData API data effortlessly. Query, integrate, and manage entities and feeds — almost no coding required."
  HelpLink="https://www.odata.org/getting-started/"
  Logo="https://www.odata.org/assets/ODataLogo-96.png"
  EngineVersion="6" 
  >
	
  <VersionHistory>
	<Change Ver="6" Date="2026-02-10" Type="New">Added new endpoints get_metadata_tables, get_metadata_columns.</Change>
	<Change Ver="5" Date="2025-01-15" Type="New">Added new properties for OAuth (DoNotIncludeCredentialsInHeader, DoNotIncludeCredentialsInBody, RenewBeforeSec, ExtraHeaders, ContentType, EnableCodeVerifier, CustomAuthHeader, CustomTokenPrefix and RemoveAuthHeader).</Change>	  
	<Change Ver="4" Date="2024-06-11" Type="New">Added PageSize parameter to control Max Rows Per Response ($top) setting.</Change>	  
    <Change Ver="3" Date="2023-08-15" Type="New">Added SslVersion Property for Connection</Change>	  
    <Change Ver="3" Date="2023-08-15" Type="New">Added IgnoreSSLCertificateErrors Property to support self-signed certificates (Ignore not trusted error)</Change>	
    <Change Ver="2" Date="2021-03-15">Renamed $filter to SearchCriteria and $format to DataFormat</Change>
    <Change Ver="1" 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="DoNotIncludeCredentialsInHeader" Type="Property" Hidden="False"/>
        <Param Name="DoNotIncludeCredentialsInBody" Type="Property" Hidden="False"/>
        <Param Name="RenewBeforeSec" Type="Property" Hidden="False"/>
        <Param Name="ExtraHeaders" Label="ExtraHeaders (e.g. x-hdr1:AAA||x-hdr2:BBB)" Type="Property" Hidden="False"/>
        <Param Name="ContentType" Type="Property" Options="Default=;Json=application/json" Hidden="False" />
        <Param Name="EnableCodeVerifier" Type="Property" Hidden="False"/>
        <Param Name="RemoveAuthHeader" Type="Property" Hidden="False"/>
        <Param Name="CustomAuthHeader" Type="Property" Hidden="False" />
        <Param Name="CustomTokenPrefix" Type="Property" Hidden="False" />
		
        <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>

    <EndPoint Name="get_metadata_tables" 
            ResponseFormat="Xml"
            Template="."
            Label="List Tables"
            Url="/$metadata"
            UseRawCache="True"
            Cached="True"
            Filter="$.edmx:Edmx.edmx:DataServices.Schema[*].EntityType[*]"
            IncludeParentColumns="True"
            CachedTtl="1440">
      <Params>
          <Param Name="MetaDetectionOrder" Type="Property" Value="Dynamic"  />
      </Params>
      <OutputColumns>
        <Column Name="@Name" Label="EntityName" DataType="DT_WSTR" Length="500" />
        <Column Name="Key.PropertyRef.@Name" Label="KeyPropertyName" DataType="DT_WSTR" Length="100" />
        <Column Name="Property" Label="Property" DataType="DT_NTEXT" />
        <Column Name="NavigationProperty_@Name" Label="NavigationPropertyName" DataType="DT_WSTR" Length="50" />        
        <Column Name="NavigationProperty_@Relationship" Label="NavigationRelationship" DataType="DT_WSTR" Length="500" />
        <Column Name="NavigationProperty_@ToRole" Label="NavigationToRole" DataType="DT_WSTR" Length="50" />
        <Column Name="NavigationProperty_@FromRole" Label="NavigationFromRole" DataType="DT_WSTR" Length="100" />
        <Column Name="NavigationProperty" Label="Navigation" DataType="DT_WSTR" Length="4000" />
        <Column Name="Key_PropertyRef" Label="KeyProperty" DataType="DT_WSTR" Length="1364" />

        <Column Name="p_edmx:Edmx_edmx:DataServices_@m:DataServiceVersion" Label="DataServiceVersion" DataType="DT_R8" />
        <Column Name="p_edmx:Edmx_edmx:DataServices_@m:MaxDataServiceVersion" Label="MaxDataServiceVersion" DataType="DT_R8" />
        <Column Name="p_edmx:Edmx_@Version" Label="Version" DataType="DT_R8" />

      </OutputColumns>
    </EndPoint>

    <EndPoint Name="get_metadata_columns"
          ResponseFormat="Xml"
          Label="List Columns"
	      Template="."
          Url="/$metadata"
          UseRawCache="True"
          Cached="True"
          
	      Filter="$.edmx:Edmx.edmx:DataServices.Schema[*].EntityType[?(@@Name=='[$TableName$]')].Property[*]"
          IncludeParentColumns="True"
          CachedTtl="1440"
			  >
      <Params>
          <Param Name="TableName" Value="*" OptionsEndPoint="get_metadata_tables" OptionsEndPointValueColumn="EntityName" />
      </Params>
	    <OutputColumns>
		    <Column Name="P_edmx:Edmx.edmx:DataServices.Schema_EntityType_@Name" Label="EntityName" DataType="DT_WSTR" Length="255" />
		    <Column Name="@Name" Label="Name" DataType="DT_WSTR" Length="500" />
		    <Column Name="@Type" Label="Type" DataType="DT_WSTR" Length="500" />
			<Column Name="@MaxLength" Label="MaxLength" DataType="DT_I4" />
			<Column Name="@FixedLength" Label="FixedLength" DataType="DT_WSTR" Length="50" />
			<Column Name="@Unicode" Label="Unicode" DataType="DT_WSTR" Length="50" />
			<Column Name="@Precision" Label="Precision" DataType="DT_I4" />
			<Column Name="@Scale" Label="Scale" DataType="DT_I4" />

			<Column Name="P_edmx:Edmx.edmx:DataServices.Schema_EntityType_Key_PropertyRef_@Name" Label="KeyName" DataType="DT_WSTR" Length="255" />
			<Column Name="@Nullable" Label="Nullable" DataType="DT_WSTR" Length="50" />
			<Column Name="@p6:StoreGeneratedPattern" Label="StoreGeneratedPattern" DataType="DT_WSTR" Length="100" />
			<Column Name="P_edmx:Edmx_@Version" Label="EdmxVersion" DataType="DT_R8" />
			<Column Name="P_edmx:Edmx.edmx:DataServices.Schema_@Namespace" Label="SchemaNamespace" DataType="DT_WSTR" Length="500" />
			<Column Name="P_edmx:Edmx.edmx:DataServices.Schema_@xmlns" Label="SchemaXmlns" DataType="DT_WSTR" Length="500" />
			<Column Name="P_edmx:Edmx.edmx:DataServices_@m:DataServiceVersion" Label="DataServiceVersion" DataType="DT_R8" />
			<Column Name="P_edmx:Edmx.edmx:DataServices_@m:MaxDataServiceVersion" Label="MaxDataServiceVersion" DataType="DT_R8" />

		</OutputColumns>
	</EndPoint>
    
  </EndPoints>
  
  <Tables>
    <Table Name="[$parent.name$]" Expand="True" DataEndPoint="list_tables_json"
      SelectEndPoint="get_[$parent.name$]">
    </Table>
  </Tables>
  <Examples>
    <Example Group="ODBC" Slug="read-records-from-json-odata-table" Label="Read all records from a JSON OData service table">
      <Desc><![CDATA[<p>Gets all rows from the <code>Customers</code> entity set when the service is configured for JSON. Use the table name that matches your OData metadata (entity set name).</p>]]></Desc>
      <Code><![CDATA[SELECT * FROM Customers]]></Code>
    </Example>
    <Example Group="ODBC" Slug="read-records-from-xml-odata-table" Label="Read all records from an XML OData service table">
      <Desc><![CDATA[<p>Gets all rows from a table when the service uses XML. Supply <code>TableName</code> in <code>WITH</code> to identify the entity set (e.g. <code>MyTable</code>).</p>]]></Desc>
      <Code><![CDATA[SELECT * FROM read_data_xml WITH(TableName='MyTable')]]></Code>
    </Example>
    <Example Group="ODBC" Slug="filter-records-server-side" Label="Filter records using server-side criteria">
      <Desc><![CDATA[<p>Gets only customers that match the given OData filter expression. The filter is applied on the server. Use the service's filter syntax (e.g. <code>Country -eq 'USA'</code>).</p>]]></Desc>
      <Code><![CDATA[SELECT * FROM Customers WITH(SearchCriteria='Country eq ''USA''')]]></Code>
    </Example>
    <Example Group="ODBC" Slug="filter-records-client-side" Label="Filter records using client-side criteria">
      <Desc><![CDATA[<p>Gets only customers where <code>Country</code> equals <code>USA</code>. Filtering is done after data is retrieved (client-side). Use for simple equality filters when server-side syntax is not required.</p>]]></Desc>
      <Code><![CDATA[SELECT * FROM Customers WHERE Country = 'USA']]></Code>
    </Example>
    <Example Group="ODBC" Slug="list-tables-json" Label="Read all tables (JSON format)">
      <Desc><![CDATA[<p>Gets the list of available entity sets (tables) when the service exposes metadata in JSON-based format. Use this to discover table names for your SELECT queries.</p>]]></Desc>
      <Code><![CDATA[SELECT * FROM list_tables_json]]></Code>
    </Example>
    <Example Group="ODBC" Slug="list-tables-xml" Label="Read all tables (XML format)">
      <Desc><![CDATA[<p>Gets the list of available entity sets (tables) when the service exposes metadata in XML-based format. Use this to discover table names for your SELECT queries.</p>]]></Desc>
      <Code><![CDATA[SELECT * FROM list_tables_xml]]></Code>
    </Example>
  </Examples>
</ApiConfig>