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.
| Header | Value | Description |
|---|---|---|
| x-vainu-limit | 1-50 | Manual maximum limit for returned results per page. |
| x-vainu-usetop | true | Gives control of maximum limits for Dynamics. This will bring as many results as Dynamics will request based on user settings. |
| x-vainu-usecount | true | Returns 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 name | Type | Description |
|---|---|---|
| _id | Guid | Global unique id |
| company_name | String | Company name |
| turn_over_local | Double | Turn over in local currency |
| staff_number | Int32 | Employee count |
| domain | String | Website |
| address | String | Postal address |
| postal | String | Postal code for postal address |
| city | String | City for postal address |
| visiting_address | String | Visiting address |
| visiting_postal | String | Postal code for visiting address |
| visiting_city | String | City for visiting address |
| country | String | Country code |
| facebook_link | String | Facebook link |
| twitter_link | String | Twitter link |
| linkedin_link | String | LinkedIn link |
| status | String | Status of the company (active/inactive) |
| form_of_company | String | Form of company |
| development_of_turnover | Double | Change of turnover in percentage |
| profit | Double | Profit in percentage |
| phone | String | Phone number |
| registration_date | String | Registration date |
| currency_code | String | Currency code |
| industry_code | String | Local industry code |
| industry_text | String | Industry text in English |
| industry_text_local | String | Industry text in local language |
| vainu_link | String | Link to Vainu company card |
| business_id | String | Business id |
| group_parent_company_name | String | Company name of the parent organisation |
| group_parent_business_id | String | Business id of the parent organisation |
Locations
The following data fields are available for the locations collection.
| Field name | Type | Description |
|---|---|---|
| _id | Guid | Global unique id |
| company_name | String | Company name of the company location belongs to |
| business_id | String | Business id of the company location belongs to |
| office_name | String | Location name |
| office_type | String | Location type |
| visiting_address | String | Visiting address for the location |
| visiting_city | String | City of the location |
| visiting_postal | String | Postal code of the location |
| country | String | Country of the location |
| office_number | String | Official office number / id of the location |
| phone | String | Phone number for the location |
| String | Email address for the location | |
| industry_code | String | Industry 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.
- Create a new Virtual entity data source with oData v4 option.
- Insert Vainu One-to-one URL with api-key and other preferred headers.
- Create a new entity and set it to use the same Virtual entity data source you created.
- Make sure the external collection is the one you prefer to use.
- Edit the id field and make sure the external field name is _id.
- Add other fields you need and make sure external field names match the ones in the schema.
- 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.
Updated about 1 year ago