na2009 enus devii_09

Chapter 9: Interfaces

9-1

CHAPTER 9: INTERFACES Objectives

The objectives are:

• Use automation servers to perform tasks with other applications. • Install and use custom controls in C/AL. • Use file handling functions to import or export data. • Design and implement an e-mail capability. • Use the XMLport to generate exported data in XML format.

Introduction This chapter deals with some of the methods that are used to interface Microsoft Dynamics® NAV to external software or hardware. One method to extend Microsoft Dynamics NAV is to use Component Object Model (COM) and file handling. First the essentials of COM are discussed, both from the Automation Server and Custom Controls (OCX) perspectives. Then, automation is used to add e-mail confirmation functionality to the seminar solution. Finally, file handling is used to generate an XML participant list. These are examples of how Microsoft Dynamics NAV solutions can be extended to provide enhanced functionality.

Microsoft Official Training Materials for Microsoft Dynamics ® Your use of this content is subject to your current services agreement

C/SIDE Solution Development in Microsoft Dynamics® NAV 2009

9-2

Prerequisite Information In C/SIDE, developers use (COM) technologies in one of two ways: by using custom controls (OCXs) or by using automation (C/SIDE in the role of an automation controller or client) to perform tasks with other applications.

Using an Automation Server

To create the Seminar Management e-mail confirmations, use C/SIDE as an automation server. Using an automation server consists of five basic steps:

1. Declare the creatable (top-level) interface (class) of the automation server as the variable of type Automation.

2. Declare all the other interfaces (classes) as variables of type Automation.

3. Use the C/AL function CREATE on the variable declared in step 1. Do not use CREATE on any other variables.

4. Use the methods and properties of the automation server in C/AL code. The syntax and semantics for these methods and properties are documented for each automation server.

5. (optional) Destroy the top-level object with the CLEAR function. If you do not destroy this object, it is automatically destroyed when the variable goes out of scope.

It is recommended to create a separate codeunit for code that uses automation because of performance issues, and because an object using automation can only be compiled on a machine on which the automation server is installed.

By default, the automation server resides on the Microsoft Dynamics NAV Server tier, and not on the client computer. For Microsoft Dynamics NAV 2009, the CREATE function is now expanded with a third optional parameter. This parameter is used to specify whether you want to create the instance of the automation variable on the client tier or on the Microsoft Dynamics NAV Server tier. The automation server must be installed and/or registered on the tier where it runs.

The data being transferred must be in text format.

Using custom (or OCX) Controls

Microsoft Dynamics NAV supports custom controls (which are also known as OLE controls or ActiveX controls) with a few limitations:

• Only non-visual controls are supported. A control cannot be used to add graphical elements to a C/SIDE object (for example, you cannot add a third-party control to a form). The control can, however, display information and interact with the user in a window of its own.



9-3

• Exception handling is not supported. C/SIDE does not allow the retrieval of information about exceptions from a control or automated server through the Invoke method of the IDispatch interface and the EXCEPINFO structure.

A custom control must be physically installed on the target machine and registered with the operating system. For the RoleTailored client, the control must be registered on the Microsoft Dynamics NAV Server tier. OCX controls cannot live on the client tier; they must always live on the service tier.

To use a custom control, declare it as a global or local variable with a data type of OCX. Then select the desired custom control from a list by clicking the lookup button in the Subtype field. If the desired control is not in the list, the control can be installed and registered manually.

To install and register a custom control:

1. Copy the custom control from the distribution media to the hard disk. The C/FRONT folder contains a readme.txt file with more information.

2. Click Tools, and then Custom Controls. 3. Click the Control button, and select Browse to open a standard

Windows dialog to locate the OCX that is to be registered. 4. After locating and selecting the custom control, click Open. 5. The custom control is now registered with the system. A

confirmation message will be received once the registration is complete. Click OK to return to the Custom Controls window and then the custom control just added appears on the list.

To declare the control as a variable:

1. In Object Designer, create a new blank form that is not based on any table.

2. Click View, and the C/AL Globals to open the C/AL Globals window.

