Define custom model endpoints

In addition to the existing standard WorkZone OData endpoints, custom endpoints on the WorkZone OData provider can also be defined. This enables you to define a specific subset of the full model is more aligned with the requirements of the endpoint instead of accessing all resources of the model.

Custom endpoints can co-exist with the full model endpoint and do not interfere with standard WorkZone endpoints.

A maximum of 10 custom endpoints can be defined and freely named.

Components of a custom endpoint

A custom endpoint consist of two files placed in the OData service root folder on the web server, a *.svc file and a *.svc.config file.

The svc file

The .svc file connects the endpoint up with the WorkZone OData provider by specifying one of the 10 available custom slot to use.

The svg.config file

The .svc.config file contains the configuration of the model to be exposed.

Example

If you want to define an endpoint for tailored for integrations that can create basic Files, Records and Documents and nothing else, you can define an endpoint called BasicFRD.svc.

Since users of the endpoint only need to access Files, Records and Documents, the rest of the model can be hidden to increase productivity and performance.

The two files can then be named BasicFRD.svc and BasicFRD.svc.config

BasicFRD.svc

<%@ ServiceHost
Language="C#"
Factory="System.Data.Services.DataServiceHostFactory, Microsoft.Data.Services, Version=5.6.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
Service="Scanjour.Services.OData.Web.ODataCustom3"
%>
				

The BasicFRD.svc resembles the standard OData.svc file, but uses a different service name.

The slots available to custom endpoints are named “Scanjour.Services.OData.Web.ODataCustom1” to “Scanjour.Services.OData.Web.ODataCustom10” and the example above uses slot 3 as seen in the Service="Scanjour.Services.OData.Web.ODataCustom3" line.

BasicFRC.svc.config

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <appSettings>
    <add key="customModelExclude" value="*" />
    <add key="customModelInclude" value="Files,Records,Documents" />
  </appSettings>
</configuration>
				

The customModelExclude is first defined with a value of * to exclude all feeds from the full model.

The customModelInclude then is defined with a value of Files,Records,Documents to defines the feeds to re-include in this endpoint. Notice that it is the feed names (the sets) that are used here and not the type names.

Testing the custom endpoint

You can test your new endpoint by navigating to http://[HOST]/[DSN]/webservices/Scanjour.Services.OData.Web/BasicFRD.svc from your browser.

The endpoint will respond with a list of available feeds:

<?xml version="1.0" encoding="utf-8"?>
<service xml:base="http://[HOST]/[DSN]/Scanjour.Services.OData.Web/Partner.svc/" xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom">
  <workspace>
    <atom:title>Default</atom:title>
    <collection href="Documents">
      <atom:title>Documents</atom:title>
    </collection>
    <collection href="Files">
      <atom:title>Files</atom:title>
    </collection>
    <collection href="Records">
      <atom:title>Records</atom:title>
    </collection>
  </workspace>
</service>
				

If any errors are encountered, error messages will be logged in the Windows Eventlog on the webserver.

Limit the custom endpoint properties

You can reshape the entity types exposed by your custom endpoint to only include the properties you are interested in and thereby tailor endpoints for specific needs such as Excel PowerPivot BI reports These endpoint provide a more clear focus on the data types of interest by filtering out data types that are not relevant to the task the endpoint is a component of.

For example, the BasicFRD endpoint in the recurring example now exposes three feeds/resource sets, but the File, Record and Document entities are still the full entities with all properties included, except for navigation properties to entities and feeds that are not present in the BasicFRD endpoint. If you are only interested in Title, Officer_Value, FileClass_Value and ResponsibleOu_Value, you can edit the BasicFRD.svc.config file in the following manner:

BasicFRD.svc

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <appSettings>
    <add key="customModelExclude" value="*" />
    <add key="customModelInclude" value="Files,Records,Documents" />
    <add key="File" value="Title,Officer_Value,FileClass_Value,ResponsibleOu_Value" />
  </appSettings>
</configuration>
				

Querying for Files using the BasicFRD endpoint will return the following:

<?xml version="1.0" encoding="utf-8"?>
<feed xml:base="http://[HOST]/[DSN]/webservices/Scanjour.Services.OData.Web/WorkZone/Partner.svc/" xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
  <id>http://[HOST]/[DSN]/webservices/Scanjour.Services.OData.Web/WorkZone/Partner.svc/Files</id>
  <title type="text">Files</title>
  <updated>2013-11-11T12:23:43Z</updated>
  <link rel="self" title="Files" href="Files" />
  <entry>
    <id>http://[HOST]/[DSN]/webservices/Scanjour.Services.OData.Web/WorkZone/Partner.svc/Files('2')</id>
    <category term="Som.File" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="File" href="Files('2')" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/RecordsByFileKey" type="application/atom+xml;type=feed" title="RecordsByFileKey" href="Files('2')/RecordsByFileKey" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/FileRecords" type="application/atom+xml;type=feed" title="FileRecords" href="Files('2')/FileRecords" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/RecordsByFile" type="application/atom+xml;type=feed" title="RecordsByFile" href="Files('2')/RecordsByFile" />
    <title />
    <updated>2013-11-11T12:23:43Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:ID>2</d:ID>
        <d:FileClass_Value>08</d:FileClass_Value>
        <d:Officer_Value>AA</d:Officer_Value>
        <d:ResponsibleOu_Value>1KT</d:ResponsibleOu_Value>
        <d:Title>Spm. S385 Om cykelstien frederiksberg allé</d:Title>
      </m:properties>
    </content>
  </entry>
				

Only the simple properties specified above are now included in the BasicFRD endpoint.