To expose an X++ method as a custom service, you need to create the following artifacts:

A service implementation class contains the code that implements the business logic to publish.

You can use any X++ class as a service implementation class. Service implementation classes don’t have to implement any interfaces or extend any super-classes. A class definition for a service implementation class MyService could look like this:

public class MyService
{
}

There are, however, constraints that govern which methods of a service implementation class can be published as service operations. Eligible methods are public methods that use only parameters with data types that can be serialized and deserialized; this includes most primitive data types in addition to valid Microsoft Dynamics AX data contracts. In addition, eligible methods must be declared as service operations in the service contract in the Application Object Tree (AOT).

The following code shows an example of a method that can be declared as a service operation in the AOT, assuming the X++ type MyParam is a valid data contract. (For more information, see the section Data contracts, later in this chapter.)

[SysEntryPointAttribute(true)]
public MyParam HelloWorld(MyParam in)
{
  MyParam out = new MyParam();
  out.intParm(in.intParm() + 1);
  out.strParm("Hello world.
");
  return out;
}

Service contracts define which methods of a service implementation class are publishable as service operations and provide additional metadata that specifies how these methods should be published.

To create a new service contract, you need to create a new child node in the AOT under the Services node; for example, MyService.

The newly created AOT node has a few properties to initialize before any methods of the service can be published as service operations:

Finally, you need to add service operations to the service contract. To do this, expand the new AOT node, right-click, and then point to Operations > Add Operation.

Note that you can publish only methods as service operations that have been explicitly added to the service contract in the AOT.

A data contract is a complex X++ data type that can be used for input and output parameters in service operations. Most importantly, data contracts must be serializable. You can control how an X++ class is serialized and deserialized by the Microsoft Dynamics AX service framework through the X++ attributes DataContractAttribute and DataMemberAttribute:

The following code shows a sample definition for the data contract MyParam, which is used in the previous example:

[DataContractAttribute]
public class MyParam
{
  int intParm;
  str strParm;
}

The following code shows a sample property that is included in the data contract:

[DataMemberAttribute]
public int intParm(int _intParm = intParm)
{
  intParm = _intParm;
  return intParm;
}

If you want to use X++ collection types in data contract definitions, you need to ensure that all contained elements are of a data type that is supported for data contracts. Moreover, you need to provide additional metadata with the definition of the service method that uses the parameter, specifying the exact data type of the values in the collection at design time. You do this by using the X++ attribute AifCollectionTypeAttribute, as shown here for a sample method UseIntList():

[SysEntryPointAttribute(true),
  AifCollectionTypeAttribute('inParm', Types::Integer)]
public void UseIntList(List inParm)
{
  ...
}

The two parameters you need to pass into the constructor of the attribute are the name of the parameter to which the metadata is to be applied (inParm in the example) and the type of elements in the collection (Types::Integer in the example).

If you want to store X++ class types in your collection, you must also specify the class, as shown in the following example:

[SysEntryPointAttribute(true),
  AifCollectionTypeAttribute('return', Types::Class, classStr(MyParam))]
public List ReturnMyParamList(int i)
{
  ...
}

The three parameters that are passed into the AifCollectionTypeAttribute constructor are the name of the parameter (return), the type of the elements of the collection type (Types::Class), and the specific class type (MyParam).

After you create all of the artifacts that are necessary for the custom service, you need to register the new service with the Microsoft Dynamics AX service framework. To register the service (in this example, MyService) with AIF, expand the Services node in the AOT, right-click the node you created earlier, and then point to > Add-Ins > Register Service.

As a result of the registration, you can now publish all declared service operations of your service. For more information, see the section Publish Microsoft Dynamics AX services, later in this chapter.

Just like custom services, all document services in Microsoft Dynamics AX 2012 require a service contract, a service implementation, and a data contract. For document services, these artifacts are generated from Axd queries; thus, their default implementation follows conventions and looks as follows:

For a complete list of document service artifacts, see the “Services and Application Integration Framework (AIF)” section of the Microsoft Dynamics AX 2012 SDK (http://msdn.microsoft.com/en-us/library/gg731810.aspx).

The following sections touch on a few selected topics for both Axd<Document> and Ax<Table> classes. For more information, see the “AIF Document Services” section of the Microsoft Dynamics AX 2012 SDK (http://msdn.microsoft.com/en-us/library/bb496530.aspx).

Axd<Document> classes (such as AxdSalesOrder) extend the X++ class AxdBase. Among other things, Axd<Document> classes do the following:

Axd<Document> classes provide default implementations for XML serialization for all data objects that are used. These classes derive XML schema definitions used for XML serialization directly from the structure of the underlying query. The XML serialization code uses Microsoft Dynamics AX concepts such as extended data types (EDTs) to further restrict valid XML schemas and improve XML schema validation. Moreover, when generating XML schemas, Axd<Document> classes take the data access layer features that have been introduced in Microsoft Dynamics AX 2012 into consideration. For example, the generated XML schema definitions reflect date-effective table fields, expanded dimension fields, and the inheritance structure of the tables used in the underlying Axd query, if applicable; surrogate foreign key fields are replaced with alternate keys, if configured.

Axd<Document> classes always access tables through the Ax<Table> classes. During serialization, Axd<Document> classes rely on AxCommon or custom Ax<Table> classes to persist data to tables and to read data from tables.

Figure 12-2 illustrates the mapping between a Microsoft Dynamics AX query used for the Axd<Document> class AxdSalesOrder and the generated XML schema definition.

Figure 12-2. Correlation between the AOT query and the XML document structure.

Axd<Document> classes also provide an API for orchestrating cross-table field validation and defaulting. Validation and defaulting logic that is relevant only for a specific Axd<Document> class, but not for all Axd<Document> classes that use the same table, can also be implemented in Axd<Document> classes.

Axd<Document> instances can be uniquely identified through AifEntityKeys, which consist of a table name (name of the root table for the Axd query), the field names for a unique index of that table, and the values of the respective fields for the retrieved record. In addition, AifEntityKeys holds the record ID of the retrieved records.

Ax<Table> classes (such as AxSalesTable and AxSalesLine) derive from the X++ class AxInternalBase. Unlike in earlier versions of Microsoft Dynamics AX, an Ax<Table> class is not needed for each table that is used in a document service; instead, the Ax<Table> class AxCommon has been introduced in Microsoft Dynamics AX 2012, which Axd<document> classes use by default to access tables.

However, there are scenarios in which custom Ax<Table> classes are required; for example, when parm methods for fields on the underlying table are needed to do the following:

Although optional in Microsoft Dynamics AX 2012, Ax<Table> classes can be generated as part of the document service with the AIF Document Service Wizard.

You generate document services based on Axd queries by using the AIF Document Service Wizard. This section discusses a few selected aspects of generating and maintaining document services.

Create Axd queries Although general guidelines for working with Microsoft Dynamics AX queries apply to Axd queries, some additional constraints and guidelines apply:

Generate a document service To generate a document service from an existing Axd query, you can use the AIF Document Service Wizard. To start the wizard, on the Tools menu, point to Application Integration Framework > Create Document Service. This section provides a high-level description of the AIF Document Service Wizard and some important notes about how to use it.

In the wizard, you can select the service operations you want to generate for your service: create, read, update, delete, find, findKeys, getKeys, and getChangedKeys. If you select Generate AxBC classes when running the wizard, the wizard generates new Ax<Table> classes with parm methods for the fields of the tables used in the query.

The AIF Document Service Wizard uses the document name—which you enter on the first screen—to derive names for the generated artifacts. You can change the document name (and thus the derived names for the artifacts) in the wizard before the artifacts are generated. Names of AOT objects are limited to 40 characters. If you choose a document name that produces names that are too long for one or more artifacts, you may get error messages.

Once the wizard finishes, it displays a report of all generated artifacts and any errors encountered. You need to fix all errors before you start customizing the code that the wizard generates.

You can use the Update Document Service dialog box to update existing document services; for example, to add a service operation that you had not selected initially.

Microsoft Dynamics AX 2012 includes over 100 ready-to-use document services. These include services such as SalesOrderService and CustomerService. You can find a list of these services in the AOT Services node, or in the topic “Standard Document Services” in the Microsoft Dynamics AX 2012 SDK (http://msdn.microsoft.com/en-us/library/aa859008.aspx).

For a more comprehensive discussion of the AIF Document Service Wizard and generating Axd<Document> and Ax<Table> classes, see the “AIF Document Services” section of the Microsoft Dynamics AX 2012 SDK (http://msdn.microsoft.com/en-us/library/bb496530.aspx).

In many cases, you might need to customize the document services that you have generated from queries or that are included with Microsoft Dynamics AX 2012 to better fit your business needs. This section touches on some of the most common scenarios for customizing document services, including customizing the tables or queries, service operations, validation, defaulting, queries, and security.

Customize tables When you customize a table that is used by a document service (for example, by adding a column), you need to update the service implementation—that is, the Axd<Document> and Ax<Table> classes and the data objects—to reflect these changes.

Add custom service operations You can change the behavior of any service operation by modifying its X++ implementation. In addition, you can add custom service operations to any document service by following the same steps used for adding service operations to custom services.

Customize validation logic Validation logic is crucial for enforcing data hygiene. Ideally, invalid data never is persisted in the Microsoft Dynamics AX data store.

Well-designed validation logic has the following characteristics:

Validation code consists mainly of the following elements:

The following code, the prepareForSave method for AxdSalesOrder, is an example of cross-table validation. It calls validation methods for the Ax<Table> classes AxSalesTable and AxSalesLine (in addition to other Ax<Table> classes, which have been removed from this example):

public boolean prepareForSave(AxdStack _axdStack, str _dataSourceName)
{

    // ...

    switch (classidget(_axdStack.top()))
    {
        case classnum(AxSalesTable) :
            axSalesTable = _axdStack.top();
            this.checkSalesTable(axSalesTable);
            this.prepareSalesTable(axSalesTable);
            return true;

        case classnum(AxSalesLine) :
            axSalesLine = _axdStack.top();
            this.checkSalesLine(axSalesLine);
            this.prepareSalesLine(axSalesLine);
            return true;

        // ...
    }

    return false;
}

Customize defaulting logic You can customize the defaulting logic for table fields that is executed as part of creating or updating table rows. Defaulting logic helps increase the usability of both interactive client applications and Microsoft Dynamics AX service interfaces. It derives initial values for table fields from other data—such as values of other table fields—and thus, it doesn’t require explicit value assignments for the defaulted table fields. It also helps reduce the amount of data required to manipulate more complex entities, such as sales orders, while lowering the probability of erroneous data entry.

Well-designed defaulting logic has the following characteristics:

Microsoft Dynamics AX 2012 still supports the approach to implementing defaulting logic that was supported in previous versions of Microsoft Dynamics AX. However, in Microsoft Dynamics AX 2012, mechanisms for tracking field states (such as not set and defaulted) have been added to tables, which means that you can implement defaulting logic directly in table classes. This allows for defaulting logic to be used not only by Axd<document> classes, but also from forms, and so on. Note that because now you can implement defaulting logic directly in the table class, an Ax<Table> class is not necessary for implementing standard defaulting code.

For more details about implementing and customizing defaulting logic in Microsoft Dynamics AX 2012 and information about how to customize document services in general, see the “AIF Document Services” section of the Microsoft Dynamics AX 2012 SDK (http://msdn.microsoft.com/en-us/library/bb496530.aspx).

Full updates are the default behavior for document services. To use this mode, add code to your client application to do the following:

The following C# code provides a conceptual example of how to apply a full update to an existing sales order:

// instantiate and initialize callContext, entityKeys, serviceOrderService
MyServiceGroup.EntityKey[] entityKeys = ...
MyServiceGroup.CallContext callContext = ...
MyServiceGroup.SalesOrderServiceClient salesOrderService = ...
...

// read sales order(s) (including document hash(es)) using entityKeys
MyServiceGroup.AxdSalesOrder salesOrder =
    salesOrderService.read(callContext, entityKeys);

// handle errors, exceptions; process sales order, update data
...

// persist updates on the server (exception handling not shown)
salesOrderService.update(callContext, entityKeys, salesOrder);

In many scenarios, full updates are inefficient. Imagine a large sales order with many sales lines—having more than 1,000 is not uncommon. If you use a full update, you would have to retrieve the entire sales order with all sales lines, apply your changes to the one sales line you want to update, and then send back the entire sales order—including all unchanged sales lines. This operation can be costly when you consider the validation and defaulting logic invoked on the server for each sales line.

Instead of performing a full update, you can apply a partial update. Partial updates use the same service operation as full updates do: update. However, with partial updates, you can send partial documents that contain only the changed (added, modified, or deleted) data. For child elements, documents sent in partial update requests contain processing instructions specifying how to handle each (child) record included in the partial document to avoid ambiguity. Consequently, the process for updating documents by using partial updates contains one additional step:

The following code provides a conceptual example of how to apply a partial update to a sales order:

// instantiate and initialize callContext, entityKeys, serviceOrderService
MyServiceGroup.EntityKey[] entityKeys = ...
MyServiceGroup.CallContext callContext = ...
MyServiceGroup.SalesOrderServiceClient salesOrderService = ...
...

// read sales order(s) (including document hash(es)) using entityKeys
MyServiceGroup.AxdSalesOrder salesOrder =
    salesOrderService.read(callContext, entityKeys);

// handle errors, exceptions; process sales order, update data
...

// example: update the first sales order and mark it for partial update
AxdEntity_SalesTable[] salesTables = salesOrder.SalesTable;
salesOrder.SalesTable = new AxdEntity_SalesTable[] { salesTables[0] };
// document-level directive, requesting a partial update
salesOrder.SalesTable[0].action = AxdEnum_AxdEntityAction.update;

// table-level directive, requesting to delete the first sales line
AxdEntity_SalesLine[] salesLines = salesOrder.SalesTable[0].salesLine;
salesOrder.SalesTable[0].SalesLine = new AxdEntity_SalesLine[] { salesLines[0] };
salesOrder.SalesTable[0].SalesLine[0].action = AxdEnum_AxdEntityAction.delete;

// remove child data sources w/o updates (DocuRefHeader, etc.) from salesTable
...

// persist updates on the server (exception handling not shown)
salesOrderService.update(callContext, entityKeys, salesOrder);

The services framework relies on optimistic concurrency control (OCC) to resolve conflicts when multiple concurrent update requests occur. To be able to detect whether a document has changed since it was last read, and to avoid inadvertently overwriting such changes, the service framework uses document hashes to identify versions of a business document.

Document hashes are computed for a specific document instance from its contents; they are derived not only from the root-level data source (such as the sales header) but also from all of the joined data sources (such as a sales line). In other words, if a field in any table that is included in the business document changes, the document hash changes too.

To obtain the document hash for a business document, your code must first read the document. It can then use the document hash that was returned inside the document in a subsequent update request.

The Send API features a set of methods that can be used to send unsolicited one-way messages from Microsoft Dynamics AX by means of integration ports, through which the consumers can pick up the messages. This API sends a single message: the body of the message contains the XML that is generated by invoking the read service operation of the AIF document service referenced by the serviceClassId (it must reference a class that derives from AifDocumentService) with the parameter entityKey.

To see a working example of how you can use this API, look at the code behind the method clicked for the button SendXmlOriginal on the form CustInvoiceJournal. The API methods are defined on the class AifSendService and include the method submitDefault:

public static void submitDefault(
    AifServiceClassId serviceClassId,
    AifEntityKey entityKey,
    AifConstraintList constraintList,
    AifSendMode sendMode,
    AifPropertyBag propertyBag = connull(),
    AifProcessingMode processingMode = AifProcessingMode::Sequential,
    AifConversationId conversationId = #NoConversationId
)

By using the two optional parameters in the preceding signature, processingMode and conversationId, you can take advantage of the parallel message processing feature for asynchronous adapters:

The AxdSend API provides functionality to send unsolicited one-way messages. The user selects the outbound integration port through which the documents are sent at run time. If more than one document needs to be sent, the user also selects the exact set of entities at run time. This feature has been implemented for several Microsoft Dynamics AX document services, such as AxdPricelist and AxdBillsOfMaterials.

The AxdSend framework provides default dialog boxes for selecting integration ports and entity ranges and allows the generation of XML documents with multiple records. You can use the framework to provide specific dialog boxes for documents that require more user input than the default dialog box provides.

The default dialog box includes an integration port drop-down list and, optionally, a Select button to open the standard query form. The query is retrieved from the Axd<Document> class that the caller specifies. Many integration ports can be configured in AIF, but only a few are allowed to receive the current document. The lookup shows only the integration ports that are valid for the document, complying with the constraint set up for the read service operation for the current document.

The framework requires minimal coding to support a new document. If a document requires the user to just select an integration port and fill out a query range, most of the functionality is provided by the framework without requiring additional code.

An example dialog box for the AxdSend framework is shown in Figure 12-3.

Figure 12-3. The Send Document Electronically dialog box for bills of materials.

If an Axd<document> requires a more specific dialog box, you inherit the AxdSend class and provide the necessary user interface interaction to the dialog box method. In the following code example, an extra field has been added to the dialog box. You just add one line of code to implement parmShowDocPurpose from the AxdSend class and to make this field appear on the dialog box:

static public void main(Args args)
{
   AxdSendBillsOfMaterials axdSendBillsOfMaterials;
   AifConstraintList       aifConstraintList;
   AifConstraint           aifConstraint;
   BOMVersion              bomVersionRecord;

   axdSendBillsOfMaterials = new  AxdSendBillsOfMaterials();
   aifConstraintList       = new AifConstraintList();
   aifConstraint           = new AifConstraint();

   aifConstraint.parmType(AifConstraintType::NoConstraint);
   aifConstraintList.addConstraint(aifConstraint);

   if (args && args.record().TableId == tablenum(BOMVersion))
   {
       bomVersionRecord = args.record();
       axdSendBillsOfMaterials.parmBOMVersion(bomVersionRecord);
   }

   // added line to make the field appear on the dialog box
   axdSendBillsOfMaterials.parmShowDocPurpose(true) ;

   axdSendBillsOfMaterials.sendMultipleDocuments(
      classnum(BomBillsofMaterials),
      classnum(BomBillsofMaterialsService),
      AifSendMode::Async,
      aifConstraintList);
}

Sorting isn’t supported in the AxdSend framework, and the query structure is locked to ensure that the resulting query matches the query defined by the XML document framework. Because of this need for matching, the AxdSend class enforces these sorting and structure limitations. The query dialog box shows only the fields in the top-level tables because of the mechanics of queries with an outer join predicate. The result set will likely be different from what a user would expect. For example, restrictions on inner data sources filter only these data sources, not the data sources that contain them. The restrictions are imposed on the user interface to match the restrictions on the query when using the document service’s find operation.