3. In the Name field enter cfront, and in the DataType field select OCX.

4. In the Subtype field, click the AssistButton to open the Custom Control List window.

5. Locate the control just installed, select and click OK. 6. Declare the additional variables.

Once the control is declared a variable, its methods and properties can be accessed. To view the methods and properties available, use the C/AL Symbol menu. Methods can be run just as any other function is run in C/AL, and properties can be read and set the same as any other object properties.



9-4

Installing Automation Objects

Code for automation objects runs on Microsoft Dynamics NAV Server. Ensure that files generated on the computer that are running Microsoft Dynamics NAV Server, and that code is running in the correct places for the automation to run successfully.

The following scenarios demonstrate how to change the automation objects created to support Microsoft Dynamics NAV Server.

NOTE: COM objects need to be installed only on the computer that is running Microsoft Dynamics NAV Server. COM does not need to be installed on every client.

Using a COM Component to Generate an Excel File for a User

Use the CREATE function with C/AL code running on Microsoft Dynamics NAV Server to create the automation object, and run its SAVE function to save it to that computer.

When the RoleTailored client needs access to the file, use the FILE.DOWNLOAD function to send it from the computer that is running Microsoft Dynamics NAV Server to the client. To ensure that this works correctly, the COM DLL must be stored and registered in the computer that is running Microsoft Dynamics NAV Server.

Using a COM Component to Carry out External Processing

With CAL code running on the Microsoft Dynamics NAV Server, use the CREATE function to create an automation object, and then call a method on the object. When the method is run, any return value is passed back to the code.

To ensure that this works correctly, the COM DLL must be stored and registered on the computer that is running Microsoft Dynamics NAV Server.

Using a COM Component to Read from an MSMQ Message

With C/AL code running on a computer that is running Microsoft Dynamics NAV Server, use the CREATE function to create an automation object and the READ function to read it from the message queue.

For the RoleTailored client, the Microsoft Dynamics NAV Server processes the result of the READ function.



9-5

NOTE: If the queue location is specified locally (such as ./myqueue), the code reads from a message queue called myqueue on the computer that is running Microsoft Dynamics NAV Server, and not from a message queue on the client.

File-Handling File-handling is useful for importing or exporting text-based data files that require parsing to interpret on input, or special formatting when output. For example, file-handling can be used to import data that is not record oriented or where the records exceed the size of text strings (250 characters) that can be handled in Microsoft Dynamics NAV text variables. Through File variables, import data from or export data to any file accessible through the operating system.

The File Data Type

To gain access to an external file from within C/SIDE, first declare a variable of type File. This is a complex data type, which has numerous functions used to open, read, write, and close external files.

Each File variable can be used to access one file at a time. This makes is necessary to declare one File variable for each file that must be accessed simultaneously.

This chapter discusses some of the frequently used file methods. Refer to the Developer and IT Pro Help for a comprehensive list of the File type variable.

Opening Files for Import or Export

Before a file can be opened for use, it must be set up properly. First determine whether it will be used for reading (import) or for writing (export). Although theoretically a file can be open for writing and then can be read, this is normally not done in Microsoft Dynamics NAV.

The following bulleted list contains the File functions used to prepare a file for opening and closing it. As with other functions, these are called through the File variable. For example, if the File variable is named ImportFile, then using the Open method looks like this:

ImportFile.OPEN(Name) ;

• WRITEMODE(NewWriteMode): Sets the read/write status of a File variable before opening the file. If NewWriteMode is TRUE, the file can be written. If NewWriteMode is FALSE, then the file can only be used for reading. Note that another way to use this method is: IsWriteMode := WRITEMODE;. With this function (used after the file is open) it can be determined whether a file is available for writing or not.



9-6

• TEXTMODE(NewTextMode): Sets the type of data to be read or written. If TRUE, the file is opened in Text mode, and if FALSE, it is opened in Binary mode. This method can only be used before opening the file. Note that another way to use this method is: IsTextMode := TEXTMODE;. With this function (used only after the file is open), it can be determined whether a file is being read or written in text mode or binary mode.

