Messaging in Ax

About action messages [AX2012] Applies To: Microsoft Dynamics AX 2012 R3, Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012 An action message is a system-generated suggestion to change an existing planned order. Action messages are generated by the master scheduling calculation in response to changed requirements. For example, the due date or quantity may have changed because an order was firmed. You decide whether to make the changes that are suggested. You can configure how action messages are calculated for a coverage group that you attach to an item. Selecting action messages In the Coverage groups form, you can select the action messages that you want the system to generate, and the coverage groups or items that the messages apply to. You can select the following action messages. Message Description Advance One or more planned orders should be moved forward in time. If you select this message, in the specify the maximum number of days between orders that are advanced. Postpone One or more planned orders should be postponed. If you select this message, in the Postpone m maximum number of days that are permitted between orders that are postponed. Decrease Production orders, purchase orders, and other receipt transactions should be decreased to preve Increase Production orders, purchase orders, and other receipt transactions should be increased to preven Derived actions Actions that are derived from requirements can be transferred to component items. Configure Message Queuing to work with Microsoft Dynamics AX Dynamics AX 4.0 An adapter for Microsoft Message Queuing (also known as MSMQ) is included with your Microsoft Dynamics AX installation. Important To send documents using MSMQ, you must use a domain account for the AOS account. For more information, (AOS) instance. To send documents using MSMQ, you must install MSMQ on a computer in your network and create at least one public queue. Note Whenever the word "queue" is used in this topic, it refers to a queue created and maintained using MSMQ. To receive documents using MSMQ, you must install MSMQ and create at least one queue on a computer that has Application Object Server (AOS) installed, and that has been configured to run the AIF batch jobs. For more information about these batch jobs, see Start and stop the asynchronous Application Integration Framework (AIF) services. right-click the Public Queues folder and click New > Public Queue. Click OK. Create a queue A queue for inbound messages can be either private or public. To create a new private queue. 2. To create a new public queue. This computer must also be configured to run the AIF batch jobs that execute the AIF services. Click Start > Settings > Control Panel > Add or Remove Programs > Add/Remove Windows Components. 1. 8. Click Details. Click OK. a queue for outbound messages must be public. expand the Message Queuing folder. you must install MSMQ on a computer with AOS installed. 5. right-click the Private Queues folder and click New > Private Queue. 9. Under Services and Applications. see Configure an adapter and Configure a channel. 3. Select Application Server. Any queue used for receiving messages must be located on the same computer as the AOS that is configured to run the batch jobs that operate on the AIF queues. 3. 7. 6. Click Start > Settings > Control Panel > Administrative Tools > Computer Management. Select Active Directory Integration and Common. Install MSMQ on a Windows Server 2003 computer To configure MSMQ to receive documents. 1. 2. Click Details. Click Next to install. 4. 2.To configure the MSMQ adapter (AifMSMQAdapter) for use in a channel. Select Message Queuing. 4. For . 1. When configuring the ACLs for newly created MSMQ queues. Under Services and Applications. Enter a name for the queue. ensure that the current. Select Allow on Send Message. Configure a queue for sending or receiving documents AIF requires all inbound messages to be authenticated. 5. 4. . If the current. 5. Right-click the queue you created and click Properties. logged-in user is denied certain privileges. Click OK. 3. select Allow on Receive Message and Peek Message for the AOS account (the domain account or Network Service account associated with the AOS instance). For inbound queues. select Authenticated. so you must configure outbound queues to be unauthenticated. authenticated messages are passed to AIF through authenticated or unauthenticated queues. If you are configuring an inbound queue. see Configure an endpoint. they may become locked out of the queue and unable to make changes. Everyone and Anonymous Logon users can send messages to any newly created queue.more information. Get Properties. and Get Permissions for endpoint users only. on the General tab. 2. Click the Transactional check box. 1. Inbound messages must be authenticated. set ACLs appropriately for all queues. Only the creator of the queue and an Administrator can receive messages from the queues. By default. logged-in user retains Full Control over each queue. 3. 6. expand the Message Queuing folder. inbound messages that are not authenticated fail to reach their destination (the local endpoint). AIF does not provide authentication for outbound messages. see Start and stop the asynchronous Application Integration Framework (AIF) services. For more information about configuring endpoint users and trusted intermediaries. 7. That is. When using MSMQ. Click Start > Settings > Control Panel > Administrative Tools > Computer Management. If you are configuring an outbound queue. On the Security tab. clear Authenticated. An AIF message uses XML to describe a self-contained unit of data that can consist of several parts. set the ACLs to select Allow on Send Message. 7. On the Owner tab. For more information about inbound and outbound integration ports. 9. Microsoft Dynamics AX 2012 This section of the documentation describes the tags used in Microsoft Dynamics AX services Application Integration Framework (AIF) messages. click Advanced. add the account for the AOS computer (for example. If the inbound queue is not on the same machine as the AOS. When you set up an inbound integration port and run an inbound service. see Integration ports and Managing integration ports. . When you set up an outbound integration port and run an outbound service to send data outside Microsoft Dynamics AX. For more information about AIF messages and schemas. grant the Peek Message and Receive Messagepermissions for the Anonymous Logon. AIF receives and processes an inbound message and generates an outbound message in response. First. then two additional entries need to be added to the queue's ACL. domain\computer-name$). 8. see Messages and transforms in AIF. AIF Messages [AX 2012] Applies To: Microsoft Dynamics AX 2012 R2. set the Current owner of this item: to be the logged-in user who performs the document exchange. All XML used in AIF is validated against the appropriate schema. and select Allow on Peek Message and Receive Message. These parts include a <Header> tag section and a <Body> tag section. Microsoft Dynamics AX 2012 Feature Pack. 6. AIF sends an outbound message. Get Properties. On the Security tab. Log off and then log back on to the computer.For outbound queues. Click OK to exit the menus. and Get Permissions for the Anonymous Logon user. Second. Select Allow on Receive Message and Peek Message for endpoint users only. For more information about AIF messages. The tags that are required in the <Body> section for Microsoft Dynamics AX document services depend on which service operation is specified in the <Action> tag in the <Header> section. The XSD schema for the <Header> section is duplicated in the file Message. see AIF Messages. The XSD is stored in the database in the AifSchemaStore table.xsd that is included with . the <Header> tag is nested one level under the <Envelope> tag. Note This topic has been updated to include information about features that were added or changed for Microsoft Dy XSD Schema Validation In the message XML. 2012 Applies To: Microsoft Dynamics AX 2012 R2. Microsoft Dynamics AX 2012 Feature Pack. Microsoft Dynamics AX 2012 This topic describes the <Header> tag section of inbound and outbound messages in Application Integration Framework (AIF). Message Header [AX 2012] Other Versions This topic has not yet been rated .The tag names in the <Body> section vary between different types of inbound and outbound messages.Rate this topic Updated: June 18. The <Header> section in inbound and outbound messages must validate against the same XSD schema. and update service operations for the document services included with Microsoft Dynamics AX. The in messa . <LogonAsUser> This is the name of the authorized Microsoft Dynamics AX user on whose authority the inbound request is being made. see Configure security for integration ports. delete. The value is replicated in the <RequestMessageId> tag of the corresponding outbound message. see Monitoring services and AIF. For more information. As an option. For more information. The value must be a valid Microsoft Dynamics AX user or user group expressed as a string in the format “Domain\User. the value can be bounded by braces (the two characters {}).Microsoft Dynamics AX under the installation directory. The s each o The value is a GUID that is not case sensitive. For more information. Table of Contained Tags The following table lists all the tags that can appear in the <Header> tag section. All tags are optional unless they are described as required in the table. Tag name Inbound description Outb <MessageId> This value uniquely identifies each message. The tags must appear in the same sequence they are listed in the table. Queue manager. By default. You can use this value to locate the particular message on the Exceptions. AIF generates one when the message is received. and History forms. see How to: Enable Checking for Duplicate Messages. For more information.” This value is used when trusted intermediaries are configured for an integration port using the AIF trusted intermediaries form. see Messages and transforms in AIF. If you do not provide a MessageId value. the inbound message is rejected if the system has seen this same <MessageId>value before for create. see Configure processing options. see Sequential and parallel processing in services and AIF. <ConversationId> This is a string value that several inbound messages have in common to force AIF to process only one message in the set at a time. The messages in the conversation are processed sequentially even when the channel is configured for parallel processing. If an the < value corres This t inbou The value is a string that contains information that uniquely identifies the service operation to the system. <Action> This tag is required. the default company is used. seeProcessing batched messages in AIF. AIF p inbou to det corres <PartitionKey> This is a string value that specifies the partition for the data that is used in the service operation. For more information. For more information about how conversation IDs work with batched messages. If no value is specified. a setting on the port determines whether the messages are processed sequentially or in parallel.<Company> This is a string value that identifies the company to use when you are retrieving data in a query from Microsoft Dynamics AX. If an the<P that v The default value for PartitionKey is the data partition that is set for the . The s inbou The maximum length of the string is 256 characters. For more information about how conversation IDs are used in parallel processing scenarios. If no company is specified. <RequestMessageI d> Does not apply to inbound messages. shown with line breaks to improve readability: <Action>http://schemas.com/dynamics/2008/01/ services/CustomerService/ read</Action> The following table shows the elements of the <Action> tag for the example. Element Portion of the <Action> value Location in AOT Namespace http://schemas. The following example is for the Customer Service (that is. Another property is the name of the Method on the . the CustCustomerService class). on the CustCustomerSer dynamics/2008/01/services/ Service Name CustomerService Under the Services node.microsoft. on the CustCustomerSer Service Operation read Under the Services node. the external name of the service. the co This o Dyna Elements of the <Action> Tag The <Action> tag consists of three elements: the namespace. or method on the service class.calling user. This option is available only if Microsoft Dynamics AX 2012 R2 is installed. and the service operation. For more information about data partitions. the Name property.microsoft.com/ Under the Services node. under the CustCustomer on the Read node. see Data partitioning architecture. Service operation name Description create Inserts new records into the database. see Customize service contracts. Read is a sub .the Name and Method properties have the same va The items specified in the <Action> tag determine the XSD schemas that the <Body> tag contents must comply with. click Service operations on the Service contract customizations FastTab for any inactive inbound or outbound integration port. read Reads complete data from records that match the specified key values. Every service that is listed on that form is also listed in the AOT in the Services node. <Action> Tag: Service Class The services that are exposed by Microsoft Dynamics AX are listed on the Select service operations form. delete Deletes records from the database. For more information. <Action> Tag: Service Operation for Document Services The following table lists the service operations that are available for document services. findKeys Reads the key values from records that match the specified fields and values. To view the available service operations. find Reads complete data from records that match the specified fields and values. 2012 Applies To: Microsoft Dynamics AX 2012 R2. Microsoft Dynamics AX 2012 Feature Pack. which are selected by the specified key values. getKeys Returns only the key values for the entities returned in a query.Rate this topic Updated: June 18. The <Body> tag must follow the . Message Body [AX 2012] Other Versions This topic has not yet been rated . update Modifies data in existing records. or many records. one. see Document Class Service Operations. For more information about service operations for document services.less verbose syntax. getChangedKeys Returns only the key values for the entities that have changed after the specified time Each type of <Action> message can affect zero. Microsoft Dynamics AX 2012 This topic describes the <Body> tag section of inbound and outbound messages in Application Integration Framework (AIF). The <Action> tag is nested under the <Header> tag. Xml <Body> <MessageParts> <QueryCriteria> <CriteriaElement> . the following table shows the XML tags that must be in the <Body> tag section for each action. For examples of inbound and outbound messages. Service operation in<Action> Tags in the inbound <Body> .closing </Header>tag. see Document Class Service Operations.. and is nested directly under the <MessageParts> tag. </CriteriaElement> </QueryCriteria> </MessageParts> </Body> For inbound messages. The following example shows the nesting relationship between the <MessageParts> tag and the tags in the body of an inbound Find message . The <MessageParts> Tag The first tag nested under <Body> must be the <MessageParts> tag. For more information about messages and their format in Microsoft Dynamics AX. see Example of Inbound XML Message and Example of Outbound XML Message. There is no requirement to specify the xmlns attribute on the <MessageParts> tag because the correct value is already specified on the outer <Envelope> tag. Tags in the <Body> of Inbound Messages The outermost tag in each table cell occurs immediately after the <MessageParts> tag. For more information about actions.. Tags Required for <Action> Values The values in the <Action> tag determine the XSD schema validations that are applied to the contents of the <Body> tag. see Messages and transforms in AIF. microsoft.com/dyn documents/Message"> <LedgerJournal xmlns = "http://schemas.microsoft.Create <serviceExternalName>  o <entityName> Examples could be as follows: <Customer>  o <CustTable> The following example shows the XML for a Create action for the LedgerJo <Body> <MessageParts xmlns = "http://schemas.com/dy documents/LedgerJournal"> <LedgerJournalTable class="entity"> <CurrencyCode>USD</CurrencyCode> <JournalName>Day1</JournalName> <JournalTotalCredit>50</JournalTotalCredit> <JournalTotalDebit>50</JournalTotalDebit> <JournalType>Daily</JournalType> <Name>Daily Journal 1</Name> <VoucherSeries>Ledger_3</VoucherSeries> <LedgerJournalTrans class="entity"> <AccountNum>11010</AccountNum> <AccountType>Ledger</AccountType> <AmountCurDebit>50</AmountCurDebit> <CurrencyCode>USD</CurrencyCode> <DocumentDate>2007-05-28</DocumentDate> <Invoice>00003</Invoice> <OffsetAccount>12020</OffsetAccount> <OffsetAccountType>Ledger</OffsetAccountType> <TransDate>2007-05-28</TransDate> <Txt>AxLedgerJournal inbound test trans 1</Txt> </LedgerJournalTrans> </LedgerJournalTable> </LedgerJournal> </MessageParts> </Body> Delete  <EntityKeyList> o <EntityKey> . the following table shows the XML tags that occur in the <Body> tag section for each action. Service operation in <Action> Tags in the outbound <Body . Update The following tags must come first:  <EntityKeyList> o <EntityKey> The following tags must come next:  <serviceExternalName> o <entityName> The tags <EntityKeyList> and <serviceExternalName> are at the same leve Both tags are nested one level deeper than <MessageParts>. GetChangedKeys  <CriteriaElement> <QueryCriteria> o <CriteriaElement> Read Same as Delete.Find  <QueryCriteria> o FindKeys. which is their The <EntityKey> tag sequence must align with the <entityName> tag seque Tags in the <Body> of Outbound Messages For outbound messages. GetKeys. <EntityKeyList xmlns = "http://schemas/microsoft. Update Same as Delete.Create  <EntityKeyList> o Delete <EntityKey> The <MessageParts> tag se Find  <serviceExternalName> o FindKeys. <EntityKeyList> Tag The <EntityKeyList> tag section contains one or more <EntityKey> tags. GetKeys. GetChangedKeys  <entityName> <EntityKeyList> o <EntityKey> Read Same as Find.com/ dynamics/2008/01/documents/Message"> . The following is the correct syntax for the <EntityKeyList> tag (with a line break added to improve this display). Details About Each Tag in the <Body> Section The following sections discuss the tags in more detail. The service class specified in the <Action> tag determines the table (or data source) that contains the records targeted by the <EntityKey>. Unlike the <EntityKeyList> tag.microsoft. Not shown is XML code elsewhere in the message that relates this <EntityKey> to the CustTable table. For example. This can occur for create and update <Action> operations.com/ dynamics/2006/02/documents/EntityKey"> <KeyData> <KeyField> <Field>AccountNum</Field> <Value>4507</Value> </KeyField> </KeyData> </EntityKey> <serviceExternalName> Tag This tag is named for the document service that is specified in the <Action> tag. <EntityKey> Example The following XML code is an example of the <EntityKey> tag section. <QueryCriteria> Tag The <QueryCriteria> tag section contains one or more <CriteriaElement> tags. under the<SalesOrderTable> tag there can be a <SalesLine> tag. For more information. Also.<EntityKey> Tag Each record in a table is uniquely identified by its value in the key field. Each <EntityKey> section identifies at most one record. In some tables the key is a set of two or more fields. Nested under this tag are tags for each field in the table (or a subset of those field tags). . The <EntityKey> tag section specifies the name and value for each key field. <entityName> Tag This tag is the name of the table (or data source) that the inbound message operates against. see Query Criteria Overview. nested under this tag could be another <entityName> tag for a child table. The <QueryCriteria> tag offers more flexibility than does the <EntityKeyList> tag. the <QueryCriteria> tag never occurs in an outbound message. Xml <EntityKey xmlns = "http://schemas. It identifies the record that has a value of 4507 in its AccountNum field. 2012 Applies To: Microsoft Dynamics AX 2012 R2.<CriteriaElement> Tag For matching records. see the following topics:  Messages and transforms in AIF  Document Schema Rules  How to: Generate a Document Schema Query Criteria Overview [AX 2012] Other Versions 2 out of 2 rated this helpful . Microsoft Dynamics AX 2012 . The <CriteriaElement> tag also offers several operators beyond the equals operator. the <CriteriaElement> tag section can specify field-value pairs that are not limited to key fields.Rate this topic Updated: January 20. XSD Validations The XSD schemas that are used to validate all parts of each message are stored in the following directory where you installed Microsoft Dynamics AX:  Program files\Microsoft Dynamics AX\60\Server\MicrosoftDynamicsAX\bin\Application\Share\Include For more information about XSD schema. Microsoft Dynamics AX 2012 Feature Pack. The code shows a <QueryCriteria> section that contains two <CriteriaElement> tags. The <QueryCriteria> tag never occurs in outbound messages. The purpose of the <QueryCriteria> tag is to provide a flexible way to control which records are returned from an inbound message. The <QueryCriteria> tag is valid only in messages that have Find or FindKeys specified in their <Action> tag. and the FindKeysservice operation. see Message Body. The <QueryCriteria> tag occurs in the <Body> tag section of an inbound message. . This means that the record information returned in the outbound message comes from records that satisfy any one of the following <CriteriaElement> conditions. For more information.This topic describes the <QueryCriteria> tag in inbound messages for Application Integration Framework (AIF). The <QueryCriteria> section is more flexible than the <EntityKeyList> section.com/ dynamics/2006/02/documents/QueryCriteria"> <CriteriaElement> <DataSourceName>CustTable</DataSourceName> <FieldName>Street</FieldName> <Operator>Range</Operator> <Value1>1</Value1> <Value2>5</Value2> </CriteriaElement> <CriteriaElement> <DataSourceName>CustTable</DataSourceName> <FieldName>Name</FieldName> <Operator>Equal</Operator> <Value1>Northwind Traders</Value1> <Value2/> </CriteriaElement> </QueryCriteria> Tags in the <CriteriaElement> Section The following table lists the tags that occur in the <CriteriaElement> section.microsoft. Example <QueryCriteria> Section The following XML code illustrates an inbound message. The message has an <Action> tag (not shown) which contains the CustomerService service. Xml <QueryCriteria xmlns = "http://schemas. The system uses Boolean OR logic to connect all the <CriteriaElement> tags. <Operator> One of several recognized operators. 1. which is required only when the Range operator is used. Tag name Description <DataSourceName> The name of the table that is targeted for the se targeted by the service that is specified in the < <FieldName> The name of a field in the table. which use the service CustomerService as a specific example. <DataSourceName> Value Aligned with Service You can determine the correct XML tag name for any service that is specified in the <Action> tag. The determination process is described by the following steps. used only when the Ran The following sections provide more details about some of the tags in the previous table. such as G <Value1> The string representation of any value that is a <Value2> The second operand. Open the Inbound ports form. Click System administration > Setup > Services and Application Integration Framework > Inbound ports. .Note All the tags are required except for <Value2>. 6. Click New to create a new port. <Operator> value Analogous X++ opera Equal == NotEqual != Greater > . click Service operations to open the Select service operations form and select the CustCustomerService. 4. Xml <xs:element name="Customer" type="tns:AxdCustomer" /> <Operator> Values The following table shows all the operators that are recognized as valid <Operator> tag values.createoperation. as is shown in the following schema code. 3.2. 5. In the Schema window that is displayed. Click the View schema button. 8. Click the left arrow button to move selected service operations to the Selected service operations list and close the form. Select Customize documents and then click Data policies to open the Document data policies form. the name attribute of the first element is the name that you must use for the first tag under <Body><MessageParts> in your inbound message. On the Service contract customizations FastTab. The name of the first element in our example is Customer. 7. GreaterOrEqual >= Less < LessOrEqual <= Range >= && <= Note The Range operator cannot be used to query hidden or locked ranges for a data source or field. seeQuery Properties. For more infor query range. You can retrieve XSDs for common schemas from the following directory where you installed Microsoft Dynamics AX: Program files\Microsoft Dynamics AX\60\Server\MicrosoftDynamicsAX\bin\Application\Share\Include . XSD Validations The <QueryCriteria> section is validated against an XSD schema. microsoft. 2012 Applies To: Microsoft Dynamics AX 2012 R2. This topic describes the <Fault> tag that occurs in outbound messages that report an error in the corresponding inbound message. If any error has occurred in processing the message.com/ dynamics/2008/01/documents/Message"> <Fault xmlns = "http://schemas. Xml <Body> <MessageParts xmlns = "http://schemas.</Text> </Reason> </Fault> </MessageParts> </Body> . Microsoft Dynamics AX 2012 When the Application Integration Framework (AIF) receives and processes an inbound message.Rate this topic Updated: January 10. See the Exception Log for details. The <Text> tag contains the textual information that you can use to diagnose the problem.microsoft.Example: Fault in an Outbound Message [AX 2012] Other Versions This topic has not yet been rated . it generates an outbound message in response. the service can generate information about the error to include in the response.com/dynamics/ 2008/01/documents/Fault"> <Code>RequestFailed</Code> <Reason> <Text xml:lang = "EN-US" >Request Failed. Microsoft Dynamics AX 2012 Feature Pack. Outbound <Fault> Example The following XML code example shows a <Body> tag section that contains a <Fault> tag. For more information.View the Exception Log The <Text> tag in the previous example instructed the user to view the Exceptions log. The log can be viewed in the Exceptions form. You can also view information about when the error was logged. In the Exceptions form. and a description of the error. The path of the directory resembles the following: \Program files\Microsoft Dynamics AX\60\Server\<MicrosoftDynamicsAX installation ID>\bin\Application\Share\Include . You can include the information in the exception log in the response on an inbound port by setting Include exceptions in fault in the Troubleshooting area on the Inbound ports form. the user who is associated with the error. Click System administration > Setup > Services and Application Integration Framework > Inbound ports. you can view information about the module and subsystem where the error occurred. and the form or business logic where the error occurred. You can retrieve XSDs for common schemas from your Microsoft Dynamics AX installation. Click System administration > Periodic> Services and Application Integration Framework > Exceptions. XSD Validations The <Fault> tag section is validated against the Fault XSD. see Configure troubleshooting options for integration ports.