Use a Custom Connector

This blog explains the concept behind custom connectors and describes how to add custom functionality to an internal document. As a case, we will use a simple import scenario in Connectivity Studio. The connection will read an XML file containing item data. But before the record is processed we would like to automatically setup a new Item Journal line.

What is a Custom Connector?

A custom connector is a plugin (codeunit) that allows you to add custom functionality to an internal document.  In the Business Integration Solution, the custom connectors are provided with standard programming model which makes it much easier for a developer to recognize the triggers, both from syntactic and semantic viewpoint.

A custom connector contains very specific signature. If the codeunit does not pass the necessary requirements, you will get an error while attaching it  in the internal document.

A custom connector contains five specific triggers (or functions) with very specific identification property namely:

1. OnBeforeProcessRecord: The code written under this trigger is fired before processing the record. The identification property of this function is set to 1.
2. OnInsertRecord: The code written under this trigger is fired when a record is inserted. The identification property of this function is set to 2.
3. OnModifyRecord: The code written under this trigger is fired when a record is modified. The identification property of this function is set to 3.
4. OnDeleteRecord: The code written under this trigger is fired when a record is deleted. The identification property of this function is set to 4.
5. OnAfterProcessRecord: The code written under this trigger is fired after processing
   the record. The identification property of this function is set to 5.

You can write your custom code under the triggers as required. Make sure a local variable Rec (passed by value) is used with data source pointing to the record table. Also, the Return Type is set to Boolean. Once the codeunit is created, you attach it to your internal document.

It is important to note that when you implement the triggers in a custom connector, the standard Microsoft Dynamics NAV triggers are overruled. For instance, if you implement the OnInsertRecord trigger in the custom connector, the standard OnInsert trigger will be overruled. Records will not be inserted unless you insert it in the OnInsertRecord trigger of the custom connector.

Create Custom Connector Codeunit

Open Microsoft Dynamics NAV Development Environment and open the Object Designer (Shift+F12). Perform the following tasks:

• Create a new codeunit.
• In the C/AL Editor, click View/C/AL Globals.
• Since we want to run our custom code before processing of the record, create a OnBeforeProcessRecord function and set the ID property to 1.
• For the function, open C/AL Locals and add a passed by value variable Rec pointing to the Item Journal Line record. Set the Return Type to Boolean and create a variable LastItemJnlLine pointing to the Item Journal Line record.
• Add the following code under the OnBeforeProcessRecord function:

//Demo Purpose Only. //This COMMIT should not be used in a real life scenario. COMMIT; LastItemJnlLine.SETRANGE(“Journal Template Name”, Rec.”Journal Template Name”); LastItemJnlLine.SETRANGE(“Journal Batch Name”, Rec.”Journal Batch Name”); IF LastItemJnlLine.FINDFIRST THEN; Rec.SetUpNewLine(LastItemJnlLine); EXIT(TRUE);

• Compile and save the codeunit with ID as 50000 and Name as NXXX Item Journal Connector.

XML File

Create a simple XML structure as shown below and save it in a location as  itemjournallines.xml:

Connectivity Studio

Download the configuration package for Connectivity Studio. Import the connection into Microsoft Dynamics NAV using the Import Connection task in the Connectivity Studio (Departments/Business Integration Solutions/Connectivity Studio/Tasks). If the import is successful, you can locate ITEMJOURNAL connection in the Connections list.

This connection contains:

• A pipeline with a File Reader event, a Mapper activity and a Record Generator end point.
• An internal ITEMJNLLINE document and an external ITEMJNLLINE document.

Document

Edit the ITEMJNLLINE internal document and for the Item Journal Line data source, place a check to use a custom connector and specify the Connector Name as  NXXX Item Journal Connector.

Connection

For the ITEMJOURNAL connection open the setup page for the File Reader event and specify the Folder Name where the XML file is located.

Open the Mapping between the internal and external document and specify the following constant values: JournalTemplateName as “ITEM” and JournalBatchName as “DEFAULT”.

Process

Click Check Configuration to see if the connection is set up properly. If everything is set up well, the connection is ready to be processed. Click Process in the ribbon to process the connection.

After successful processing check the message. An item journal line with the following details is inserted as expected by our custom connector.