• QUERYREPLACE(NewQueryReplace): Use this function for opening a file using the CREATE method. If NewQueryReplace is TRUE and the file already exists, C/SIDE asks the user before a replace is allowed. If NewQueryReplace is FALSE, and the file already exists, C/SIDE erases the old file and replaces it with a new (empty) one, without asking the user. If the file does not already exist this function has no effect. This function is not supported in the RoleTailored client.

• OPEN(FileName): Use this function to open an already existing file. Be sure to set the WRITEMODE and the TEXTMODE before opening a file. FileName is the full path name of the file. When used as a statement (without using the return value) and the file indicated by FileName does not exist, OPEN causes a run-time error. If OPEN is used as an expression (using the return value) and the file indicated by FileName does not exist, OPEN returns FALSE, but if the file does exist, it is opened, and OPEN returns TRUE. If you are running the RoleTailored client and you call OPEN on a file variable that refers to an open file, the function will not automatically close the existing file and open the new file. You must explicitly call the CLOSE Function (FILE) to close the existing file. If you call OPEN on a file that is already open, a runtime error occurs.

• CREATE(FileName): Use this function to create and open a file. Be sure to set the WRITEMODE, the TEXTMODE, and QUERYREPLACE before creating a file. FileName is the full path name of the file. If CREATE is used as a statement (without using the return value) and the file indicated by FileName cannot be created (for example, the path does not exist), a run-time error occurs. If CREATE is used as an expression (using the return value) and the file indicated by FileName cannot be created, CREATE returns FALSE. But if the file is created, it is opened and CREATE returns TRUE. If the file already exists, it is cleared and opened. Whether the user is warned about this or not depends on the parameter to the QUERYREPLACE method called before calling CREATE. If you are running the RoleTailored client and you call CREATE on a file variable that refers to an open file, the function will not automatically close the existing file and create the new file. You must explicitly call the CLOSE Function (FILE) to close the existing file. Otherwise, a runtime error occurs. If you are running the Classic client and you call CREATE on a file variable that refers to an open file, the function will CLOSE the existing file and CREATE the new file. A runtime error does not occur.



9-7

• CLOSE: Use this function to close access to the file through this file variable. After CLOSE is called, the file variable cannot be used again to access a file unless it is reopened or recreated. If CLOSE is called and the file is not open, a run-time error occurs.

Methods of Reading Files

There are two methods for reading or writing data in external files. The method is set using the previously described TEXTMODE method. There are two possible settings:

• TEXT (TEXTMODE=TRUE): Each file access reads or writes a line of text. The variable used can be of any type and it is converted to (if writing) or from (if reading) text during the processing.

• BINARY (TEXTMODE=FALSE): Each file access reads or writes a single variable. The variable is read or written in its internal format. For example, text is written as a null terminated string whose length is the defined length of the Text variable. Since TEXTMODE is limited to one variable per line, note that the file cannot contain more than 250 characters per line. Binary mode does not have this limitation, since it does not have lines. However, the internal format can only be read if it is written in the same manner from Microsoft Dynamics NAV. The one variable type that is useful when using Binary mode is the Char type, which enables reading or writing one byte at a time.

Reading or Writing Data in External Files

The following methods are used to read or write data in external files (once the file variable is open):

• [Read :=] READ(variable): Read a variable from the file. The optional return value indicates the number of bytes read. In Text mode, a line of text is read and the text is evaluated into the variable passed in as a parameter. In Binary mode, the variable is read in its internal format, and thus the number of bytes read depends on the size of the variable.

• WRITE(variable): Write a variable to the file. In Text mode, the variable is formatted to text and written out as a line of text. In Binary mode, the variable is written using its internal format.

E-mail Confirmation E-mail confirmation provides the ability to send e-mail from Microsoft Dynamics NAV in an automated fashion. A solution for providing e-mail confirmation to seminar participants is designed and implemented for the Seminar Management system.



9-8

Solution Analysis

The client’s functional requirements in Chapter 1 describe e-mail confirmation as:

