Microsoft Dynamics NAV includes a sample document handler, codeunit 8703 Mobile Document Handler, which processes requests to create new customers. This sample document handler receives request documents from mobile devices that run the sample application from Microsoft Dynamics® Mobile. In Microsoft Dynamics Mobile, document handlers process incoming request documents that are defined by document types. Microsoft Dynamics NAV includes five sample document types. For more information, see How to: Set Up Mobile Document Types in Microsoft Dynamics NAV Classic.

This codeunit illustrates a simple document handler that processes a single request document, but Microsoft Dynamics NAV also includes a more complicated document handler, codeunit 8725 Mobile Sales Document Handler, that you can explore in Object Designer. For more information, see Document Handling for Mobile Sales.

This topic provides examples of how you can define a document handler in Microsoft Dynamics NAV. For more information, see Defining Document Handlers in Microsoft Dynamics NAV.

Document Handling in Codeunit 8703 Mobile Document Handler

A document handler contains code that handles one or more types of incoming documents. In the default implementation, codeunit 8703 Mobile Document Handler, contains a single document handling function, CreateCustomerHandle, and can handle one type of request document that is sent from a mobile device. This section describes how the codeunit meets the requirements for document handlers that are described in Defining Document Handlers in Microsoft Dynamics NAV.

The following table describes the global functions in the codeunit.

Name Description

CreateCustomerHandle

Processes the request document by checking permissions, reading the XML, and passing each tasklet section to a separate function.

CustomerNodeHandle

Processes the part of the request document that describes the customer name, e-mail, and customer discount group.

CreditLimitNodeHandle

Processes the part of the request document that describes the customer credit limit information.

ContactNodeHandle

Processes the part of the request document that describes the customer contact person.

SaveResult

Updates the mobile document queue and sends a response document to the mobile device.

To illustrate the way that this codeunit handles an incoming document, this topic describes the OnRun section and the following functions:

  • CreateCustomerHandle

  • CustomerNodeHandle

  • SaveResult

The CreditLimitNodeHandle and ContactNodeHandle functions are similar to the CustomerNodeHandle function.

OnRun Section

The following code example illustrates the OnRun section in Mobile Document Handler.

CopyCode imageCopy Code 
OnRun(VAR Rec : Record "Mobile Document Queue")
CONSISTENT(FALSE);

CASE "Document Type" OF
  ’CreateCustomer’:
	CreateCustomerHandle(Rec);
  ELSE
	ERROR(Text000,"Document Type");
END;

CONSISTENT(TRUE);

In the OnRun section, the code executes on a record in the Mobile Document Queue Table table. The code uses the CONSISTENT function in C/SIDE to make sure that the codeunit executes as a single transaction. For more information, see CONSISTENT in the Microsoft Dynamics NAV 2009 Developer and IT Pro Documentation.

In the CASE switch, CreateCustomer is the name of the document type that this codeunit processes. If the codeunit supports several document types, list the document types in the switch. CreateCustomerHandle is the document handling function that processes the request document.

CreateCustomerHandle Function

The following code example contains sections from the CreateCustomerHandle function from Mobile Document Handler.

First, the function checks the permissions for the mobile user who has submitted the request document.

CopyCode imageCopy Code 
WITH Permission DO
  MobPermissionMgt.CheckPermission(
	MobDocQueue."Mobile User ID","Object Type"::"Table Data",DATABASE::Customer,
	"Read Permission"::" ","Insert Permission"::Yes,"Modify Permission"::" ",
	"Delete Permission"::" ","Execute Permission"::" ");

The code illustrates how this document handling function uses the CheckPermission function from the Mobile Permission Management codeunit to check that the mobile user has the appropriate permissions to each table that the request document accesses. In this example, the mobile user must have permission to insert records in the Customer table because the request document is for creating customers.

NoteNote

This permissions check does not replace the Microsoft Dynamics NAV security system. You must have assigned the appropriate security roles to the mobile users.

Next, the function reads the XML of the request document.

CopyCode imageCopy Code 
MobDocQueue.LoadXMLRequestDoc(XMLRequestDoc);

XMLRootNode := XMLRequestDoc.documentElement;

XMLNodeList := XMLRootNode.childNodes;

FOR i := 1 TO XMLNodeList.length DO BEGIN
  XMLCurrNode := XMLNodeList.item(i - 1);
  MobXMLMgt.GetAttribute(XMLCurrNode,’name’,AttributeValue);
  CASE AttributeValue OF
	’CustomerDetailTasklet’: XMLCustomerNode := XMLCurrNode.firstChild;
	’CustomerCreditLimitDetailTasklet’: XMLCreditlimitNode := XMLCurrNode.firstChild;
	’CustomerContactDetailTasklet’: XMLContactNode := XMLCurrNode.firstChild;
	ELSE
	ERROR(Text001,AttributeValue);
  END;
