Message Header
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 topic describes the <Header> tag section of inbound and outbound messages in Application Integration Framework (AIF). For more information about AIF messages, see AIF Messages.
Note
This topic has been updated to include information about features that were added or changed for Microsoft Dynamics AX 2012 R2.
XSD Schema Validation
In the message XML, the <Header> tag is nested one level under the <Envelope> tag. The <Header> section in inbound and outbound messages must validate against the same XSD schema. The XSD is stored in the database in the AifSchemaStore table. The XSD schema for the <Header> section is duplicated in the file Message.xsd that is included with Microsoft Dynamics AX under the installation directory. For more information, see Messages and transforms in AIF.
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. The tags must appear in the same sequence they are listed in the table.
Tag name |
Inbound description |
Outbound description |
|---|---|---|
<MessageId> |
This value uniquely identifies each message. If you do not provide a MessageId value, AIF generates one when the message is received. The value is a GUID that is not case sensitive. As an option, the value can be bounded by braces (the two characters {}). The value is replicated in the <RequestMessageId> tag of the corresponding outbound message. You can use this value to locate the particular message on the Exceptions, Queue manager, and History forms. For more information, see Monitoring services and AIF. By default, the inbound message is rejected if the system has seen this same <MessageId> value before for create, delete, and update service operations for the document services included with Microsoft Dynamics AX. For more information, see How to: Enable Checking for Duplicate Messages. |
The system generates a unique GUID value for each outbound message. |
<LogonAsUser> |
This is the name of the authorized Microsoft Dynamics AX user on whose authority the inbound request is being made. The value must be a valid Microsoft Dynamics AX user or user group expressed as a string in the format “Domain\User.” This value is used when trusted intermediaries are configured for an integration port using the AIF trusted intermediaries form. For more information, see Configure security for integration ports. |
The inbound value is repeated in the outbound message. |
<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 no company is specified, the default company is used. |
If an explicit value was given for the <Company> in the inbound message, that value is reused for the <Company> in the corresponding outbound message. |
<Action> |
This tag is required. The value is a string that contains information that uniquely identifies the service operation to the system. |
This tag is required. The value is identical to the inbound value. |
<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. The maximum length of the string is 256 characters. If no value is specified, a setting on the port determines whether the messages are processed sequentially or in parallel. For more information, see Configure processing options. For more information about how conversation IDs work with batched messages, see Processing batched messages in AIF. For more information about how conversation IDs are used in parallel processing scenarios, see Sequential and parallel processing in services and AIF. |
The same value as was in the corresponding inbound message. |
<RequestMessageId> |
Does not apply to inbound messages. |
AIF puts the <MessageId> value from the inbound message into this tag. This enables you to determine which outbound message corresponds to your inbound message. |
<PartitionKey> |
This is a string value that specifies the partition for the data that is used in the service operation. The default value for PartitionKey is the data partition that is set for the calling user. For more information about data partitions, see Data partitioning architecture. This option is available only if Microsoft Dynamics AX 2012 R2 is installed. |
If an explicit value was given for the <PartitionKey> in the inbound message, that value is reused for the <PartitionKey> in the corresponding outbound message. This option is available only if Microsoft Dynamics AX 2012 R2 is installed. |
Elements of the <Action> Tag
The <Action> tag consists of three elements: the namespace, the external name of the service, and the service operation, or method on the service class. The following example is for the Customer Service (that is, the CustCustomerService class), shown with line breaks to improve readability:
<Action>https://schemas.microsoft.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 |
https://schemas.microsoft.com/ dynamics/2008/01/services/ |
Under the Services node, on the CustCustomerService node, the Namespace property. |
Service Name |
CustomerService |
Under the Services node, on the CustCustomerService node, the ExternalName property. |
Service Operation |
read |
Under the Services node, under the CustCustomerService node, under the Operations node, on the Read node, the Name property. Another property is the name of the Method on the service class. Usually the Name and Method properties have the same value. |
The items specified in the <Action> tag determine the XSD schemas that the <Body> tag contents must comply with.
<Action> Tag: Service Class
The services that are exposed by Microsoft Dynamics AX are listed on the Select service operations form. To view the available service operations, click Service operations on the Service contract customizations FastTab for any inactive inbound or outbound integration port. For more information, see Customize service contracts. Every service that is listed on that form is also listed in the AOT in the Services node.
<Action> Tag: Service Operation for Document Services
The following table lists the service operations that are available for document services.
Service operation name |
Description |
|---|---|
create |
Inserts new records into the database. |
delete |
Deletes records from the database. |
find |
Reads complete data from records that match the specified fields and values. |
findKeys |
Reads the key values from records that match the specified fields and values. |
read |
Reads complete data from records that match the specified key values. Read is a subset of the Find functionality, with slightly less verbose syntax. |
update |
Modifies data in existing records, which are selected by the specified key values. |
getKeys |
Returns only the key values for the entities returned in a query. |
getChangedKeys |
Returns only the key values for the entities that have changed after the specified timestamp. |
Each type of <Action> message can affect zero, one, or many records.
For more information about service operations for document services, see Document Class Service Operations.