"The solution must allow e-mail notification to be sent to the Customer's participants in several situations, such as registration confirmation."

This feature enables seminar managers to send e-mail confirmations to all participants registered for a seminar, stating that that they are registered, and to remind them of the starting date.

Solution Design

Before attempting to implement a solution, it is vital to create a design, or plan. In this case, GUI changes are necessary to make the feature accessible to seminar managers, and functions are needed to execute the e-mail confirmation logic.

GUI Design

E-mail confirmation will be available from the Seminar Registration page. This requires the Seminar Registration page to be modified by adding a new Functions section menu to the Actions menu as shown in the following image.

FIGURE 9.1 THE SEMINAR REGISTRATION PAGE (123456710)



9-9

The e-mail confirmation functionality will also be available from the Seminar Registration List page. Therefore, a Functions section is added to the Actions menu of this list page as well. This can be seen in the following image.

FIGURE 9.2 THE SEMINAR REGISTRATION LIST PAGE (123456713)

Functional Design

To send e-mails, use an Automation variable with the subtype of an automation server class that can create and send e-mails. This automation server is the Navision Attain ApplicationHandler, and the class used is MAPIHandler. The implementation requires a new codeunit that can create and send the e-mails.



9-10

Lab 9.1 - Creating E-mail Confirmations There are many instances where it is good practice to have email communications with clients or other contacts. The extent to which this process can be automated reduces the effort involved in generating such communications.

Scenario

Before the scheduled date of a seminar, it is good practice to send out registration confirmation emails to all the registrants. There are multiple ways to accomplish sending out emails in Microsoft Dynamics NAV. This time it will be done using an Automation control, MAPIHandler.

Challenge Yourself!

Create a codeunit that uses MAPIHandler to send out emails to seminar registrants. Allow the user to specify the contents of the email and to whom it will be sent. Add the new email function to an action menu for easy access.

Step by Step

Begin by creating a codeunit to create the e-mail:

1. Create a codeunit called Seminar Mail (123456705). 2. Declare global record variables for the Seminar Registration Header,

Seminar Registration Line, Customer, and Contact tables. 3. Declare an Integer type variable called NumberOfErrors for storing

the number of errors. 4. Declare a Boolean type variable called MailSent for storing the result

of the MAPIHandler's Send command. 5. Declare a variable called MAPIHandler, of type Automation and of

subtype Navision Attain ApplicationHandler and of class MAPIHandler.

6. Define text constants for the different sections of the e-mail confirmation, including the subject line, the greeting, the confirmation sentence, and the signature.

7. Define a function called NewConfirmationMessage that has a parameter of a record variable for the Seminar Registration Line table, which is passed by reference.

8. Enter code in the function trigger so that the function performs the following tasks: o Creates an instance of the MAPIHandler (using the CREATE

function).



9-11

o Creates the e-mail message by assigning the appropriate elements of the message to the properties of the MAPIHandler variable. Assigns the ToName field using the Contact record, the CCName using the Customer record, and the Subject

o Uses the AddBodyText method of the MAPIHandler to create each line of the e-mail message.

NOTE: Rather than using Automation Controller and MAPIHandler, emails could be sent out using the SMTP Mail codeunit (Codeunit object 400). Compare the functions in the SMTP Codeunit to the properties and methods in the MAPIHandler Automation controller. To view all the properties and methods available in the MAPIHandler Automation controller, open the C/AL Symbol Menu by pressing F5 or clicking View, C/AL Symbol Menu, and locate the MAPIHandler variable in the left most column.

o Sends the message using the Send method of the MAPIHandler.

o Uses the ErrorStatus property of the MAPIHandler to check the number of errors. If there are none, set the Confirmation Date of the Seminar Registration Line to today’s date.

9. Define a function called SendAllConfirmations with a parameter of a record variable for the Seminar Registration Header.

10. Enter code in the function trigger so that the function runs the NewConfirmationMessage function for each Seminar Registration Line associated with the Seminar Registration Header that passed to it.

11. With the code in place, the remaining step is to make the functionality available to the user. Add a new menu selection to the Seminar Registration page (123456710) as follows:

