Mobile devices can send various types of request documents to Microsoft Dynamics NAV, which the product must be able to process. For example, the mobile application can have one request document for creating a new customer and another for submitting an order. The request document is an XML file, so you must define a processing codeunit that reads the XML, verifies permissions, and executes the relevant business logic in Microsoft Dynamics NAV. These codeunits are document handlers. Each document handler corresponds to one or more document types. You must therefore determine which document types your application needs before you create the document handling codeunit.

In the standard implementation, Microsoft Dynamics NAV includes the following document handlers:

Guidelines for Defining Document Handlers in Microsoft Dynamics NAV

A document handler contains code that handles one or more types of incoming documents. In the default implementation, the sample document handler, 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. Codeunit 8725 Mobile Sales Document Handler contains four document handling functions and can handle four types of request documents.

Requisite Code

A document handling codeunit must contain code that does the following:

  • Ensures that the database remains consistent during document processing. Typically, this is handled by inserting a CONSISTENT(FALSE) statement at the start of the OnRun section and a CONSISTENT(TRUE) statement at the end of the OnRun section.

  • Specifies which document types are handled by which document handlers in the codeunit. Typically, this is handled by inserting a CASE statement in the OnRun section to send each incoming XML document of a certain document type to the corresponding document handling function.

  • Saves results to the mobile document queue and, optionally, sends a response document to the mobile device.

In addition, each document handling function, such as CreateCustomerHandle in codeunit 8703 Mobile Document Handler, must do the following:

  • Check the permissions for the mobile user who has submitted the request document. Use the CheckPermission function from the Mobile Permission Management codeunit to check that the mobile user has the appropriate permissions for each table that the request document accesses.

    The codeunit will run under the user account for Microsoft Dynamics NAV Application Server. In most cases, you want the code to run with more restricted permissions and, with the CheckPermission function, you can restrict access to tables.

  • Read the XML code in the request document. Use the LoadXMLRequestDoc function from the Mobile Document Queue table to open the XML document. You must add local variables to process the XML document by using the Microsoft XML, v6.0 automation server. For more information, see AUTOMATION in the Microsoft Dynamics NAV 2009 Developer and IT Pro Documentation.

    The XML code lists the tasklets that generated the request document and, usually, you want to process each tasklet in a separate function. Use a CASE statement to send each tasklet section of the request document to a separate function for further processing.

  • Optionally, log the changes. Mobile Sales Document Handler uses the LogInsertion function from codeunit 8701 Mobile Document Management to add to the change log.

Depending on the type of request document, you must include code that creates new records, reads or updates existing records, or marks records for deletion. You can put this code in a separate function or in the same function that processes the XML document itself. No matter where you place the code, you must know the names of the XML elements in the request document as well as in the Microsoft Dynamics NAV tables.

NoteNote

If Microsoft Dynamics NAV must run some logic before the request document can update the database, you can post to a temporary table for post-processing before updating the actual tables.

Microsoft Dynamics NAV includes a sample document handler, codeunit 8703 Mobile Document Handler, which can process requests to create new customers. For more information, see Document Handling in Codeunit 8703.

Security

The document handler must ensure that the mobile user has the appropriate permissions to execute the request. For example, if the incoming request document is for creating a sales order, the user submitting the request document must have been assigned security roles that grant access to the relevant tables. Use 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. The CheckPermission function calls an extended stored procedure on the SQL Server database that checks permissions that are based on Active Directory groups.

Caution noteCaution

The integration with Microsoft Dynamics Mobile requires that the Microsoft Dynamics NAV database runs the enhanced security model. This means that users can only be members of security groups in their own domain. For example, if your company has defined two Active Directory domains, Domain A and Domain B, a user who is in Domain A cannot be added to a security group in Domain B. For more information, see Security Overview for Mobile Functionality in Microsoft Dynamics NAV.

See Also