Endpoint Management

The Endpoint Management tool introduced in Dynamicweb 9.8 allows you to define & test various endpoints – but why do you need endpoint management?

Well, integration between multiple systems almost always requires communication between multiple endpoints. Not only do these endpoints differ in the data they expose (e.g. contact, orders, products), they also differ in their origin (development, staging, production servers).

Over the course of a development project there is a need to manage these endpoints:

  • Developers might need to add new endpoints as changes to the business requirements necessitates new data sources
  • User credentials might need to be updated as passwords and permissions are changed for an endpoint
  • Eventually it is necessary to change servers when the project progresses from development to staging and finally production

All of these management tasks are made much easier by using the Endpoint Management tool.

To use the Endpoint Management tool, go to Settings > Integration > Endpoint Management (Figure 1.1).

Figure 1.1 The Endpoint Management tool

You can now do four things:

  • Add an endpoint
  • Add an authentication
  • Test an existing endpoint
  • Edit one or more existing endpoints

Endpoints can be used with the following placed:

  • In the Import data with custom request add-in
  • In the Live Integration

The Endpoint Management tool is built with two specific types of endpoints in mind:

  • OData RESTful endpoints exposed by NAV/D365 Business Central
  • SOAP endpoints exposed by a Dynamicweb plug-in installed on a Microsoft Dynamics ERP system

This is not to say that the tool cannot be useful with other RESTful or SOAP-based endpoints, e.g. an Azure Table or a proprietary SOAP web service – but you should regard this as a bonus and not the purpose for which the tool is built, or something which will necessarily be prioritized in the future.

To add an OData RESTful endpoint:

  1. Click Add Endpoint
  2. Add a Name and a Description
  3. Add the URL of the OData endpoint you want to connect to
  4. Select type GET
  5. Select an Authentication from the list of authentications (see next section)
  6. Save

A configured OData RESTful endpoint could look like Figure 2.1)

To add a SOAP endpoint connected to a Dynamicweb ERP plugin:

  1. Click Add Endpoint
  2. Add a Name and a Description
  3. Add the URL of the SOAP web service exposed by the Dynamicweb ERP plugin
  4. Check the Connects to a standard Dynamicweb codeunit service checkbox
  5. Add a GetEcomData request – see more here
  6. Select an Authentication from the list of authentications (see next section)
  7. Save

A configured SOAP endpoint could look like Figure 2.2.

Connects to a standard Dynamicweb codeunit service

The Connects to a standard Dynamicweb codeunit service checkbox does three things:

  • Forces the type to POST
  • Adds two headers – Content-Type and SoapAction – with appropriate values
  • Adds a request body

This is because SOAP, while using HTTP, envelopes each message with headers and a body. Endpoint Management does all of this for you when you connect to a standard Dynamicweb Service. It then adds your GetEcomData request to the body of each message.

Of course, you can also configure an endpoint like this manually. 

To add an authentication:

  1. Click Add authentication
  2. Add a Name
  3. Select a Type:
    1. Basic: Authentication with a username and a password
    2. WebServiceAccessKey: Business Central can assign web access keys to users. These keys can be valid from one date and be invalid after a certain date. These keys are auto-generated and is used instead of a password. WebServiceAccessKeys can be used for on premise solutions as well as cloud-hosted test enviroments. 
    3. Ntlm: NTLM is an authentication protocol used in windows networks. It allows you to provide a domain and windows user to access endpoints within the same network as the Dynamics ERP system. This is useful in development and on premise scenarios.
    4. OAuth2: A method of authentication managed in Microsoft Azure Active Directory. As of April 2021 the use of OAuth is mandatory when interacting with APIs of cloud hosted Business Central enviroments. Check out the how to guides for Business Central, Dynamics CRM and 365 F&O here.
  4. Add username, password, webservice access key, and/or domain according to the selected authentication type
  5. Save

Please note that a single authentication can be used across multiple endpoints – for example; an authentication using the NTLM protocol to access endpoint with a network domain and windows user. This user is subsequently added as a Business Central user with access rights to the endpoint.

To filter the records exposed by the endpoint a query parameter can be added in Endpoint Management.

A query parameter consists of a key value pair and could look like the following example (filtering 365BC sales orders):




Sell_to_Country_Region_Code eq ‘GB’




The first example filters the OData so that it only includes records where the value of the sell_to_Country_Region_Code is equal to the string ‘GB’. Resulting in the endpoint only exposing orders made to customers in Great Britain.

The second example restricts the endpoint to only importing the first 20 records of the entity.

Once a query parameter has been added to the endpoint and the endpoint itself has been saved, the full URL (including the added query parameter) will be visible in the endpoint editor.

For a full documentation on Business Central API filters click here.

The endpoints configured in Endpoint Management can be tested for development and debugging purposes with the internal Test Tool of Dynamicweb.

Clicking Test in the Endpoint Management action bar takes you to the Test Tool where you can send requests to either a preconfigured endpoint or a new URL, select your desired authentication and adjust request headers, body or query parameters, and view the response instantaneously. The Test Tool also let's you save local files with the reponse from an endpoint, which can be useful for populating the database of a new solution.


Figure 5.1 Testing an OData endpoint

At some point, for instance when you move from development to staging and from staging to production, you want to edit existing endpoints. This can be done in two ways:

  • Clicking a single endpoint in the endpoint list, changing something, and saving it
  • Clicking Edit endpoints in the toolbar and edit multiple endpoints at once (Figure 6.1)
Figure 6.1 Bulk-editing endpoints

Note how you can also add new endpoints from the bulk edit page.

Addresses are stored in the AccessUserAddress-table - this does not contain the address stored in the user standard fields.


For endpoint configurations

Field name Data type Length
EndpointId int 4
EndpointName nvarchar 255
EndpointDescription nvarchar Max
EndpointUrl nvarchar Max
EndpointAuthenticationId int 4
EndpointRequestType nvarchar 10
EndpointHeaders nvarchar Max
EndpointBody nvarchar Max
EndpointUseInLiveIntegration bit 1
EndpointParameters nvarchar Max

Endpoint authentication

For authentication information for endpoints

Field name Data type Length
EndpointAuthenticationId int 4
EndpointAuthenticationName nvarchar 255
EndpointAuthenticationType nvarchar 255
EndpointAuthenticationParameters nvarchar Max
EndpointAuthenticationEncrypted bit 1