Custom Connectors

A Connector is an add-in used by the Connector Service and Connector TestTool to connect to and communicate with a particular remote system in a manner which it understands. The Connector for Dynamics AX, for instance, connects to a plugin installed in AX, which then extracts data, wraps it in XML, and returns it to the Connector Service again. Other Connectors simply query a web API and return the responses to Dynamicweb as is, where they are then processed by an XSLT file on the import job.

Basically, a Connector:

  • Receives requests from Dynamicweb
  • Relays them to a remote system
  • Receives responses from the remote system
  • Relays the responses to Dynamicweb

Since Connectors are system-specific, a custom connector is typically only used when you want to create an integration to a system which is not supported by Dynamicweb by default. They can be as complicated or simple as you want them to be – maybe you want to transform your response data in the Connector instead of on either side of the integration. That’s totally up to you.

To create a custom Connector:

  • Download and install the Visual Studio templates for Dynamicweb 9 from the Downloads section
  • Create a new project in VS and select Class Library as the project template
  • Select the Dynamicweb 9 > Data Integration > DynamicwebConnectorAddin template (Figure 1.1)
  • Add references to System.Configuration and Dynamicweb.Ecommerce.Integration.Connectors.dll (which is found in the DynamicwebConnectorService folder)

In the ProcessRequest method, you can write your code for handling the XML requests from Dynamicweb to the remote system. See more below.

When the Connector Service receives a request, it is handled in the ProcessRequest method, relayed to the remote system, and the response is returned to Dynamicweb.

If you use one of the built-in batch integration task add-ins to request data, the standard requests & responses can be browsed here.

You can also use the import data with paging add-in to submit custom requests to the Connector Service, or even create a custom batch integration task add-in.

In the example add-in, the ProcessRequest method breaks down the request XML:

<GetEcomData> <tables> <Users type="all"/> </tables> </GetEcomData>

…and translates it into an SQL statement, which is then used to query an SQL database specified in a connectionString parameter from the settings in the DynamicwebConnectorService config file:

public override string ProcessRequest(string request) { string result = ""; NameValueCollection connectorSettings = (NameValueCollection)ConfigurationManager.GetSection("DynamicwebConnectorAddin"); string connectionString = connectorSettings["ConnectionString"]; using (SqlConnection connection = new SqlConnection(connectionString)) { connection.Open(); XmlDocument doc = new XmlDocument(); doc.LoadXml(request); if (doc.DocumentElement.Name == "GetEcomData") { result = "<tables>"; foreach (XmlNode node in doc.SelectNodes("//tables/*")) { switch (node.Name) { case "Users": string sqlCommand = "select * from Users"; SqlCommand command = new SqlCommand(sqlCommand, connection); var reader = command.ExecuteReader(); result = result + WrapInXml("AccessUser", reader); break; default: throw new Exception("request for table '" + node.Name + "' was not recognized by the Connector"); } } result = result + "</tables>"; } else { throw new Exception("request of type '" + doc.DocumentElement.Name + "' was not recognized by the Connector"); } } return result; }

As you can see, this Connector retrieves all users from the [Users] table of an SQL server database, then runs the response through a the WrapInXml method to wrap the data in the format understood by Dynamicweb: 

public static string WrapInXml(string tableName, SqlDataReader reader) { StringWriter sw = new StringWriter(); XmlWriter xml = new XmlTextWriter(sw); xml.WriteStartElement("table"); xml.WriteAttributeString("tableName", tableName); while (reader.Read()) { xml.WriteStartElement("item"); xml.WriteAttributeString("table", tableName); for (int i = 0; i < reader.FieldCount; i++) { if (reader[i] != DBNull.Value) { xml.WriteStartElement("column"); xml.WriteAttributeString("columnName", reader.GetName(i)); xml.WriteValue(reader[i]); xml.WriteEndElement(); } else { xml.WriteStartElement("column"); xml.WriteAttributeString("columnName", reader.GetName(i)); xml.WriteAttributeString("isNull", "true"); xml.WriteEndElement(); } } xml.WriteEndElement(); } xml.WriteEndElement(); return sw.ToString(); }

To use the custom DynamicwebConnectorService add-in, save and build your project – then copy the .dll to the DynamicwebConnectorService folder.

Open the DynamicwebConnectorService config file and create the relevant Connector changes:

<?xml version="1.0" encoding="utf-8" ?> <configuration> <configSections> <section name="DynamicwebConnectorAddin" type="System.Configuration.NameValueSectionHandler"/> </configSections> <DynamicwebConnectorAddin> <add key="ConnectionString" value="YOUR CONNECTION STRING" /> </DynamicwebConnectorAddin> <appSettings> <add key="ServiceName" value="DynamicwebService" /> <add key="testMode" value="False" /> <add key="TestOutputFile" value="c:\exportContent.xml" /> <add key="Secret" value="test" /> <add key="WebserviceURI" value="http://localhost:8090/DynamicwebService"/> <add key="ErpConnectorType" value="DataIntegration.Examples.DynamicwebConnectorAddin"/> </appSettings> </configuration>

You must:

  • In the <configSections> node specify the name of your Connector
  • Create a section for settings – here the <DynamicwebConnectorAddin> section – with the appropriate nodes, in this case the ConnectionString parameter used to connect to an SQL database
  • In the <appSettings> section, point the ErpConnectorType node to your custom Connector

Next you should start the Dynamicweb service and check your connector is working using the TestTool.