One-to-one Dynamics

One-to-one

One-to-one for Dynamics is an OData v4 API that Dynamics supports natively. OData API can be added as a Virtual entity data source at the Dynamics. This allows virtual entities or virtual tables to be created based on the data source.

Virtual entities behave like native entities with the difference that the data isn't saved, only displayed in the system. Further functionalities can be built on top of virtual entities that allow converting them to native entities like accounts or leads.

Odata API

Dynamics can read and query the OData v4 API without scripts or development. The following specification helps understand the API and creation of virtual entities that need to match external data fields of the API

OData v4 API URL:

https://one-to-one.vainu.com/odata/<iso-2_country_code>/

OData API supports custom headers that can be utilised to alter the behaviour of the API. Headers allow changing limits for returned objects and enabling counts of all matched objects. The functionality of counts and limits is limited when using the locations collection.

HeaderValueDescription
x-vainu-limit1-50Manual maximum limit for returned results per page.
x-vainu-usetoptrueGives control of maximum limits for Dynamics. This will bring as many results as Dynamics will request based on user settings.
x-vainu-usecounttrueReturns count of all available documents. (Note that this will affect performance)

Authentication

Authentication works with "api-key" header. This header can be set at the Virtual entity data source settings. You can request access from your Vainu contact person.

🚧

API-Key

OData API uses different permission system from Vainu's REST API and your REST API credentials or API-Key will not work.

Collections

One-to-one includes two different collections: companies and locations. Companies collection consists of company-level data and locations collection of location-level data.

A single Virtual entity data source can serve both types of collections. The preferred collection is selected on the Entity level.

Each country needs to have a separate data source The preferred country is set as an URL parameter using ISO-2 country code (FI, SE, NO, DK).

🚧

Availability

Companies collection is available for all Nordic databases.

Locations collection is only available in Sweden (SE).

Schemas

Both collections have their separate schemas. Dynamics will process these schemas automatically, but fields for Virtual entities need to be created manually. API serves data in JSON format.

Schemas can be queried from the OData API with the following queries:

Collections

https://one-to-one.vainu.com/odata/<country_code>/#metadata

Companies

https://one-to-one.vainu.com/odata/<country_code>/companies#metadata

Locations

https://one-to-one.vainu.com/odata/<country_code>/locations#metadata

Companies

The following data fields are available for the companies collection.

Field nameTypeDescription
_idGuidGlobal unique id
company_nameStringCompany name
turn_over_localDoubleTurn over in local currency
staff_numberInt32Employee count
domainStringWebsite
addressStringPostal address
postalStringPostal code for postal address
cityStringCity for postal address
visiting_addressStringVisiting address
visiting_postalStringPostal code for visiting address
visiting_cityStringCity for visiting address
countryStringCountry code
facebook_linkStringFacebook link
twitter_linkStringTwitter link
linkedin_linkStringLinkedIn link
statusStringStatus of the company (active/inactive)
form_of_companyStringForm of company
development_of_turnoverDoubleChange of turnover in percentage
profitDoubleProfit in percentage
phoneStringPhone number
registration_dateStringRegistration date
currency_codeStringCurrency code
industry_codeStringLocal industry code
industry_textStringIndustry text in English
industry_text_localStringIndustry text in local language
vainu_linkStringLink to Vainu company card
business_idStringBusiness id
group_parent_company_nameStringCompany name of the parent organisation
group_parent_business_idStringBusiness id of the parent organisation

Locations

The following data fields are available for the locations collection.

Field nameTypeDescription
_idGuidGlobal unique id
company_nameStringCompany name of the company location belongs to
business_idStringBusiness id of the company location belongs to
office_nameStringLocation name
office_typeStringLocation type
visiting_addressStringVisiting address for the location
visiting_cityStringCity of the location
visiting_postalStringPostal code of the location
countryStringCountry of the location
office_numberStringOfficial office number / id of the location
phoneStringPhone number for the location
emailStringEmail address for the location
industry_codeStringIndustry code of the location

Implementation

Implementation for the One-to-one consist of two major parts: Setting up the Virtual entity data source and setting up the virtual entity. The following steps are needed for the configuration.

  1. Create a new Virtual entity data source with oData v4 option.
  2. Insert Vainu One-to-one URL with api-key and other preferred headers.
  3. Create a new entity and set it to use the same Virtual entity data source you created.
  4. Make sure the external collection is the one you prefer to use.
  5. Edit the id field and make sure the external field name is _id.
  6. Add other fields you need and make sure external field names match the ones in the schema.
  7. Create views and other elements to make the entity and its fields visible.

Setting up the Virtual entity data source

Begin by navigating to the Advanced settings. Select Administration and then Virtual entity data sources. Create a new data source and select the OData v4 data source from the list.

Insert the API URL into the General section with the name you prefer. Leave pagination to Pagination mode to client-side paging and timeout to the default value. See section OData API for details about the URL and countries.

Insert request parameters and make sure they are set as headers. Minimum functionality can be achieved by inserting the api-key header. See OData API section for other headers and their purposes.

Setting up the Virtual Entity

Begin by navigating to the Advanced settings. Select Customizations and then Customize the system. Navigate then to the entities and create a new entity.

You can insert names and other features as other entities, but make sure to set it as a Virtual entity. After this, you can select the Virtual entity data source from the list of data sources. The external collection needs to be either companies or locations, which defines which dataset the entity will use.

Dynamics will automatically assign an id field for the entity. This field needs to be linked to the _id field in the schemas. Edit this field and assign a correct external name for the field.

After this, you can continue and add the rest of the fields for the entity. Each external name has to match the field name in the schema, and the field's data type must support the data type in the schema. Most strings will be short enough to fit the standard 100 characters.

You don't need to add all data fields in the schema, but select the ones you plan to use. After this, the views, forms and other functionalities can be created like for the native entities.

Limitations

Microsoft Dataverse search fails to index virtual tables. Virtual tables might not be available on the Dataverse search.

Counts and limits for location collection might return fewer results than specified in the headers.

Vainu One-to-One can't process OR queries. Note this when implementing quick search with multiple fields.