END;

In the code, CustomerDetailTasklet, CustomerCreditLimitDetailTasklet, and CustomerContactDetailTasklet are names of tasklets in the UserRole.xml file for the mobile application. In this example, the application is the Microsoft Dynamics Mobile sample application. For more information, see Microsoft Dynamics Mobile Orchestration Guide online.

The CreateCustomerHandle function breaks the XML document into sections that correspond to the tasklets. Each section is then passed on to a separate function that processes the business logic for that tasklet. For example, XMLCustomerNode is the section of the XML document that corresponds to the CustomerDetailTasklet tasklet. Later, you will see how this is processed by the CustomerNodeHandle function.

Next, the function inserts a record in the Customer table, calls the three functions to process each of the three tasklet sections, and then saves the modified records in the Customer and Mobile Document Queue tables.

CopyCode imageCopy Code 
Customer.INIT;
Customer.INSERT(TRUE);

CustomerNodeHandle(XMLCustomerNode,Customer);
CreditLimitNodeHandle(XMLCreditlimitNode,Customer);
ContactNodeHandle(MobDocQueue,XMLContactNode,Customer);

Customer.MODIFY(TRUE);

RecRef.GETTABLE(Customer);
MobDocMgt.LogInsertion(MobDocQueue,RecRef);

SaveResult(MobDocQueue,Customer);

In the example, the CustomerNodeHandle(XMLCustomerNode,Customer); statement calls the CustomerNodeHandle function and passes on the XML section that contains the customer information. SaveResult is a function that updates the mobile document queue with the result from the processing. This is described in a later section.

CustomerNodeHandle Function

The following code example illustrates a function that processes a tasklet section of the XML document, in this example the CustomerNodeHandle function from Mobile Document Handler. In Mobile Document Handler, the CreateCustomerHandle function passes on the section of the request document that contains information about the customer to the CustomerNodeHandle function. This section corresponds to the CustomerDetailTasklet tasklet in the Microsoft Dynamics Mobile sample application.

CopyCode imageCopy Code 
MobXMLMgt.FindNode(XMLCustomerNode,’name’,XMLCurrNode);
Customer.VALIDATE(Name,XMLCurrNode.text);

MobXMLMgt.FindNode(XMLCustomerNode,’email’,XMLCurrNode);
Customer.VALIDATE("E-Mail",XMLCurrNode.text);

MobXMLMgt.FindNode(XMLCustomerNode,’type’,XMLCurrNode);
Customer.VALIDATE("Customer Disc. Group",XMLCurrNode.text);

In the code, MobXMLMgt is a global variable for codeunit 8704 Mobile XML DOM Management. The CustomerNodeHandle function uses the FindNode function to extract information about the customer name, e-mail address, and customer discount group. The function then calls VALIDATE on the new record in the Customer table to set the appropriate field values for the new customer and validate the values. For more information, see VALIDATE in the Microsoft Dynamics NAV 2009 Developer and IT Pro Documentation.

NoteNote

The code in the CustomerNodeHandle function specifies both the elements in the incoming XML document and the corresponding fields in the Customer table. You must know the structure of the XML document in order to process it. You can see the structure in the schema for the mobile application. For more information, see Microsoft Dynamics Mobile Orchestration Guide online.

SaveResult Function

The following code example illustrates a function that creates a response to the mobile user and updates the mobile document queue with the new status for the request document. In Mobile Document Handler, the SaveResult function is called from the CreateCustomerHandle function when the request document has been processed.

CopyCode imageCopy Code 
WITH MobDocQueue DO BEGIN
  MobDocMgt.CreateXMLResponseDocCompleted(XMLResultDoc,"Message ID",STRSUBSTNO(Text002,Customer.TABLECAPTION,Customer."No."));

  XMLRootNode := XMLResultDoc.documentElement;
  MobXMLMgt.AddElement(XMLRootNode,’responseData’,’’,XMLRootNode.namespaceURI,XMLCreatedNode);
  MobXMLMgt.AddElement(XMLCreatedNode,’newCustomerAccount’,Customer."No.",XMLRootNode.namespaceURI,XMLCreatedNode);

  SaveXMLResultDoc(XMLResultDoc);
  Status := Status::Completed;
  MODIFY;
END;

The code uses functions on codeunits 8701 Mobile Document Management and 8704 Mobile XML DOM Management to create an XML document that is sent as a response to the mobile user, and then it updates the record in the Mobile Document Queue table.

See Also