Chapter 19. Application domain frameworks
In this chapter
The organization model framework
The operations resource framework
Introduction
AX 2012 includes several domain-specific application frameworks that improve code reuse between application modules, reduce the need to assign artificial relationship roles in application modules, and reduce the number of tightly coupled interdependencies between application modules. For example:
The operations resource role that is assigned to people and work centers by the operations resource framework eliminates the need to assign employees and independent contractors artificially to the work center role so that they can participate in production planning and scheduling activities.
The performance dimensions extended from the dimension framework, the double-entry subledger journal provided by the accounting framework, and the source document abstraction provided by the source document framework enable operations processes such as purchasing, receiving, and invoicing to be decoupled from accounting processes such as budget control and financial reporting.
This chapter provides a short description of the conceptual foundation of some of the key application domain frameworks, in addition to links to white papers that provide more detailed implementation guidelines and code samples. This chapter does not contain an exhaustive list of application domain frameworks for AX 2012. Instead, it is intended to provide an overview of important functionality and suggestions about how you can use it. For information about additional application domain frameworks, see “White papers for developers” at http://technet.microsoft.com/EN-US/library/hh272882. This page is updated frequently with links to new white papers.
The names of entities in the conceptual domain models in this chapter are denoted in title case on first mention and italicized for emphasis.
The organization model framework
AX 2012 introduced a new organization model framework. This framework is designed to model key scenarios that are required by government organizations and corporations that have global operations, and those that have separate legal and operating organization structures. The organization model framework extends the company feature that was used in AX 2009 and earlier versions.
With the types of organizations that are included in AX 2012, you can model organizations in AX 2012 to mirror the way you operate them without having to customize the application. Most organizations go through an iterative operating cycle of monitor, measure, analyze, and improve. The analysis phase results in new business rules and policies and new strategic and operational initiatives to improve the organization’s performance. With the organization framework, you can create hierarchical structures that support this cycle of performance improvement.
How the organization model framework works
The organization model has two major components: Organization Types and Organization Hierarchies. The following sections describe these components.
Organization types
The organization model in AX 2012 introduced two new types of organizations: Legal Entity and Operating Unit.
Legal entity An organization with a registered or legislated legal structure that has the authority to enter into legal contracts and that is required to prepare statements that report on its performance. A legal entity and a company in AX 2012 are semantically the same. However, some functional areas in the application are still based on a data model that uses the concept of a company. These areas might have the same limitations as in AX 2009 and might have an implicit data security boundary.
Operating unit An organization that divides the control of economic resources and operational processes among people who have a duty to maximize the use of resources, to improve processes, and to account for their performance.
AX 2012 includes several types of operating units:
Business Unit A semi-autonomous operating unit that is created to meet strategic business objectives.
Cost Center A type of operating unit that describes an organization that is used to track costs or expenses. A cost center is a cost accumulator, and it is used to manage costs.
Department A type of operating unit that might have profit and loss responsibility and might consist of a group of cost centers. Departments are also often created based on functional responsibility or skill, such as sales and marketing.
Value Stream A type of operating unit that is commonly used in lean manufacturing. In lean manufacturing, a value stream owns one or more production flows that describe the activities and flows needed to supply a product, an item, or a service to the consumers of the product.
Retail Channel A type of operating unit that is commonly used in retail to represent a retail channel.
A Team is also a type of Internal Organization, but it is an informal group of people that is typically created for a specific purpose over a short duration. Teams might be created for specific projects or services. The other types of organizational units described here are more permanent, although they could require frequent minor updates or major changes because of restructuring.
These types of operating units support application functionality in AX 2012. However, every industry and business has unique requirements for its operating units and might call them by different names. Additionally, organizations can create custom types of operating units to meet their needs. For more information, see the “Creating a custom operating unit type” section later in this chapter.
When you arrange legal entities and operating units into hierarchies and use them for aggregated reporting, to secure access to data, and to implement business policies, they help you maintain internal control of your organization.
Organization hierarchies
An organization is a group of people who work together to perform operational and administration processes. Organization hierarchies represent the relationships between the Organizations that make up an enterprise or a government entity. In previous releases of Microsoft Dynamics AX, companies could not be organized into a hierarchy to represent the structure of an organization. In reality, organizations typically have a hierarchical structure for the reasons mentioned in the previous section.
The organization model framework in AX 2012 supports the creation of multiple hierarchies that take effect on multiple dates. This is useful in restructuring scenarios, where you want the updated hierarchy to become effective at a certain date in the future. The framework also supports hierarchies that are used for multiple purposes.
A Purpose defines how the organizational hierarchy is used in application scenarios. The purpose that you select determines the types of organizations that can be included in the hierarchy. Table 19-1 shows the types of organizations that you can use for each hierarchy purpose that is included in AX 2012.
The organization model has a significant impact on the implementation of AX 2012 and on the business processes being implemented. Executives and senior managers from different functional areas such as finance and accounting, human resources, operations, and sales and marketing should participate in defining the organization structures.
Figure 19-1 shows the conceptual domain model of the organization model framework.
When to use the organization model framework
You use the organization model framework to model how the business operates. You can use the organization model framework in two ways: by using the built-in integration with other application frameworks and existing AX 2012 modules, or by modeling custom scenarios to meet the needs of your organization.
Integration with other frameworks’ application modules
The organization model framework is inherently integrated with certain frameworks and modules in AX 2012:
Address book All internal organizations—legal entity, operating unit, and team—are types of the Party entity. This means that these organizations can use the capabilities of the address book to store address and contact information. For more information, see the “Implementing the Global Address Book Framework” white paper at http://technet.microsoft.com/en-us/library/hh272867.aspx.
Financial dimensions You can use legal entities and operating units to define financial dimensions and then use those financial dimensions in account structures. By using organizations as financial dimensions, an enterprise or government entity can analyze an organization’s financial performance. If two types of organizations are used as separate financial dimensions in the account structure, the relationships between organizations described through hierarchies can also be used as constraints. For more information, see the “The dimension framework” section later in this chapter.
Policy framework You can use the policy framework to define an internal control policy for an organization. The policy framework can be used to define policies for expense reports, purchase requisitions, audit control of documents, and vendor invoice payments. The policy framework provides support for override and default behavior for organizations based on their hierarchies, and supports internal management control of organizations to facilitate cost control, fraud detection, better operating efficiency, and better performance in general. For more information, see the “Using the Policy Framework” white paper at http://technet.microsoft.com/en-us/library/hh272869.aspx.
Extensible data security The extensible data security framework provides capabilities to secure data based on any condition. Security access to organizations can be defined based on hierarchies. For more information, see Chapter 11, “Security, licensing, and configuration.”
The organization model framework is also used in the following application modules:
Procurement and sourcing The lines of a purchase requisition are created for a buying legal entity, and they are received by an operating unit, such as a cost center or a department. The organization model framework supports various scenarios by allowing the viewing or creation of purchase requisitions for any buying legal entities and receiving operating units in which you have access to create purchase requisitions.
Human resources In human resources, workers hold employment contracts in a legal entity and have a position in a department. All transaction scenarios in human resources use these concepts to view and modify data.
Travel and expense Expense reports and expense line items are associated with a legal entity to which the expense line item should be charged from a statutory perspective, and they also are associated with an operating unit for internal reporting.
Modeling your own functional scenarios
You can use the organization model framework to model your own scenarios. For example, a common scenario for data security is to filter application data based on a user’s roles and membership in internal organizations. For instance, organizations might seek to limit an individual account manager’s access to specific sales orders based on geography, allowing her to view only the sales orders that originate in her region.
You can set up a new scenario or customize an existing scenario by taking the following high-level steps:
1. Define or change the data model.
2. Create a new table with the SaveDataPerCompany property set to No. If you are working with existing tables that are marked per-company, change the value of the SaveDataPerCompany property from Yes to No.
3. Reference organizations as foreign keys (FKs) on the table. It might be necessary to reference an operating unit and a legal entity if the legal entity cannot be established through legal entity or operating unit organization hierarchies.
4. If the table includes redundant data in the Legal Entity field, set up hierarchical constraints between legal entities and operating units to maintain data consistency.
5. Build a new form (for example, a list page) for the scenarios, or change the existing user experience to view or maintain data. You can use custom filters to make it possible for users to view and maintain data across organizations.
6. Apply default organizations on the table in financial dimensions by including them in account structures.
7. Create extensible data security policies that are based on the organizations that the user belongs to or has access to.
8. Use the policy framework to set up policies to apply when users access data in the scenario.
Extending the organization model framework
You can extend the organization model framework by creating a custom type of operating unit or a custom purpose, or by extending the hierarchy designer, a tool that is included with AX 2012.
Creating a custom operating unit type
A core extensibility scenario is to extend the organization model to accommodate specific vertical industry requirements. For example, branches, schools, and school districts are essentially organization concepts, and you can model them as new types of operating units.
Suppose that you want to create an operating unit called Branch. To do so, you would follow these steps:
1. Create a new base enum value for the new operating unit type.
2. Create a view.
3. Create a menu item for the new operating unit.
The following sections describe these steps in more detail.
Create a new base enum value
Define a new base enum value for the OMOperatingUnitType enum that corresponds to the new type of operating unit:
1. In the Application Object Tree (AOT), navigate to Data DictionaryBase EnumsOMOperatingUnitType.
2. Right-click the OMOperatingUnitType enum, click New Element, and then add an element named Branch.
3. In the Properties window for the new element, set both the Name and Label properties to Branch. Change the default EnumValue property to an integer value that will prevent clashes between your new enum and future enums added by the Microsoft Dynamics AX team.
Create a view
Define a view, DimAttributeBranchView, that is similar to views created for other types of operating units. For example, the DimAttributeOMBusinessUnit view was created for business units. The DimAttributeOMBusinessUnit view contains the fields that allow the OMOperatingUnit table to be used as a financial dimension for all business units specified.
1. In the AOT, navigate to the Data DictionaryViews node, and then locate DimAttributeOMBusinessUnit.
2. Duplicate DimAttributeOMBusinessUnit: Right-click the DimAttributeOMBusinessUnit node, and then click Duplicate. The AOT will create a node called CopyOfDimAttributeOMBusinessUnit.
3. In the Properties window for the newly created view, set the properties as shown in the following table:
4. Under the new DimAttributeBranchView view, locate the OMOperatingUnitTypeOMBusinessUnit range. The range is under the MetadataData SourcesBackingEntity(OMOperatingUnit)Ranges node.
5. In the Properties window for the OMOperatingUnitTypeOMBusinessUnit range, set the properties as shown in the following table:
Create a menu item
Finally, create a menu item for the new operating unit type as follows:
1. Under Menu ItemDisplay, create a menu item named BranchMenuItem.
2. In the Properties window for BranchMenuItem, set the following properties:
The new operating unit type will now appear in the list of operating unit types that are available when a system administrator creates a new operating unit.
Creating a custom purpose
You can extend the AX 2012 organization model to create a custom purpose. A purpose defines how the organization hierarchy is used in application scenarios.
Suppose you want to create a new purpose called Sales. To do so, you would follow these steps:
1. Create a new base enum value for the new purpose.
2. Create a method to add the new purpose, and then call that method to add the purpose to the HierarchyPurposeTable table.
The following sections describe these steps in more detail.
Create a new base enum value
First, create a new base enum value for the new purpose. To do so, you follow these steps:
1. In the AOT, navigate to Data DictionaryBase EnumsHierarchyPurpose.
2. Right-click the HierarchyPurpose enum, click New Element, and then add an element named Sales.
3. In the Properties window for the new element, set the Name and Label properties to Sales. Change the default EnumValue to an integer value that will prevent clashes between your new enum and future enums that are added by Microsoft or independent software vendors (ISVs).
Create and call a method to add the new purpose
Next, create the method to add the new purpose, and then call the method to add it to the table.
1. In the Classes node in the AOT, locate OMHierarchyPurposeTableClass.
2. Duplicate the addSecurityPurpose method: Right-click the addSecurityPurpose node, and then click Duplicate. The AOT will create a method called CopyOfaddSecurityPurpose.
3. Replace the code for the CopyOfaddSecurityPurpose method with the following code. This code renames the method:
private static void addSalesPurpose()
{
OMHierPurposeOrgTypeMap omHPOTP;
select RecId from omHPOTP
where omHPOTP.HierarchyPurpose == HierarchyPurpose::Sales;
if (omHPOTP.RecId <= 0)
{
omHPOTP.clear();
omHPOTP.HierarchyPurpose = HierarchyPurpose::Sales;
omHPOTP.OperatingUnitType = OMOperatingUnitType::OMAnyOU;
omHPOTP.IsLegalEntityAllowed = NoYes::No;
omHPOTP.write();
omHPOTP.clear();
omHPOTP.HierarchyPurpose = HierarchyPurpose::Sales;
omHPOTP.OperatingUnitType = 0;
omHPOTP.IsLegalEntityAllowed = NoYes::Yes;
omHPOTP.write();
}
}
The preceding code is similar to the code in most of the methods of the OMHierarchyPurposeTableClass class. The code was changed only in the places where the HierarchyPurpose enum values are referenced. In the code, you can see three occurrences of HierarchyPurpose::Sales.
4. In the OMHierarchyPurposeTableClass class, update the populateHierarchyPurposeTable method to call the new method that you created, by adding the following line of code:
OMHierarchyPurposeTableClass::addSalesPurpose();
The following code shows the modification to the populateHierarchyPurposeTable method:
public static void populateHierarchyPurposeTable()
{
OMHierPurposeOrgTypeMap omHPOTP;
if (omHPOTP.RecId <= 0)
{
ttsbegin;
OMHierarchyPurposeTableClass::AddOrganizationChartPurpose();
OMHierarchyPurposeTableClass::AddInvoiceControlPurpose();
OMHierarchyPurposeTableClass::AddExpenseControlPurpose();
OMHierarchyPurposeTableClass::AddPurchaseControlPurpose();
OMHierarchyPurposeTableClass::AddSigningLimitsPurpose();
OMHierarchyPurposeTableClass::AddAuditInternalControlPurpose();
OMHierarchyPurposeTableClass::AddCentralizedPaymentPurpose();
OMHierarchyPurposeTableClass::addSecurityPurpose();
//Add the following line.
OMHierarchyPurposeTableClass::addSalesPurpose();
ttscommit;
}
}
After you complete these steps, the new purpose will appear under Organization Administration > Setup > Organization > Organization Hierarchy Purposes.
Extending the hierarchy designer
System administrators can view or modify organizational hierarchies by using the hierarchy designer. This form is available through Organization Administration > Setup > Organization > Organization Hierarchies.
Developers have a few options for extending the hierarchy designer. The hierarchy designer control can be customized for four parameters of the organization nodes within the hierarchy: border color, node image, top gradient color, and bottom gradient color. For more information, download the “Implementing and Extending the Organization Model” white paper from http://technet.microsoft.com/en-us/library/hh292602.aspx.
The product model framework
AX 2012 offers a flexible product data management framework, supporting both centralized and legal-entity–specific management of information about a product, which is defined as an item or a service that results from an economic activity.
How the product model framework works
In the product model, product information is centralized around the concept of a Product, which represents information that is shared across the organizational structure, and the concept of a Released Product, which controls information that is specific to a legal entity. Figure 19-2 shows the conceptual domain model of the product model framework.
Product types and subtypes
A Product can be an Item—which represents a physical entity for which inventory levels can be tracked, like finished goods or raw components—or a Service—modeling a nonphysical entity for which inventory levels are not tracked, like consulting services. A product can be divided further into additional subtypes: a Distinct Product that is uniquely identifiable and can be used in economic activities, or a Product Master. A product master is a standard or functional product representation that serves as a basis for configuring distinct Product Variants. In this case, a product variant is a uniquely identifiable product that can be used in economic activities. However, because all product variants are bound to a product master, they share a significant part of the information defined for the product master.
Consider a manufacturing company named Contoso that sells different models of bicycles, which come in different colors and sizes, and accessories such as bicycle lights. In this scenario, every bicycle model can be modeled as a product master, with each color and size combination defining a product variant. Lights do not come in various configurations, so they can be modeled as distinct products.
Product dimensions
A product variant is defined by using product dimensions, which are active for a specified product master. Product dimensions are characteristics that uniquely identify a product. AX 2012 includes four product dimensions: Configuration, Size, Color, and Style. (You can rename them.) A Product Dimension Group, which is required for a product master, encompasses the information about the product dimensions that are active and can be used for controlling which product dimensions should be considered in the price calculation in trade agreements. Because product dimensions define unique products, a product dimension group must be assigned to the product master and is shared across the organizational structure.
For example, Contoso sells two bicycle models. Each model is available in three sizes (small, medium, and large) and three colors (black, red, and white). Contoso can model this assortment by creating a product dimension group named Bicycles, with Size and Color as the active dimensions, and assigning that product dimension group to the two product masters that represent the two bicycle models. Because Contoso also sells helmets, which come in one color but in different sizes, Contoso can create a second product dimension Group called Helmets that has only one active dimension: Size.
Storage and tracking dimensions
Besides product dimensions, there are two more types of dimensions: Storage and Tracking. The Storage Dimension Group defines the level of detail used to identify the physical location of goods, with the possible dimensions being Site, Warehouse, Location, and Pallet. The Tracking Dimension Group defines how specific instances of the same Released Product are tracked, with Batch and Serial Number being available. These dimension groups also define policies regarding how specific dimension values affect business activities. Because these policies might differ in different legal entities, different storage and tracking dimensions can be assigned to the same product in different legal entities.
For example, Contoso might be required by law to track batch numbers of bicycle brakes in certain countries so that an entire batch can be recalled easily in case a widespread defect is discovered that causes a safety hazard. This requirement does not apply in other countries, so Contoso might choose not to track brake batches in these countries.
Released products
All of the information described so far applies to the concept of a product, representing the information that is shared across the entire organizational structure. But this information is not sufficient for a legal entity to be able to use a product. To enable a legal entity to use a product, the product, together with the relevant product variants, has to be released to the legal entity. On a released product, you can define various policies that control how these products can be used within that legal entity. These policies include storage and tracking dimension groups (unless they were defined on the shared product information), Inventory Model Group and Item Group, and various inventory and costing policies that apply to the product. After these policies are defined, the product can be used for transactions within the legal entity.
Product availability within legal entities can be controlled both on the product and the product variant level. For example, a specific bicycle model can be released only to Contoso US because the company wants to sell it only in that market. Another model can be released to Contoso US in only black and red because the company has decided that it’s not worth investing in white bikes in the United States.
Additional product information
Besides the required information, additional details can be provided for a product, either to provide a reference or to control the interaction with other system components. For example, you might define Product Translations for a product to control the product name or descriptions that are displayed in various contexts. Similarly, you can attach Images to provide a graphical representation of the product. An example of the information used to control other components is the Default Order Type, which a legal entity can set to decide the type of order that is generated to cover the demand for a particular product. For example, Contoso Italy, which owns a clothing production facility, could set the Default Order Type for cycling clothes to Production, whereas bicycles, which are bought from external vendors, would have the default order type set to Purchase.
Product Attributes and Categories
AX 2012 introduces the concept of product attributes. User-defined product attributes can be associated with a product category to describe characteristics that are common to all products within that category. Product attributes can be of various data types. Each attribute might have a default value within that category. When a product is added to a category, the product inherits all product attributes within that category along with their default values. However, the value of a product attribute can be changed for each product.
For example, a company in the food industry has a product attribute called Fat that is associated with the procurement category for milk products. The default value is 1%. The category contains the product Light-milk, which inherits the default value of 1% from the category. The category also contains the product Fat-milk, which also inherits the Fat value. However, the value for Fat-milk has been overwritten with a value of 3%. A purchasing clerk could search all products that match specific criteria—for example, to find all milk products with a Fat value between 1% and 3%.
Note
Product attributes primarily provide an additional product description that can be used for search functions. You cannot use product attributes to track inventory. The system uses only Product, Tracking, and Storage dimensions to track physical and financial inventory.
Variant configuration technology
The product master definition has a mandatory variant configuration technology, which you use to define the configuration strategy of the product master. The configuration strategy identifies the method used to create a new product variant to meet a customer’s needs. As a result of product configuration, a new product variant is created in the shared product repository and automatically released to the legal entity when product configuration takes place.
For example, in a configure-to-order environment, a manufacturing company provides several predefined product models with different constraints. If the existing models do not meet the expectations of a specific customer, the system creates a new unique product variant to represent the variation that the customer wants.
Constraint-based configuration technology
With the new Product Configuration module in AX 2012, you can describe a shared product model in terms of product structure, product components, attributes, and constraints. After you create a product model, you can associate it with the product master definition, which follows a constraint-based configuration strategy. This advanced configuration technology allows modeling of complex product structures.
For example, a company produces a home theater system that contains 10 components with predefined constraints based on various component characteristics (attributes). During sales order entry, the system exposes a rich product configuration experience that guides the user through the configuration process to successfully create the correct product variant.
Dimension-based configuration technology
In AX 2012, you can set up the configuration group and configuration rules as part of the general inventory management setup. This information can be used in a bill of material (BOM) definition. You can use the configuration rules to predefine the product configurations to use as part of a specific BOM configuration.
For example, a manufacturing company produces gaming devices in several configurations. To produce these products, the company uses a BOM, which contains a raw component that comes in different configurations. With configuration groups and configuration rules, the system can enforce that only a specific raw component configuration can be included in a specific configuration of a gaming device.
This functionality allows a lightweight approach to configuring products on the order line that have relatively simple BOM structures.
Predefined variant configuration technology
Predefining product variants is the simplest configuration strategy in AX 2012. The different product variants can be created automatically or manually based on the product dimension values, which are associated with the product master.
For example, a product master might have active dimensions of Size and Color. Every time a user adds a new color or size value, the system automatically creates all possible product variants. This functionality is especially valuable in the retail industry, where companies offer a wide range of products based on different styles, colors, and sizes.
When to use the product model framework
You can extend the product model framework to align the stored product information and product behavior with organizational master data management practices. These practices might include processes such as data governance, centralized master data control, or a product-specific policy. Such a policy can affect the product life cycle or specific behavior within business processes, such as procurement, production, and reserve logistics.
For example, a multinational retail organization might require a process for defining an organization-wide policy such as product sales price. After the new sales price is set, that price should be used in all retail stores.
Extending the product model framework
In AX 2012, you can customize the product model by extending tables and classes with the prefix EcoRes. For example, you could begin to implement the sales price policy in the previous example by adding a new field to the EcoResProduct table to represent the sales price in the currency assigned as the primary currency in the legal entity’s ledger configuration. This field is inherited automatically by all product subtypes such as distinct product, product master, and product variant, which means that you can define a specific sales price for product variations. After the policy has been implemented, you need to expose the information in the user interface of the Product Information Management module to allow users to manage sales prices.
The next step is to adjust the product release process to propagate the sales price to released products. You can do this by modifying the EcoResProductReleaseManager class, which is responsible for the creation of released products. Specifically, you need to set a proper value in the InventTableModule table, which stores the default sales, purchase, and production prices for the released product within a legal entity.
If the shared product sales price changes, the new sales price value should be propagated to all legal entities in which the product has been released. One of the ways to achieve this is to add such logic to the update method of the EcoResProduct table.
The potential conceptual model is illustrated in Figure 19-3.
For more information about the product model framework, download the “Implementing the Item-Product Data Management Framework” white paper from http://technet.microsoft.com/EN-US/library/hh272877.
The operations resource framework
Designing a manufacturing process within an enterprise resource planning (ERP) system has traditionally been done by describing what activity should be performed and who should do it. This requires the process engineer to know not only how a product is built, but also which resources are available for building the product. In AX 2012, a new model has been put in place that allows decoupling of the process from the resources, so that the process can be described without having to reference specific resources.
How the operations resource framework works
The primary entity of the operations resource model is the Resource, which is defined as anything that is used for the creation, production, or delivery of an item or service other than the materials that are consumed in the process. There are multiple types of resources: Tool, Machine, Human Resource, Location, and Vendor.
A resource can be a member of a Resource Group, and the Resource Group Membership can change over time. You can think of a resource group as a vehicle for organizing resources. A resource group is located at a particular site. A resource can be a member of only a single resource group at a time. A resource does not have to belong to a resource group, but the resource is considered for scheduling only during the period or periods that it is connected to a resource group.
Figure 19-4 shows the conceptual domain model for resources and resource groups.
Capabilities
A Capability is the ability of a resource to perform a specified activity, such as welding, pressing, or floor sweeping. A resource can be assigned one or more capabilities and can have multiple capabilities on the same date. For each assignment, you can set a priority and level at which the capability can be performed—for example, stamping with four tons of pressure.
Figure 19-5 shows the conceptual domain model for resources and capabilities.
A capability can be assigned to any resource regardless of its type. If a resource is of the type Human Resource, which is associated with a worker, skills, courses, certificates, and title information from the Human Resources module, you can use that information in addition to the capability to define the competencies of the resource.
Activities and requirements
An Activity is a common abstraction of the unit of work to be performed by one or more resources. The activity entity in itself is not visible to the user but is used internally for a common representation of the following business entities: Hour Forecast (Project), Production Route, Operation Relation, Product Model Operation Relation, and Product Builder Operation Relation.
Figure 19-6 shows the conceptual domain model for an activity.
Each activity can have a set of Activity Requirements that specifies how many resources are needed for the activity and what abilities the resources must have to participate in the activity. Multiple activity requirements can be contained in an Activity Requirement Set. For a resource to be applicable to an activity, the resource must meet all of the requirements in the activity requirement set. For each activity requirement, you can specify whether the requirement should be considered when operations scheduling or job scheduling is performed. Figure 19-7 shows the conceptual domain model for activities, activity requirements sets, and activity requirements.
Identifying applicable resources
Finding the resources that are applicable for an activity requires that at least the following information is known:
The as-of date by which to perform the search. Because resource and membership information can vary over time, an as-of date must be provided.
The site context. In most cases, the site will be a limiting factor because the resources must be a member of a resource group on the site where the production takes place.
The scheduling method. An activity requirement can be applicable for either operations scheduling, job scheduling, or both.
Conceptually, identifying an applicable resource is easy; it is simply a matter of traversing through all resources while checking to determine whether the skills, capabilities, resource type, and so on, of each resource match the ones stated in the requirements and ensuring that the Resource is not associated with a resource group that is marked as a lean work cell.
In code, you can find applicable resources for an activity by using one of the two main application programming interfaces (APIs) offered for the activity requirement set:
applicableResourcesList Returns the IDs of all applicable resources in a simple list
applicableResourcesQuery Creates a query object with the WrkCtrTable table as the primary data source
When the activity has been planned by the scheduling engine, the chosen resource (or resources) can be found through querying the capacity reservations.
When to use the operations resource framework
You can use the operations resource framework for any activity that requires one or more resources. The framework provides good integration with the scheduling engine, which can perform the resource selection and allocate time according to the requirements and priorities.
Extending the operations resource framework
You can extend the operations resource framework in at least two ways: by adding a new class of activity and by adding a new class of activity requirement. The following sections provide details about the integration points and describe some of the considerations that must be taken.
Adding a new class of activity
To add a new class of activity, you first need a primary table (called X in the following example) that contains the activity definition, including the task to be performed, the duration, links to other activities, and so on. To connect this table to the generic activity, create a new WrkCtrXActivity table with a 0-1 relation to the WrkCtrActivity table and a 1-1 relation to the X table. Having this data structure in place makes it possible to create a form where users can fill in the activity requirements for your X table and navigate further to see the resulting applicable resources. The ProdRoute form is a good example of how such a form can be constructed and the logic that is needed to control the WrkCtrActivityRequirement and related data sources.
If the activity must be scheduled, this can be done by using the same resource scheduling engine that is used for master planning, production orders, and projects. The main class is WrkCtrScheduler. Each type of activity has its own derivative class, such as WrkCtrScheduler_Proj, which has information about how that type of activity is handled. At a minimum, the following methods must be implemented:
loadData Feeds the engine with information about which activities should be scheduled, the duration for applicable resources, dependencies, links between activities, and so on.
saveData Iterates through the results from the core engine, saving the from and to time on the activity and creating capacity reservations in the WrkCtrCapRes table. It is recommended that you add a new value to the WrkCtrCapRefType enum and use this value when saving the capacity reservations. Doing so makes it easier to trace who owns the reservation.
Adding a new class of activity requirement
If information exists that is related either directly to an operations resource or to the vendor that is associated with the resource, and that information determines the resource’s ability to perform an activity, you can incorporate this information into the resource selection process.
If the information related to the resource is stored in a table named Y, first create a new value in the WrkCtrActivityRequirementType enumeration to represent the Y entity. Next, add a new table named WrkCtrActivityYRequirement that contains a foreign key to the WrkCtrActivity table and the Y table. Because much of the logic surrounding resource requirements relies on reflection, the new table must implement a certain set of methods. Use the WrkCtrActivityPersonTitleRequirement table as an example of the table methods needed.
After the requirement table is in place, the application must be modified in several places to take the new table into consideration. The best way to ensure that the new requirement is implemented throughout the application is to use cross-references for one of the existing tables, such as WrkCtrActivityPersonTitleRequirement, and then add the new table in a similar way.
For performance reasons, the matching of the resource requirements for an activity against the actual abilities of a resource is done by the core scheduling engine, which converts capabilities, skills, certificates, and so on to a common property that can be compared against the requirements by simple string matching. This transformation is performed by the computeResourceCapabilities and computeResourceGroupCapabilities methods of the WrkCtrSchedulingInteropDataProvider class, which also must take into account information from the Y table. Consider carefully whether you want the new requirement to be available both for job and operation scheduling. If the requirement must be available for operation scheduling, the used capacity for the group with regard to the Y property must be saved and maintained, along with the capacity reservations, to avoid overbooking. This capability comes at a high performance cost during scheduling.
MorphX model element prefixes for the operations resource framework
All elements that concern the operations resource model are prefixed with WrkCtr*. Most are named similarly to the conceptual names—except for the resource entity, which for legacy reasons is stored in the WrkCtrTable table.
For more information about the operations resource model framework, see the following Core Concepts documents on Microsoft Dynamics InformationSource (http://informationsource.dynamics.com):
Allocating resources based on resource requirements
Operations scheduling based on capabilities
To access these documents, sign in to InformationSource, click Library, and then type the document title in the Search box.
The dimension framework
The dimension framework provides a method for tracking additional pieces of information such as department, cost center, or purpose for documents throughout the application. That information can be used in accounting to categorize information.
How the dimension framework works
A Dimension Attribute is a type of information that is tracked by the dimension framework. The domain of values for a dimension attribute is defined by the instances of the business entity that exist for the backing business entity type. For instance, the OMOperatingUnit table can provide the list of values for an organization unit dimension. Dimension attributes can be placed in a Dimension Hierarchy to indicate ordering. For example, one specialization of a dimension hierarchy is an Account Structure. Dimension attributes can be grouped into a Dimension Attribute Set, which is used in some Setup Data to specify the dimension attributes that apply in particular situations—for example, the check box next to each dimension on the LedgerAllocation form.
Figure 19-8 shows the conceptual domain model for the dimension framework.
There are four primary storage patterns for exposing and tracking dimension information:
Ledger Dimensions Ordered sets of Dimension Attribute Values that are constrained by an account structure and additional accounting rules—for example, Sales-11005-NorthAmerica-Xbox-70004. This pattern is normally used on financial data such as journal lines.
Default Dimensions Unordered, unconstrained sets of dimension attribute values. For example, a record in the CustTable table might be set to SalesRegion=NorthAmerica. This value would then be defaulted into the Ledger Dimension when the customer record was used on a sales order. When Default Dimensions are shown on a form, all dimensions that are in use by the chart of accounts for the current legal entity are shown.
Dimension Attribute Sets Unordered sets of dimension attributes that have an enumeration value associated with each dimension attribute. For example, in the allocation process, the user can mark which dimension attributes should default from the original transaction and which should take on a specific value. This pattern is used infrequently.
Dimension Sets Ordered sets of dimension values similar to Ledger Dimensions, but without the requirement that they contain a main account. Dimension sets are used primarily for reporting and balance tracking. For example, to view the trial balance list page by main account and department, the user would create a dimension set containing those two dimensions.
These four primary patterns are further specialized into dozens of specific uses. Two of the more common specializations are as follows:
The Default Account pattern is a specialization of the Ledger Dimension storage pattern. An instance of the Default Account pattern is stored like a standard ledger account but only contains a value for the main account dimension attribute. An example of when this pattern might be used is when profiles are posted, to specify which main account is used when a Ledger Dimension is created by financial processes.
The Dynamic Account pattern is also a specialization of the Ledger Dimension storage pattern. This pattern is used on journals where an Account Type field is available. When Account Type is set to Ledger, it behaves like a standard Ledger Dimension account. When the account type is set to something else, it acts as a lookup. For example, if it is set to Customer, it acts as a customer lookup. When a nonledger type is used, a predefined hidden dimension attribute is used to signify customer, vendor, item, or whatever type is used.
In addition, a variety of budgeting patterns mirror the accounting patterns.
Constraining combinations of values
You can constrain the combinations of values that are valid in Ledger Dimensions in two ways.
If constraints are set up in the tree in the Configure Account Structure form (General Ledger > Setup > Financial Dimensions > Configure Account Structures), these constraints are stored in the DimensionConstraintNode and DimensionConstraintNodeCriteria tables. Because the structure of the data in these tables is highly complex, it is much easier to use the DimensionValidation::validateByTree method to perform validation rather than to read the constraint node tables directly. The validateByTree method validates that a Ledger Dimension matches the constraints specified in these tables.
The other method of constraining values is to click the Relationships button on the Action Pane of the Configure Account Structures form, and then use the Select Relationships form to specify the relationships that you want to apply to the account structure. The Select Relationships form shows all of the organization model hierarchies that contain organization model types used as the backing entities for Dimension Attributes in the current hierarchy. For example, if an account structure contains departments and cost centers, and an organization model exists that relates departments to cost centers, that information appears in this form. The information will appear twice, once in the standard order, and once with party A and party B reversed. This allows a system administrator to specify whether departments must be parents or children of a specified cost center to be valid. These organization model constraints are similarly applied when you use the DimensionValidation methods.
Creating values
You can create Ledger Dimensions programmatically in two ways. To explicitly create them, use the DimensionStorage class. You can use this class to add multiple hierarchies and values. When you call the save method, it attempts to find an existing combination. If no combination is found, a new one is created. Ledger Dimensions are immutable, and only one exists for any particular combination. So if the same account is used twice, this method guarantees that only one instance is created in the database.
When working with existing default accounts and ledger dimensions, you can use the DimensionDefaultingService class to combine the values into new combinations. For example, the DimensionDefaultingService::serviceCreateLedgerDimension method takes a default account and one or more Default Dimensions and combines them to form a full Ledger Dimension.
Extending the dimension framework
The most common customization of the dimension framework is to add a new backing entity type. AX 2012 includes approximately 30 backing entities. The only requirement for adding a backing entity type is that the entity must have a natural key that consists of a unique, single-part string with a length of 30 characters or less.
To add a new backing entity type, create a view that meets the following criteria, to wrap the entity:
The view name must be DimAttribute<entityname>—for example, DimAttributeCustTable.
The view must contain a root data source named BackingEntity, which is backed by the table containing the surrogate key and the natural key.
The view can optionally contain additional related data sources to handle inheritance or relational associations to provide additional fields, such as a name from the DirPartyTable table.
The view must contain the following fields named exactly as follows:
• Key Must be the surrogate key field of the backing entity—for example, an Int64 RecId field
• Value Must be the natural key field of the backing entity—for example, a str30 AccountNum field
• Name Must point to the additional description for the entity—for example, a str60 description field
If the view meets these criteria, the entity will automatically become available as a backing entity type.
Because the list of backing entity types are cached both on the client and on the server, a new type does not appear in the list of existing entities until a call to clear the caches is performed, or until both the client and server are restarted. To clear the caches and have the new entity type appear immediately, use the options on the Tools > Caches menu in the Development Workspace.
Querying data
Dimension Attributes are data and can be added or removed by the user. This means that specific dimensions should not be referenced directly in code because there is no guarantee that a particular dimension exists. Instead, treat dimension references as configurable data. The one exception to this rule is the main account dimension attribute. All installations are guaranteed to have exactly one dimension attribute that is backed by main account. To retrieve this dimension attribute, use the DimensionAttribute::getMainAccountDimensionAttribute method.
The technique used to query dimension information depends on the pattern being used. In the case of a Ledger Dimension, you can use either the full combination or the constituent parts. To get the full concatenated combination, create a join to the DimensionAttributeValueCombination table, as shown in the following example:
GeneralJournalAccountEntry gjae;
DimensionAttributeValueCombination davc;
select gjae join DisplayValue from davc where
davc.RecId == gjae.LedgerDimension;
To get a constituent part of the Ledger Dimension, you can use the DimensionAttributeLevelValueView abstraction to abstract some of the complexity of the dimension model:
GeneralJournalAccountEntry gjae;
DimensionAttributeLevelValueView dalvv;
DimensionAttribute department;
department = DimensionAttribute::findByName('Department'),
select gjae join DisplayValue from dalvv where
dalvv.ValueCombinationRecId == gjae.LedgerDimension &&
dalvv.DimensionAttribute == department.RecId;
The main account dimension attribute is a special case. This dimension attribute has been denormalized to the DimensionAttributeValueCombination table to optimize the performance of queries for this value, because it is the most often used:
GeneralJournalAccountEntry gjae;
DimensionAttributeValueCombination davc;
MainAccount mainAccount;
select gjae
join MainAccount from davc where
davc.RecId == gjae.LedgerDimension
join Name from mainAccount where
mainAccount.RecId == davc.MainAccount;
You query Default Dimensions in a similar way to Ledger Dimensions; however, Default Dimensions do not have a concatenated representation because they are unordered sets. The DimensionAttributeValueSetItemView abstraction joins the DimensionAttributeValueSetItem and DimensionAttributeValue tables to simplify queries:
CustTable custTable;
DimensionAttributeValueSetItemView davsiv;
DimensionAttribute department;
department = DimensionAttribute::findByName('Department'),
select custTable
join DisplayValue from davsiv where
davsiv.DimensionAttributeValueSet == custTable.DefaultDimension &&
davsiv.DimensionAttribute == department.RecId;
Physical table references
Table 19-2 maps the concept names in the conceptual domain model to the names of physical table elements that realize these concepts in the application where the names are not the same.
For more information about the dimension framework, download the following white papers:
“Securing Data by Dimension Value by Using Extensible Data Security (XDS)” at http://www.microsoft.com/download/en/details.aspx?id=26921
“Implementing the Account and Financial Dimensions Framework” at http://technet.microsoft.com/en-us/library/hh272858.aspx
The accounting framework
The accounting framework uses policies and rules to derive accounting requirements for amounts and business events that are documented on source document lines. These policies and rules are abstracted as five categories:
Accounting Policy Used to determine whether accounting applies for a business event–monetary amount combination
Main Account Derivation Rule Used to determine main account values
Main Account Dimension List Provider Used to provide a list of main accounts and side (debit or credit) combinations
Dimension Derivation Rule Used to determine dimension values
Accounting Journalization Rule Used to determine which main account dimension list provider should be used and to determine the journalization parameters that should be used, such as the posting type
The accounting framework is also responsible for transferring Subledger Journal entries to the General Journal. Rules for subledger journal transfers are specified by legal entity and source document type, and they determine when the subledger journal is transferred to the general journal and whether summarization occurs on transfer.
How the accounting framework works
The Accounting Distribution process creates at least one Accounting Event. An accounting event groups a set of distributions based on their accounting date. When a Source Document header is submitted to a Processor for processing and the processor transitions the document from an In Process state to a Completed state, the Journalization Processor (journalizer) is called. The journalizer processes all accounting events associated with the document that are in a started process state, and transitions them to a journalized process state. An Accounting Policy determines whether accounting is required for amounts and business events that are documented on a Source Document Line. If the accounting policy specifies that accounting is required, the journalizer uses journalization rules, main account derivation rules, dimension derivation rules, and the main account dimension list provider to determine the main account–dimension combinations to use when creating balanced subledger journal entries.
Figure 19-9 shows the conceptual domain model for the accounting framework.
Subledger Journal Transfer Rules, shown in Figure 19-10, specify when the transfer should occur (that is, whether it should be synchronous, asynchronous, or a scheduled batch transfer) and whether amounts for the same main account–dimension combination should be summarized when they are transferred to the general journal.
When to use the accounting framework
You can extend the accounting framework to create concrete implementations of accounting policy, journalization, main account derivation, main account dimension list providers, and dimension derivation rules to support new source document implementations. In AX 2012, the accounting framework was extended to create concrete accounting policies, journalization, main account derivation, and dimension derivation rules used to generate subledger journal entries on the purchase requisition, purchase order, product receipt, vendor invoice, travel requisition, expense report, and free-text invoice source documents.
Extensions to the accounting framework
The AX 2012 purchase requisition (PurReqSourceDocument prefix) is an example of an extension of the source document framework components. The AccPolicyCommitFundsExpensedProd accounting policy and AccJourRuleCommitFundsForExpProdExtPrice dimension derivation rule are extensions to the accounting framework that specify the accounting requirements for the purchase requisition document. These are examples of extensions to the accounting framework.
Accounting framework process states
The process states for the accounting process are illustrated in Figure 19-11.
Each process state performs an action and updates the status of the accounting event that is being processed. Table 19-3 describes the process states.
MorphX model element prefixes for the accounting framework
Table 19-4 maps the concept names in the conceptual domain model to the prefixes added to the names of MorphX model elements that realize these concepts in the application.
The source document framework
A Source Document is an original record that documents the occurrence of one or more Business Events in an accounting system. Concrete Source Documents, such as purchase orders, product receipts, and vendor invoices, are entered into an accounting system that records, classifies, tracks, and reports on the quantity and value of economic resources that are exchanged or committed for exchange when activities identified by Business Events such as purchase, product receipt, and payment request are performed.
How the source document framework works
The source document framework generates a projection of a concrete source document for a process that transitions the source document status to reflect the state of the process. Figure 19-12 shows the domain model for the source document framework.
AX 2012 submits a Source Document header or line record to a Processor for processing when a user confirms that the documentation requirements of business events and internal process controls have been met. A processor is a state machine that transitions the processing of the source document and its lines from one Process State to another. The processor creates a process state object that corresponds to the status of the Source Document or the status of the source document Line Item and then directs the process state to transition the process to the next state.
A process state first constructs a Concrete Source Document or a Concrete Line Item from the provided source document header or line record by using an extension factory facility. The extension factory facility uses the source document type and the table number of the concrete source document or the concrete line item provided by the header or line record to find a matching concrete source document class. A matching source document class is one that is annotated with a class attribute recognized as an Extension Attribute by the Extension Factory and that also specifies a matching source document type and table number as arguments.
A process state accesses a data projection of the concrete source document and concrete source document line item, performs an action, transitions the process to a new state, and updates the status of the process’s concrete source document or concrete line item accordingly. The data projections of the Concrete Source Document and concrete line item are defined by one or more interfaces. For example, implementing the IParty interface provides a party account number, and implementing the IProduct interface provides an item number and a production category to an accessing process state.
When to use the source document framework
You can extend the source document framework to implement concrete source documents that document business events whose financial consequences are recorded in the subledger journal. In AX 2012, the source document framework has been extended to implement the purchase requisition, purchase order, product receipt, vendor invoice, travel requisition, expense report, and free-text invoice source documents.
Extensions to the source document framework
The AX 2012 free-text invoice (CustInvoiceSourceDocument prefix) is the simplest extension of the source document framework components. Readers new to the source document framework should review this extension of the source document framework first. The concrete source document and concrete line item implement only those source document projection interfaces that are required by the accounting distribution processor and the subledger journalizing processor.
The process states for the subledger journalizing process and the accounting distribution process are illustrated in Figure 19-13. Each processing state performs an action and updates the status of the source document or source document line item that participated in the process. Table 19-5 describes the states of the subledger journalizing process and the accounting distribution process.
FIGURE 19-13 State model for the accounting distribution process and the subledger journalizing process.
MorphX model element prefixes for the source document framework
Table 19-6 maps the concept names in the conceptual domain model for the source document framework to the prefixes added to the names of MorphX model elements that realize these concepts in the application.
