Walkthrough: Creating a Service by Using the AIF Document Service Wizard

Straipsnis
11/29/2021

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 covers how to create a document query, a new service, and a document schema when you want to create a document service that is not included with Application Integration Framework (AIF). After you have created a document service, you can use it from modules within Microsoft Dynamics AX and external applications. Document services enable you to create reusable business logic. For information about which services are included with AIF, see Standard Document Services.

In the following scenario, you want to send data to an external system for reporting. You may also want to receive information through AIF from an external accounting system and then create a journal entry and its associated lines. In this scenario, a journal and its entries are stored in the LedgerJournalTable and LedgerJournalTrans tables.

Note

In this walkthrough, you create a new service from a query that has the data source set to LedgerJournalTable and the LedgerJournalTrans tables. The general journal service is already included in AIF. Be careful when you name objects so that they do not conflict with the existing general journal service. The name of the included class is AxdLedgerGeneralJournal. The query name for the included document is also AxdLedgerGeneralJournal.

The following illustration shows the relationship between the LedgerJournalTable table and the LedgerJournalTrans table (shown here with an abbreviated field list).

Ledger Journal Tables

The tables that contain journal entries.

This walkthrough illustrates the following tasks:

Creating a document query
Creating the service
Generating the document schema

Prerequisites

To complete this walkthrough, you need:

Microsoft Dynamics AX 2012
A developer license

Creating a Document Query

You use the AIF Document Service Wizard to create a service from a document query. The first step is to create the document query. For more information about document queries, see How to: Create a Document Query.

To create a document query

Press CTRL-D to open the AOT, right-click Queries, and then click New Query.
Expand the node for the new query that is named something like Query1.
In the AOT, right-click Data Dictionary, and then click Open New Window.
In the second AOT window, expand the Tables node and drag the LedgerJournalTable table onto the Data Sources node under the new query in the first window. By default, all of the fields in the data source are included in the query.

For more information, see How to: Create Queries by using the AOT.
Right-click the new data source, and then click Properties. In the Properties sheet, rename the query data source name from LedgerJournalTable_1 to LedgerJournalTable.
In the first AOT window, expand the LedgerJournalTable node. Drag the LedgerJournalTrans table onto the LedgerJournalTable Data Sources node.
Right-click the new query and then click Properties. In the Properties sheet, rename the query data source table from LedgerJournalTrans_1 to LedgerJournalTrans.
Set the JoinMode property to OuterJoin.
Right-click Fields in the LedgerJournalTable node and then click Properties. Set the Dynamic property to Yes. This setting makes sure that all fields are returned and is required when a table participates in an interitance relationship.
In the AOT, click the new query, and then in the Properties sheet, set the Name property to AxdLedgerJournal.

Note

As a best practice, the query name should always be the same as the document class name. This is especially true when you use the AIF Document Service Wizard to generate the service because it sets the document name to the name of the query by default.
In the AOT, expand the LedgerJournalTrans data source node, right-click Relations, and then select New Relation. By default, a relation is created between the LedgerJournalTable.JournalNum field and the LedgerJournalTrans.JournalNum field. This is because the data type for the JournalNum field is based on the LedgerJournalId extended data type which has a relation to the LedgerJournalTable.
Expand LedgerJournalTrans, right-click Fields, and then click Properties.
Set the Dynamic property to Yes.
Right click the LedgerJournalTrans node and then click Properties.
Set the FetchMode property to 1:n.
Press Ctrl+Shift+S to save the AxdLedgerJournal query.

Creating a Service

You use the AIF Document Service Wizard to create the service, document class, Ax <Table> classes, and other service related artifacts. For more information, see How to: Create a Service by Using the AIF Document Service Wizard.

To create a service by using the AIF Document Service Wizard

In the Developer Workspace, click Tools > Application Integration Framework > Create Document Service. The Welcome screen appears.
Click Next. In the Select document parameters screen, in the Query field, select the AxdLedgerJournal query. The default setting is the document name.
Click Next. In the Select code generation parameters screen, the Class names default setting is based on the AxdLedgerJournal query selected.
Select the Read and Create service operations that the service will expose. The AxdLedgerJournal class must support reading a single journal and its entries and creating a single journal and its entries. For more information, see Document Class Service Operations.
Click Next. In the Generate code screen, you can review the artifacts that will be generated, and then click Generate.
The Completed screen displays the artifacts that the wizard created. Click Finish.

Generating a Document Schema

The document schema, or XSD, defines the structure and format of the XML that is serialized or deserialized by the document class. In AIF, the schema for each document is generated by iterating through the query associated with the document class. The document schema defines the XML rules for the document. For more information, see Document Schema Rules.

When you use the AIF Document Service Wizard to create a service, it automatically creates an X++ job that you can run to generate the document schema. Use the following steps to generate the document schema for the service.

To generate the document schema for the service

Press Ctrl+Shift+P to open the Projects form.
Expand the Private node, and then double-click the AxdLedgerJournal project. This project contains all of the objects created by the AIF Document Service Wizard that are related to the new service.
Double-click the GenerateXSDSchema_AxdLedgerJournal job to open it in the code editor.
Press F5 to run the job. You will not see any message indicating the job has completed.

When you run this job, it creates a file that contains the schema for all of the fields in the document. The file location is c:\XSDSchema_AxdLedgerJournal.xml. Now that the service has been generated, your scenario may require that you add custom business logic code to the document service classes. For simplicity, we will consider this service implementation completed.

Next Steps

You can now use the document service you have created in an inbound or an outbound exchange. For more information about how to configure and code an outbound exchange using the file adapter, see Walkthrough: Deploying the Document Service in an Outbound Exchange

When using an inbound adapter-based exchange such as file system transfer or Message Queuing, you must run the AIF batch services so that the message is transferred to the gateway queue. The message is then transferred from the gateway queue, deserialized into an AxdLedgerJournal class, and then saved to the database by using the Ax <Table> classes. For more information about how to configure the AIF batch services for an inbound exchange, see Configuring batch jobs and tasks for AIF and Walkthrough: Exchanging documents by using the file system adapter.

Bendrinti naudojant