Menu Button

Options Comments

Functions Send E-mail Confirmations

Runs code to Send E-mail Confirmations.

12. Enter code in the appropriate trigger so that when the user selects the

Send E-mail Confirmations menu item, the program runs the SendAllConfirmations function.

13. Add a new menu selection to the Actions menu on the Seminar Registration List page (123456713) as follows:

Menu Button

Options Comments

Functions Send E-mail Confirmations

Runs code to Send E-mail Confirmations.



9-12

14. Enter code in the appropriate trigger so that when the user selects the Send E-mail Confirmations menu item, the program runs the SendAllConfirmations function.

Using an XMLport XMLports are used to export and import data from and to Microsoft Dynamics NAV. XMLports can be coded to work either with structured XML document files or, in Microsoft Dynamics NAV 2009, to work with text files. The Text file formats are often some variation on CSV or "comma delimited" formats. The XML data structure is an industry standard, used to communicate between different applications, including those from different vendors. It provides a common format which is widely used in networked data exchanges.

Only a basic knowledge of XML is needed to design and work with XMLports. Design XMLports in the XMLport Designer, which is opened from the Object Designer.

XMLport Triggers

There are three event triggers that execute for an XMLport object:

• OnInitXMLport: This trigger executes when the XMLport is loaded and before any table views and filters are set.

• OnPreXMLport: This trigger executes after the table views and filters are set and before the XMLport is run.

• OnPostXMLport: This trigger executes after all the data items in an XMLpost are processed.

There are also event triggers for every field in an XMLport which are dependent on whether the XMLport is importing or exporting. For more information on those triggers, consult the Microsoft Dynamics NAV 2009 Developer and IT Pro Help.

Solution Analysis

The client's functional requirements for the Seminar Management system in Chapter 1 describe the need for a participant list in an XML format:

"...the participant list for a seminar must be exportable as an XML file."

Solution Design

Generating a Seminar Management participant list in XML can be accomplished using an XMLport.



9-13

GUI Design

The following menu item must be added to the Partner Menu MenuSuite (80):

Menu Type

Menu Name

Group Comments

Item Create XML List

Periodic Activities

Runs report 123456705 XML Sem. Reg.-Participant List.

Functional Design

To implement this solution, it is necessary to understand the basics of how XMLports work. XMLports have three basic sections:

• A title, in this case, "Seminar Registration - Participant List." • Heading information, in this case, from the Seminar Registration

Header including the No., Seminar Code, Seminar Name, Starting Date, Duration, Instructor Name, and Room Name fields.

• Line information, in this case one for each registered participant from the Seminar Registration Line, including Customer No., Contact No., and Name fields.

The following table shows the basic sections that are necessary for this solution:

Section Sample Section

Title <Seminar_Registration_-_Participant_List>

Heading for Heading information

<Seminar>

Heading information <No>REG0001</No>

<Seminar_Code>Sem0002</Seminar_Code>

<Seminar_Name>Solution Dev</Seminar_Name>

<Starting_Date>01.08.11</Starting_Date>

<Duration>10</Duration>

<Instructor_Name>A Hill</Instructor_Name>

<Room_Name>Room 1</Room Name>

Heading for Line information <Participant>

Line information <Customer_No>10000</Customer_No>

<Contract_No>CT100210</Contract_No>

<Name>Stephanie Bourne</Name>



9-14

Lab 9.2 - Creating the XML Sem. Reg. - Participant List XML formatted data has become a widely accepted standard for communicating data between systems.

Scenario

The Seminar Management system requires listings of registrations to be exported in an XML format to be input into another application. To accomplish this task, the XMLport tools will be used.

Challenge Yourself!

Create the necessary object(s) to export Seminar registrant data into an XML formatted file. Add the new XML export function to an action menu for easy access.

Step by Step

Begin by creating the XMLport:

1. Create a new XMLport called Sem. Reg.-XML Participant List (123456700).

