Walkthrough: Deploying the Document Service in an Outbound Exchange
Important
This content is archived and is not being updated. For the latest documentation, see Microsoft Dynamics 365 product documentation. For the latest release plans, see Dynamics 365 and Microsoft Power Platform release plans.
Applies To: Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012
This walkthrough illustrates the following tasks:
Set up Application Integration Framework (AIF) components for an outbound exchange.
Code the outbound exchange.
Test the outbound exchange.
Prerequisites
To complete this walkthrough, you will need:
Microsoft Dynamics AX 2012
A developer license
The AxdLedgerJournal document service created in Walkthrough: Creating a Service by Using the AIF Document Service Wizard.
Setting Up Components for an Outbound Exchange
You create and configure an outbound integration port to deploy a document in an outbound exchange. In the following section you will create directories for inbound and outbound files, and create and configure an outbound enhanced integration port that uses the file system adapter.
You must first create an outbound directory. Microsoft Dynamics AX puts the XML files that it creates in the outbound directory.
To create and configure a directory
In Windows Explorer, create an outbound directory.
Important
Directories that are accessed by the file system adapter must grant appropriate access to the domain account under which the AOS runs. If the AOS runs under the NETWORK SERVICE account, you must grant permissions for that specific account. For example, granting full permissions to Everyone does not enable the file system adapter to access the files in the directory or network share accessed by the file system adapter if the AOS runs under the NETWORK SERVICE account.
We strongly recommend that you use a domain account or a managed service account in a production environment. Use the Network Service account only in development and testing environments. For more information, see Create service accounts.
Name the directory AIFout. For more information, see Walkthrough: Exchanging documents by using the file system adapter.
You must create a port for the outbound directory. You use an integration port to associate the file system adapter with the file system directory that you just created. For more information, see Managing integration ports.
To create the outbound port
Open the Outbound ports form. Click System administration > Setup > Services and Application Integration Framework > Outbound ports.
Click New.
Name the new integration port LedgerJournalOut.
To configure the outbound port to use the file adapter
In the Adapter list in the Address group, select File system adapter.
In the URI list, click the arrow to browse to the folder that you created that is named AIFOut.
On the Service contract customizations FastTab, click Service operations.
In the Select service operations form, select LedgerJournalService.read in the Remaining service operations list. Click the left arrow to move the service operation to the Selected service operations list.
Close the form.
On the Service contract customizations FastTab, select Customize documents and then click Data policies.
In the Document data policies form, click Enable all. The XPath field determines which entity is the source of the data element. In AxdLedgerJournal class, a data element can come from the document class itself, the LedgerJournalTable table, or the LedgerJournalTrans table.
Close the Document data policies form.
Expand the Troubleshooting FastTab, select All document versions for Logging mode.
In the Outbound ports form, click Activate to activate the port.
Coding the Outbound Exchange
After a new document is created and you have configured the integration port for the data that will be sent in an outbound exchange, you must write code to initiate the document transfer. For this example, you will create a Send electronically button on the General journal form.
The first step in writing the code to send a document is to identify the form from which the exchange will be initiated. The following steps describe how to get the form class name for the General journal form.
To identify the General journal form
Navigate to the General journal form. Click General Ledger > Journals > General journal.
Right-click a record in the General journal form, and then click Personalize.
Click the Information tab in the Personalization form. The Form name field contains the name of the form, and in this case, it should be LedgerJournalTable form. Click the Query tab to see that the form table is the LedgerJournalTable table.
In this section, you will add a button to the LedgerJournalTable form to initiate the sending of the ledger journal document. The user can send the ledger journal as an original or a duplicate. To do this, the form must contain a MenuButton control with two MenuItemButton controls.
To add a button
In the AOT, expand the Forms node and then expand the LedgerJournalTable node.
Expand Designs, expand Design, expand ActionPane: ActionPane, and then expand ActionPaneTab: ActionPaneTab.
Right-click ButtonGroup:ButtonGroup, select New control, and then click MenuButton.
Note
The VendPurchOrderJournal form has the same button structure for sending a purchase order. You can use this form as a reference when you implement your own send button. On the VendPurchOrderJournal form, expand the Design node, expand Tab:Tab, expand TabPage:Overview, expand ActionPane:ActionPane, expand ActionPaneTab:ActionPanetab, expand ButtonGroup:OverviewButtonGroup, and then expand MenuButton:MenuSendXML to view the form controls.
Right-click the new MenuButton control, click Properties, and then set the following properties.
Property
Value
Name
SendXMLMenu
Text
Send Electronically
In the AOT, right-click the MenuButton:SendXMLMenu button control, point to New control, and then click Button. This button specifies that the user is sending an original message.
Set the following properties on the new Button control.
Property
Value
Name
SendXMLOriginal
Text
Original
In the AOT, right-click the MenuButton:SendXMLMenu button control, point to New control, and then click Button. This button will specify that the user is sending a duplicate message.
Set the following properties on the new Button control and save your changes.
Property
Value
Name
SendXMLDuplicate
Text
Duplicate
When the user clicks the Send electronically button, the clicked event calls two methods from the LedgerJournalTable table:
canXMLBeSent
sendElectronically
These methods contain the code that sends the ledger journal document.
The canXMLBeSent method makes sure that an integration port has been configured for the selected document action. If there is no integration port configured, the code returns false. In this section you will add this method to the LedgerJournalTable table.
To add the canXMLBeSent table method
In the AOT, expand the Data Dictionary node, expand Tables, and then expand LedgerJournalTable.
Right-click Methods, and then click New method.
In the code editor, copy the following code into the new method.
boolean canXMLBeSent() { boolean ret; AifActionId actionId; AifEndpointList endpointList; AifConstraint aifConstraint = new AifConstraint(); AifConstraintList aifConstraintList = new AifConstraintList(); ; actionId = AifSendService::getDefaultSendAction(classnum(LedgerJournalService), AifSendActionType::SendByKey); if(actionId) { aifConstraint.parmType(AifConstraintType::NoConstraint); aifConstraintList.addConstraint(aifConstraint); endpointList = AifSendService::getEligibleEndpoints(actionId, aifConstraintList); if(endpointList.getEndpointCount()>0) { ret = true; } } return ret; }
The sendElectronically method gets the entity key for the selected journal, calls the method that retrieves the data, serializes that data into an XML message, and then sends the document to the gateway queue.
To add code to the sendElectronically table method
In the AOT, in the LedgerJournalTable table, right-click the Methods node, and then click New method.
In the code editor, copy the following code into the new method.
void sendElectronically(XMLDocPurpose _xMLDocPurpose, AifSendMode _aifSendMode = AifSendMode::Async) { AxdSendContext axdSendContext = AxdSendContext::construct(); AifEntityKey aifEntityKey = AifEntityKey::construct(); Map keyData; AifConstraintList aifConstraintList = new AifConstraintList(); AifConstraint aifConstraint = new AifConstraint(); ; keyData = SysDictTable::getKeyData(this); aifEntityKey.parmTableId(this.TableId); aifEntityKey.parmRecId(this.RecId); aifEntityKey.parmKeyDataMap(keyData); axdSendContext.parmXMLDocPurpose(_xMLDocPurpose); axdSendContext.parmSecurity(false); aifConstraint.parmType(AifConstraintType::NoConstraint) ; aifConstraintList.addConstraint(aifConstraint) ; AifSendService::submitDefault( classnum(LedgerJournalService), aifEntityKey, aifConstraintList, _aifSendMode, axdSendContext.pack()); }
Note
Parallel processing distributes the processing of messages across one or more instances of Application Object Server (AOS). To enable parallel processing for outbound messages, you use two optional parameters, processingMode and conversationID, in the call to the AifSendServicesubmitDefault() method.
The following example code illustrates the signature of the submitDefault method.
public static void submitDefault( AifServiceClassId serviceClassId, AifEntityKey entityKey, AifConstraintList constraintList, AifSendMode sendMode, [AifPropertyBag propertyBag = connull(), AifProcessingMode processingMode = AifProcessingMode::Parallel, AifConversationId conversationId = #NoConversationId ] )
You set a value for processingMode to indicate parallel or sequential processing. If no value is specified, AIF uses sequential processing. You set processingMode to AifProcessingMode::Parallel to indicate that messages can be moved from the AIF outbound processing queues to the AIF gateway queues in parallel. For sequential or first in first out (FIFO) processing, the default value AifProcessingMode::Sequential is used.
In parallel processing mode, you specify a value for conversationId when you want AIF to process all messages that use the same conversationId in sequential FIFO order. In other words, all messages that have the same conversation ID are processed sequentially. The processing order for other messages that have different values for conversationId is not guaranteed.
For more information, see Sequential and parallel processing in services and AIF.
In this section you will add code to the clicked events for the SendXMLOriginal and SendXMLDuplicate buttons.
To add code to the button clicked events
In the AOT, expand the Forms node and then expand the LedgerJournalTable form.
Expand Designs, expand Design, expand ActionPane: ActionPane, and then expand ActionPaneTab: ActionPaneTab.
Expand ButtonGroup:ButtonGroup, expand MenuButton:SendXMLMenu, and then expand Button:SendXMLOriginal.
Right-click the Methods node, click Override Method, and then select clicked.
In the code editor, enter the following code in the clicked event.
void clicked() { LedgerJournalTable ledgerJournalTableLocal; ; for (ledgerJournalTableLocal = LedgerJournalTable_ds.getFirst(true) ? LedgerJournalTable_ds.getFirst(true) : LedgerJournalTable; ledgerJournalTableLocal; ledgerJournalTableLocal = LedgerJournalTable_ds.getNext()) // Check to see if document can be sent. if (ledgerJournalTableLocal.canXMLBeSent()) { // Send the document. ledgerJournalTableLocal.sendElectronically(XMLDocPurpose::Original); } else { warning (strfmt("@SYS72175")); // TODO Add a ledger journal specific error message to the // label file. // warning (strfmt("@SYSnnnnn",ledgerJournalTableLocal.JournalNum)); } }Repeat steps 1 through 3 for the MenuItemButton:SendXMLDuplicate control.
In the clicked event of the MenutItemButton:SendXMLDuplicate button control, change XMLDocPurpose::Original to XMLDocPurpose::Duplicate.
Testing the Outbound Exchange
For AIF to begin sending and receiving documents for adapter-based exchanges, the services that move documents through the queues must be running as batch jobs within Microsoft Dynamics AX. For more information, see Configuring batch jobs and tasks for AIF.
To create the batch job
Open the Batch job form. Click System administration > Inquiries > Batch jobs > Batch jobs.
Create a new batch job and enter a name. For more information, see Create a batch job.
Click View tasks. On the Batch tasks form, press CTRL+N to add a row, and then enter a Task description and select the Company account.
Add four tasks that use the following classes to the batch job: AifGatewayReceiveService, AifGatewaySendService, AifInboundProcessingService, and AifOutboundProcessingService.
On the Batch job form, set a recurrence interval for the batch job. For testing, it is convenient to set the interval to one minute.
To start the batch job, change its status to Waiting.
To test sending the document
Open the General journal form. Click General ledger > Journals > General journal.
Click one of the journal lines, and then click the Send electronically button. Click Original to send the original document.
The selected ledger journal and its lines are serialized into XML with header information and sent to the gateway queue. When the AIF batch services run, the message will be selected from the gateway queue and sent to the AIFout directory that you created earlier.
See also
Walkthrough: Exchanging documents by using the file system adapter