2. Define the data items for the XMLport, using the previous Functional Design section as a reference for which tables to get information from. Add code to calculate the FlowFields so that the Instructor Name and Participant Name appear in the XML file.

Now implement a way that the user can run this XMLport. To enable the user to select filters, create a new report.

3. Create a new Processing Only report called Sem. Reg.-XML Participant List (123456705).

4. This report has one data item, the Seminar Registration Header table. Set the name of this datatype to SEMREGHEADER.

5. Create global variables for TestOutStream (datatype Outstream) and TestFile (datatype File).

6. In the OnPreReport trigger, insert this code, substituting the file path:

TestFile.CREATE('C:\XML_Part_List.XML') ;

TestFile.CREATEOUTSTREAM(TestOutStream) ;

XMLPORT.EXPORT(123456700,TestOutStream,SEMREGHEADER) ;

TestFile.CLOSE ;

MESSAGE('XML Completed') ;



9-15

7. All that remains is to add the menu item to the Seminar main menu. Add the new menu item to the Periodic Activities folder in the Partner MenuSuite.

Sample XML Participant List

The resulting XML participant list might look like this:

- <Seminar_Registration_-_Participant_List>

- <Seminar>

<No>REG00001</No>

<Seminar_Code>SEM0002</Seminar_Code>

<Seminar_Name>Solution Development</Seminar_Name>

<Starting_Date>01.08.01</Starting_Date>

<Duration>10</Duration>

<Instructor_Name>Annette Hill<Instructor_Name />

<Room_Name>Room 1</Room_Name>

- <Participant>

<Customer_No>10000</Customer_No>

<Contact_No>CT100140</Contact_No>

<Name>David Hodgson</Name>

</Participant>

- <Participant>



<Name>John Emory</Name>

</Participant>

- <Participant>



<Name>Mindy Martin</Name>



9-16

</Participant>

- <Participant>



<Name>Stephanie Bourne</Name>

</Participant>

</Seminar>

</Seminar_Registration_-_Participant_List>

Summary This chapter used COM automation to send e-mail messages to seminar participants and an XMLPort was used to create an XML file of participants in a seminar.

At this point in the course, the Seminar Management solution is complete. The next chapter addresses the deployment of custom solutions.



9-17

Test Your Knowledge

1. In what two ways can COM objects be used in C/SIDE?

2. When a variable is used for an automation server, what data type is assigned to the variable?

3. What C/AL function is used to create an instance of an automation server class?



9-18

4. In what situations are the file handling functions used?

5. Ideally, where is code placed that uses automation?

6. What event triggers exist for XMLports?



9-19

7. What is the purpose of using XML?



9-20

Quick Interaction: Lessons Learned Take a moment and write down three key points you have learned from this chapter

1.

2.

3.



9-21

Solutions Test Your Knowledge

1. In what two ways can COM objects be used in C/SIDE?

MODEL ANSWER:

COM objects can be used in C/SIDE by using custom, non-visual, OCX controls and by using automation server objects.

2. When a variable is used for an automation server, what data type is assigned to the variable?

MODEL ANSWER:

The data type for automation server variables is "Automation."

3. What C/AL function is used to create an instance of an automation server class?

MODEL ANSWER:

To instantiate an automation type variable, the C/AL keyword CREATE is used.

4. In what situations are the file handling functions used?

MODEL ANSWER:

When data needs to be imported and that data needs to be parsed, character by character when imported. When there is a need to build output textual data character by character, and when the data to be imported or exported has a record length too long for Microsoft Dynamics NAV to handle internally.

5. Ideally, where is code placed that uses automation?

MODEL ANSWER:

Code that uses automation is placed in separate codeunits. That way, other objects that call functionality using unregistered automation objects will compile.



9-22

6. What event triggers exist for XMLports?

MODEL ANSWER:

OnInitXMLport OnPreXMLport OnPostXMLport

7. What is the purpose of using XML?

MODEL ANSWER:

To communicate with another system in a standard structured data format.


na2009 enus devii_09

Technology

runtime error

seminar registration

seminar registration

clients functional

al symbol

side solution

microsoft

mail confirmations