Chapter 1: Number Sequences

CHAPTER 1: NUMBER SEQUENCES

Objectives
The objectives are: Describe the features of number sequences in Microsoft Dynamics AX 2012. Describe the steps for setting up and administering a number sequence. Develop new number sequences by extending the NumberSeqApplicationModule class. Use the Form Handler to create number sequences in a form.

Introduction
Number sequencing is a necessary feature in an Enterprise Resource Planning (ERP) system. Microsoft Dynamics AX uses a number sequence framework to generate alphanumeric number sequences. These sequences can be used for transaction documents such as sales orders, purchase orders, invoices, and journals; or for master data entities such as customers, vendors, and employees. The primary purpose of the number sequence framework is to provide unique, user-friendly identifiers while maintaining a continuous or non-continuous alphanumeric sequence. This course is designed to explain how developers can perform customizations using the number sequence framework. However, administrators may be interested in the "Setup and Administration of Number Sequences" topic, which describes how to configure and set up number sequences using the new number sequence administration forms.

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-1

Development IV in Microsoft Dynamics AX 2012

Overview
Microsoft Dynamics AX 2012 introduces two concepts to the number sequence framework: segment and scope. A segment, which is synonymous with parameter, is a data entity such as a legal entity, operating unit, or fiscal calendar period that can be used to define a number sequence. In the enhanced number sequence framework, a number sequence can have more than one segment. A scope is a valid combination of segments used for a specific transaction or master data entity. By using segment and scope, Microsoft Dynamics AX 2012 extends the capabilities of the number sequence framework. All segments in a scope must be related to the underlying transaction or master data entity. For example, a journal transaction will have a relationship with the segments of a legal entity and fiscal calendar period (through the transaction or posting date) that make up its scope. The scope can be used to partition the entity instances or transactions based on the segment values. In this example, a journal transaction might be partitioned into categories based on the two segments in its scope. A unique number sequence code must be created for every possible combination of legal entity and fiscal calendar period instances. For example, if there are two legal entities with IDs 10 and 20, and there are fiscal calendar periods for every calendar month in 2011, the user must define separate number sequences for each combination. An example of a scope instance is 20-Jan11. An example of a number sequence code for a journal might be JN-J-20-Jan11, in which JN represents a journal. The number sequence format, J-20-Jan11, is a string that is defined by the end-user to represent the identifier for the transactions for legal entity 20 and fiscal calendar period January 2011. The actual instance of a journal might have a generated number sequence such as J-20-Jan11-000340. (The last number in the sequence, "000340," is a system-generated number.) The concept of a number sequence reference, which is synonymous with an extended data type, is carried forward from Microsoft Dynamics AX 2009. When you create a number sequence, you must first create an extended data type (EDT) with a label-such as SalesOrderID-for the new number sequence. The label of this EDT is used as a reference. This reference is used to define a field on a document or master data entity that requires a number sequence.

Supported Scopes
Microsoft Dynamics AX 2012 will convert a subset of existing transactions and master data entities so they can use scopes such as a legal entity or global scope. This enables Microsoft Dynamics AX 2012 to ship with predefined scopes for this subset of entities. The rest of the data entities still have a default scope of DataArea (or company).

1-2

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

Microsoft Dynamics AX 2012 does not currently support an arbitrary combination of segments as a valid scope. The following are the only scopes that are currently valid in the number sequence framework: DataArea (or company) DataArea and fiscal calendar period Legal entity Operating unit Legal entity and fiscal calendar period Legal entity and operating unit

TIP: Use the Legal entity scope when the underlying table does not include the DataAreaID field and has a foreign key to the legal entity table, CompanyInfo. For example, use this scope for the number sequence for the expense report number that is in the expense report table, TrvExpTable. Although the scope is predefined for a data entity, the segments within that scope are configurable. This means if a scope consists of a legal entity and fiscal calendar period, a user can decide to configure the scope to be only a legal entity during implementation. However, there are some mandatory restrictions on scope composition. If, for example, a fiscal calendar period is selected as part of a scope, the inclusion of DataArea or legal entity is mandatory in that scope. One limitation of the new number sequence framework is that the scope must always be configured for a specific reference. You cannot define a scope based on variations in the data. For example, suppose that the regulatory requirements in France and China require you to generate a number sequence by using the legal entity and fiscal calendar period segments. However, other countries or regions might not have the same requirements. The administrator in a multinational corporation might decide that it is not necessary to include both segments for all countries or regions. However, you cannot define two different scopesone to be used in France and China that includes legal entity and fiscal calendar period segments, and another to be used in all other countries or regions that includes only the legal entity segment. You could use the framework in such a way that all countries or regions have the scope of legal entity and fiscal calendar period, but display the number sequence format based on both segments only in France and China. However, the numbers generated would still be partitioned based on both segments in all companies. A second limitation is that no references are provided out-of-the box that has a fiscal calendar period segment. Extending the framework to include a fiscal calendar period currently requires customization of existing parameters forms in specific modules. The new Number sequences setup form does support a fiscal calendar segment.

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-3

Development IV in Microsoft Dynamics AX 2012

Set Up and Administration

When an end-user creates a document such as a sales order, purchase order, or invoice, the extended data type on the document fieldsuch as SalesOrderID or InvoiceIDis passed to the number sequence framework. Additionally, information is passed for the segments such as DataArea, or a legal entity plus fiscal calendar period, depending on the scope for the reference. The framework then generates a number sequence code based on these parameters (segments), and this number sequence code is used to generate a number based on the format for the corresponding number sequence. Specifying a number sequence is now done in two steps: segment configuration and setup. With the Microsoft Dynamics AX 2012 number sequences framework, you can use multiple segments, but legacy number sequence references do not support this new capacity. Customers and partners who plan to perform customizations to enable new segments, based on the new capabilities of the framework, will have to use the Segment configuration form. This form can be used to view or modify the default configuration of segments included out of the box.

Segment Configuration
An administrator can configure the segments that are allowed for his or her requirements. For example, out of the box, the application could allow for two segments such as legal entity and fiscal calendar period. However, only the legal entity segment might be included by default. The administrator can enable both segments for their scenario by using the Segment configuration form. In Microsoft Dynamics AX 2012, most references use either DataArea (or company) or legal entity segments out of the box. There are several references for master data entities that are shared across the application and do not use segments. However, the framework allows an administrator to add segments such as the fiscal calendar period.

1-4

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

To define the segment configuration, open Organization Administration > Common > Number sequences > Segment configuration.

FIGURE 1.1 SEGMENT CONFIGURATION FORM

Most references use either Company or Legal entity scope segments. By default, references for master data entities that are shared across the application do not use scope segments. NOTE: You cannot modify scope segments for a number sequence that is currently being used. It is not sufficient to stop the use of number sequences with a scope segment that you need to modify. You must delete any number sequences that are based on the current configuration before you can modify the scope segments for a reference.

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-5

Development IV in Microsoft Dynamics AX 2012

Set Up Number Sequences
The existing number sequences can be viewed by using the Number sequences list page. The navigation path to this page is Organization administration > Common > Number sequences > Number sequences. The following figure shows the Number sequences list page.

FIGURE 1.2 NUMBER SEQUENCES LIST PAGE

You can use the Area, Reference, and Company drop-down lists to filter the data that is displayed in the form. TIP: The Company filter field only appears after you have selected an Area and a Reference. You can set up all required number sequences at the same time by using the Set up number sequences wizard by clicking Generate in the New group of the Action Pane, or you can create or modify individual number sequences by using the Number sequences form.

1-6

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

Procedure: Set Up Number Sequences by Using the Wizard
You can use the Set up number sequences wizard to automatically create number sequences. The wizard generates number sequences for all references in all organizations for which number sequences are not yet defined. You cannot use the wizard to generate number sequences for a subset of the areas or references that require number sequences. You cannot use the wizard to modify existing number sequences. To use the wizard to set up number sequences, follow these steps. Open Organization administration > Common > Number sequences > Number sequences. Then click Generate in the New group of the Action Pane. On the Welcome page, click Next >. The Setup page is displayed. On this page, you can modify the Identification code, the Lowest value, and the Highest value. Additionally, you can indicate whether the number sequence must be Continuous.

IMPORTANT: Do not select the Continuous option if you must preallocate numbers for the number sequence. To add a scope segment to the format of a number sequence, select the format in the list, and then click Include scope in format. To remove a scope segment from the format of a number sequence, select the format in the list, and then click Remove scope from format. To exclude a number sequence from automatic generation, select the number sequence in the list, and then click Delete. Click Next >. On the Completed page, verify the information, and then click Finish.

NOTE: In the Hyper-V training environment, all number sequences are set up. Therefore, you cannot run the wizard unless you first delete some number sequences.

Procedure: Set Up Number Sequences Manually

You can use the Number sequences page to create or modify selected number sequences. To manually create number sequences, follow these steps. Click Organization administration > Common > Number sequences > Number sequences. Click Number sequence in the New group of the Action Pane

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-7

Development IV in Microsoft Dynamics AX 2012

On the Identification FastTab, enter an identification code and a name for the number sequence. On the Scope parameters FastTab, select a scope for the number sequence and select scope values. The scope defines which organizations use the number sequence. Additionally, number sequences that have a scope other than Shared can have segments that correspond to their scope. For example, a number sequence with a scope of Legal entity can have a legal entity segment. By default, the following scopes are available: a. Shared: A single number sequence is used for all organizations. b. Company: A separate number sequence is used for each company. TIP: Use the Company scope when the underlying table includes the DataAreaId field. For example, use this scope for the number sequence for the customer account number in the customer table, CustTable. c. Legal entity: A separate number sequence is used for each legal entity. TIP: Use the Legal entity scope when the underlying table does not include the DataAreaId field and has a foreign key to the legal entity table, CompanyInfo. For example, use this scope for the number sequence for the expense report number that is in the expense report table, TrvExpTable. d. Operating unit - A separate number sequence is used for each operating unit. e. Company and Fiscal calendar period - A separate number sequence is used for each company and fiscal calendar period combination. f. Legal entity and Fiscal calendar period - A separate number sequence is used for each legal entity and fiscal calendar period combination. On the Segments FastTab, define the format for the number sequence by adding, removing, and rearranging segments. Number sequences of all scopes can contain Constant segments and Alphanumeric segments.

Constant segments contain a set of alphanumeric characters that do not change. Use this segment type to add a hyphen or other separator between number sequence segments.

1-8

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

Alphanumeric segments contain a combination of number signs (#) and ampersands (&). These characters represent letters and numbers that increment every time that a number from the sequence is used. Use a number sign (#) to indicate incrementing numbers and an ampersand (&) to indicate incrementing letters. For example, the format #####_2014 creates the sequence 00001_2014, 00002_2014, and so on. At least one alphanumeric segment must be present. Scope segments, such as company or legal entity, are optional. However, even if you do not include scope segments in the format, numbers for the selected reference are still generated for each scope. On the References FastTab, select the document type or record to assign this number sequence to. This step is optional for sequences that are defined for special application usage patterns. In these scenarios, a new number is generated by using the value of a number sequence code or ID, without using a reference. An example of a special application usage pattern is a voucher series that is used for specific journal names. However, the recommendation is not to use such patterns. On the General FastTab, specify whether the number sequence is manual, and continuous or non-continuous. Additionally, enter the lowest and highest numbers that can be used in the number sequence. Save the number sequence and close the form.

Administration
The administration of number sequences is performed by using actions provided in the Administration group on the Action Pane on the Number sequences list page. Status list: Provides a list of numbers that are generated for continuous number sequences, but which are not committed to the database. The numbers are either currently being used in a user session, are reserved for future use in a user session, or are free for use if a new client user session requests a new number for a particular number sequence in the list. If a new number does not exist for a specific continuous number sequence, it is generated by the sequence number framework from the next value for that number sequence in the Number sequence table (NumberSequenceTable). Manual cleanup: Allows the administrator to manually clean up numbers in the status list. Use of this option is only recommended after an unexpected system failure; in such rare circumstances, numbers might not be automatically cleaned up. History: Provides the history of the changes to the number sequences.

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-9

Development IV in Microsoft Dynamics AX 2012

Several administrator tasks can be performed from the Details page. An administrator can, for example, schedule an automated periodic cleanup for every number sequence by entering intervals on the Automatic cleanup FastTab. An administrator can also assign number sequences by using a page in the parameter forms in individual application modules. For example, you can view or assign the number sequences to specific references in the General ledger module. You can open the form by using the path General ledger > Setup > General ledger parameters.

Extensibility Scenarios
This section is primarily intended for developers who want to call an API that extends the NumSeqApplicationModule class to handle changes that are required by the enhanced number sequence framework. This API is called to create new fields on documents or master data entities that will use a number sequence. In a common extensibility scenario, a developer creates new fields and makes use of the new number sequence framework to generate values for those fields. There are two main extensibility scenarios: Company scenario: Based on the default segment of DataArea (or company). Organization model and regulatory scenario: Based on the use of new segments such as legal entity, operating unit, and fiscal calendar period.

The Microsoft Dynamics AX 2012 number sequence framework does not currently support an extensibility scenario to add arbitrary segments such as a warehouse or a site as a segment in the definition of a number sequence for a reference. That kind of extensibility would require significant customization to the number sequence framework. In all extensibility scenarios, the assumption is that the developer is trying to set up a new module, has already defined a field in a table, and is using the new number sequence framework to generate values for that field. A developer would typically follow these steps: Make changes to support the new extended data type that corresponds to the new field in the table. Call the API to generate the values by using the number sequence for that field.

1-10

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

Scenario: Create a Number Sequence with a Company Scope
Isaac, the Business Application Developer, is developing a new module in Microsoft Dynamics AX for Fleet management. The module will require two new number sequences: one for the vehicle numbers, and one for the trip numbers. He has already created a new extended data type, and the tables that will store the vehicles and trip information. Now he must modify the NumberSeqModule base enumeration, and create a new class that extends the NumberSeqApplicationModule class that will store the information about the two number sequences. When it is finished, he must modify the Fleet management parameters form to have a Number Sequences tab, and add the references so that the administrator can set up the number sequences.

Procedure: Modify the NumberSeqModule Base Enumeration

To add Fleet management as a module in the number sequences base enumeration, follow these steps. Open the Development Workspace. In the Application Object Tree (AOT) window, expand Data Dictionary > Base Enums. Select the NumSeqModule base enumeration. Right-click the element and select New Element. Right-click the new element (this is named Element 1 by default) and select Properties. In the Name field, enter a name such as FleetManagement. In the Label field, create or select a label such as "Fleet management". Optionally, you can add a configuration key if it might be required to disable the Fleet management functionality in certain installation. Click the Save all icon to save the changes.

TIP: Make sure that you add the base enumeration and any other objects that you create or modify to a project. This makes the promotion of changes to a testing or production environment easier. NOTE: An element for FleetManagement exists in the training environment by default.

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-11

Development IV in Microsoft Dynamics AX 2012

Procedure: Extend the NumberSeqApplicationModule Class
To create a new class for Fleet management, that extends the NumberSeqApplicationModule class and stores the two number sequences for the Fleet management module, follow these steps. Open the Development Workspace. In the AOT window, expand Classes. Right-click the Classes node and then select New Class. Right-click the newly created class and select Properties. Enter a name for the class following the naming standard NumberSeqModuleXXX where XXX represents the name of the module such as, NumberSeqModuleFleetManagement. Make sure that the new class extends the NumberSeqApplicationModule, and then use the following code sample for the class.

Class declaration public class NumberSeqModuleFleetManagement extends NumberSeqApplicationModule { } protected void loadModule() { NumberSeqDatatype datatype = NumberSeqDatatype::construct(); /* Vehicle Number */ datatype.parmDatatypeId(extendedtypenum(FMVehicleId)); datatype.parmReferenceHelp("Unique key for Fleet Management vehicles"); datatype.parmWizardIsContinuous(false); datatype.parmWizardIsManual(NoYes::No); datatype.parmWizardIsChangeDownAllowed(NoYes::No); datatype.parmWizardIsChangeUpAllowed(NoYes::No); datatype.parmWizardHighest(999999); //Use the DataArea segment datatype.addParameterType(NumberSeqParameterType::DataArea, true, false); this.create(datatype); /* Rental Number */ datatype.parmDatatypeId(extendedtypenum(FMRentalId)); datatype.parmReferenceHelp("Unique key for rentals"); datatype.parmWizardIsContinuous(false);

1-12

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

datatype.parmWizardIsManual(NoYes::No); datatype.parmWizardIsChangeDownAllowed(NoYes::No); datatype.parmWizardIsChangeUpAllowed(NoYes::No); datatype.parmWizardHighest(999999); //Use the DataArea segment datatype.addParameterType(NumberSeqParameterType::DataArea, true, false); } this.create(datatype);

public NumberSeqModule numberSeqModule() { return NumberSeqModule::FleetManagement; }

Right-click the Data Dictionary node in the AOT, and then select Synchronize.

TIP: Notice that the DataArea segment describes the default segment for the extended data types that are used for both vehicle number and trip number. IMPORTANT: You will have to synchronize the database after you create a new class that extends the NumberSeqApplicationModule class. This may take several minutes to complete.

Procedure: Create a Number Sequences Page in the Parameters Form of the New Module
Next, you must create or modify a Number sequences page on the FMSetup form for the new Fleet management module. This requires you to override the numberSeqPreInit method. You can refer to existing forms such as CustParameters or LedgerParameters for examples of the implementation. The following is sample code for the numberSeqPreInit method on the form for Fleet management.
void numberSeqPreInit() { numberSequenceModules = [NumberSeqModule::FleetManagement]; numberSeqApplicationModule = new NumberSeqModuleFleetManagement(); scope = NumberSeqScopeFactory::createDataAreaScope(); NumberSeqApplicationModule::createReferencesMulti(numberSeq uenceModules, scope); tmpIdRef.setTmpData

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-13

Development IV in Microsoft Dynamics AX 2012

(NumberSequenceReference::configurationKeyTableMulti(number SequenceModules)); }

NOTE: This form can only be used for references that have a scope of DataArea. The administration forms described in the Set Up and Administration topic can be used for references that have any scope. These forms can be found in Organization Administration > Common > Number Sequences. TIP: You must add several variable declarations to the class declaration of the form that you are modifying for the code sample provided to compile. Use the following code sample to guide you. NumberSeqReference NumberSeqScope NumberSeqApplicationModule container TmpIdRef numberSeqReference; scope; numberSeqApplicationModule; numberSequenceModules; tmpIdRef;

Procedure: Add a Method on the Parameters Table for Vehicle Numbers

Next you must use the Number Sequence API in business logic on the parameters form (FMSetup) so that the number sequence references will appear. Use the following code sample in the new method.
Public server static NumberSequenceReference numRefVehicleID() { // Optional step for DataArea scope, mandatory for other scopes NumberSeqScopeFactory::CreateDataAreaScope(); return NumberSeqReference::findReference(extendedtypenum (FMVehicleID)); }

NOTE: A FleetManagementParameters table does not exist in the training environment by default. You can create one, or alternatively use one of the tables in the FMSetup form.

1-14

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

You must repeat this process and create a second method for the trip identification number on the FMSetup form.

Procedure: Add a Table Method for Creating New Vehicle Numbers

Next, you must add a method to the FMVehicle table for creating a new number. Use the following code as an example for creating a new vehicle ID. Void setVehicleID() { NumberSeq num; NumberSequenceReference numberSequenceReference; numberSequenceReference = FleetManagementParameters::numRefVehicleID(); if (numberSequenceReference) { num = NumberSeq::newGetNum(numberSequenceReference); this.VehicleID = num.num(); } } NOTE: You must repeat this process for each number sequence.

Scenario: Create a Number Sequence with the Organizational Model

Isaac, the Business Application Developer, is developing a new module in Microsoft Dynamics AX for Fleet management. The module will require two new number sequences: one for the vehicle numbers, and one for the rental numbers. He has created the classes for storing the number sequences and the code that is required for the vehicle numbers already. He wants to make the trip ID number sequence include the data area ID and the fiscal calendar period segments. Now he must update the code to allow for the additional segments on the rental ID number sequence.

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-15

Development IV in Microsoft Dynamics AX 2012

Procedure: Modify the loadModule() Method
For each extended data type that needs to be generated by the number sequences API, additional lines of code must be added to the loadModule() method inside of the NumberSeqModuleFleetManagment class already created in the "Extend the NumberSeqApplicationModule Class" procedure. The code is used to add the second segment. Use the following code sample to guide you.
... /* Rental Number */ datatype.parmDatatypeId(extendedtypenum(FMRentalID)); datatype.parmReferenceHelp("Unique key for trips"); datatype.parmWizardIsContinuous(false); datatype.parmWizardIsManual(NoYes::No); datatype.parmWizardIsChangeDownAllowed(NoYes::No); datatype.parmWizardIsChangeUpAllowed(NoYes::No); datatype.parmWizardHighest(999999); datatype.addParameterType(NumberSeqParameterType::DataArea, true, false); //Additional line of code for second segment added here: datatype.addParameterType(NumberSeqParameterType::FiscalCal endarPeriod, true, false); this.create(datatype);

NOTE: The code sample only includes a section of the loadModule() method. If you want to additional segments, you must add another call to the addParameterType() method before the call to the create() method.

Procedure: Add a Method on the Parameters Table for Rental IDs

You have to create an instance of the scope for the two segments of DataArea (or company), and fiscal calendar period, and call the API with these two segments passed as parameters to the number sequence framework. The sample code for the Rental ID is as follows:
Public server static NumberSequenceReference numRefRentalID(TransDate _date = systemdateget()) { NumberSeqScope scope = NumberSeqScopeFactory::CreateDataAreaFiscalCalendarPeriodSc ope( curext(),FiscalCalendars::findPeriodByPeriodCodeDate (CompanyInfo::fiscalCalendarRecId(),_date).RecId); return NumberSeqReference::findReference(extendedtypenum(FMRentalI D), scope); }

1-16

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

NOTE: A FleetManagementParameters table does not exist in the training environment by default. You can create one, or alternatively use any of the tables in the FMSetup form.

Procedure: Add a Table Method for Creating Rental IDs

Next, you must add a method to the table to create a new number. Use the following code as an example to create a new trip ID.
Void RentalID() { NumberSeq num; NumberSequenceReference numberSequenceReference; numberSequenceReference = FleetManagementParameters::numRefRentalID(); If(numberSequenceReference) { num = NumberSeq::newGetNum(numberSequenceReference); this.RentalId = num.num(); } }

NOTE: A FleetManagementParameters table does not exist in the training environment by default. You can create one, or alternatively use any of the tables in the FMSetup form.

Scenario: Change the Scope for an Existing Reference

In this scenario, a developer is changing the scope of an existing reference. Isaac, the Business Application Developer wants to change the vehicle number to be global (or shared). The existing reference, FMVehicleID, has the scope of the DataArea segment. But the developer wants to change this to the global scope. The changes that are required to achieve this resemble those that are described in the previous section. First, Isaac must remove the call to the addParameterType() method in the NumSeqModuleFleetManagment.loadModule() method for the vehicle ID. Then, he must update the NumberSequenceReference method on the Fleet management parameters table to create a global scope.

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-17

Development IV in Microsoft Dynamics AX 2012

Procedure: Modify the loadModule() Method
When you use the global scope for a number sequence, you do not have to include a call to the addParameterType() method. Use the following code sample when you create the global number sequence.
protected void loadModule() { NumberSeqDatatype datatype = NumberSeqDatatype::construct(); /* Vehicle Number */ datatype.parmDatatypeId(extendedtypenum(FMVehicleID)); datatype.parmReferenceHelp("Unique key for Fleet Management vehicles"); datatype.parmWizardIsContinuous(false); datatype.parmWizardIsManual(NoYes::No); datatype.parmWizardIsChangeDownAllowed(NoYes::No); datatype.parmWizardIsChangeUpAllowed(NoYes::No); datatype.parmWizardHighest(999999); //No longer need the Data Area Scope //datatype.addParameterType(NumberSeqParameterType::DataAre a, true, false); this.create(datatype); ...

NOTE: In the code sample provided, the call to the addParameterType() method is commented out. Also notice that the sample provided is only a part of the method.

Procedure: Modify the numRefVehicleID() Method

The numRefVehicleID method on the FleetManagementParameters table must be updated to create a number sequence reference with a global scope. Replace the previous code with the following sample.
Public server static NumberSequenceReference numRefVehicleNumber() { NumberSeqScopeFactory::CreateGlobalScope(); return NumberSeqReference::findReference(extendedtypenum (FMVehicleID)); }

1-18

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

Using Number Sequences in Forms

To use the number sequence for a form in Microsoft Dynamics AX, or in the Enterprise Portal, you will typically add code to the data source for the form or dataset. You can also retrieve a number sequence value directly in code.

Scenario: Use Number Sequences in a Form

Isaac, the Business Application Developer, is developing a new module in Microsoft Dynamics AX for Fleet management. He has created the new number sequences and set up the number sequence on the parameters form. Now, he wants to have the system automatically retrieve the next vehicle number when a user inserts a new record into the Vehicle form.

Procedure: Implement the Number Sequence Form Handler

To set up a form to correctly handle the creation and update of a number sequence in a form, you must insert and update the number sequence when the form is closed or the record is deleted. Use the following code samples when you implement the number sequence form handler. For this example, it is assumed that you have a table and form data source named FMVehicle which has a field named VehicleId. Start by declaring the NumberSeqFormHandler in the class declaration of the form.
public class FormRun extends ObjectRun { NumberSeqFormHandler numberSeqFormHandler; }

Next, create a new method called numberSeqFormHandler. This method should call the static method newForm() on the numberSeqFormHandler class. Make sure that you pass in the number sequence reference from your parameters table, the data source which stores the number, and the table and field that will hold the number that is generated. Use the following code sample to guide you.

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-19

Development IV in Microsoft Dynamics AX 2012

NumberSeqFormHandler numberSeqFormHandler() { if (!numberSeqFormHandler) { numberSeqFormHandler = NumberSeqFormHandler::newForm(FleetManagementParameters::nu mRefVehicleNumber().NumberSequenceId, element, FMVehicle_DS, fieldNum(FMVehicle, VehicleID)); } return numberSeqFormHandler; }

Next you must override the create() method on the data source where the number will be populated. Use the following code sample to guide you.
void create(boolean append = false, boolean extern = false) externally { // If created

element.numberSeqFormHandler().formMethodDataSourceCreatePr e(); super(append); if (!extern) { element.numberSeqFormHandler().formMethodDataSourceCreate(t rue); } }

The formMethodDataSourceCreatePre() method is used to validate that there is a last number on the number sequence. The call to this method must be positioned before the call to super(). The formMethodDataSourceCreate() method is used to create a record with a number sequence value. The call to this method must be positioned after the call to super().

1-20

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

The next step is to override the validateWrite() and write() methods on the data source where the number sequence is being inserted into. Use the following code samples to guide you.
public boolean validateWrite() { boolean ret; ret = super(); ret = element.numberSeqFormHandler().formMethodDataSourceValidate Write(ret) && ret; return ret; } void write() { ttsbegin; super(); element.numberSeqFormHandler().formMethodDataSourceWrite(); ttscommit; }

Next, you must override the delete() method on the data source where the number sequence is being inserted. This is an important step that will make sure the number sequence is canceled and deleted when a record is deleted from your form that has a number sequence.
void delete() { ttsbegin; element.numberSeqFormHandler().formMethodDataSourceDelete() ; super(); ttscommit; }

The last step is to override the close() method on the form to make sure that the number sequence is canceled when the form is closed. Use the following code sample to guide you.
void close() { if (numberSeqFormHandler) { numberSeqFormHandler.formMethodClose(); } super(); }

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-21

Development IV in Microsoft Dynamics AX 2012

Lab 1.1 - Implement a New Number Sequence

This lab demonstrates how to implement a new number sequence reference. Estimated time to complete: 20 minutes Scenario Isaac, the Business Application Developer, is developing a new feature in the Accounts receivable module for tracking customer contracts. The new customer contracts feature will be used to track the details and terms for multiple contracts on customers account.

Challenge Yourself!
Isaac must implement a new number sequence for the customer contract ID. He has already created a new extended data type(CustContractID), contract table (CustContract), and form (CustContract) to store all the contract information. Now you must create a new number sequence reference and add it into the Accounts receivable parameters form. Make sure that you set up the number sequence format and select it in the Accounts receivable parameters form. When you are finished, implement the Form Handler on the CustContract form and make sure that the system will populate the customer contract ID automatically with the new number sequence when you are finished. IMPORTANT: You must import the AX2012_ENUS_DEVIV_LAB.xpo file which is located on the local drive of the training image before starting this lab.

Need a Little Help?

1. Import the NumberSequencesLab1_CustContract.xpo file which is located on the local drive of the training image. 2. Modify the loadModule() method on the NumberSeqModuleCustomer class to include a new number sequence reference for the customer contract ID. 3. Create a new static method on the CustParameters table to find the number sequence reference. 4. Set up the new Customer contract ID number sequence reference in the Organization administration module, and then select it on the Accounts receivable parameters form. 5. Create a new table method on the CustContract table to generate a new contract ID. 6. Declare the NumberSeqFormHandler class in the CustContract form. 7. Create a new numberSeqFormHandler() method in the CustContract form to create an instance of the numberSeqFormHandler class for the custContractID number sequence reference.

1-22

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

8. Override the create() method on the CustContract data source inside the CustContract form. 9. Override the write() and validateWrite() methods on the CustContract data source in the CustContract form. 10. Override the delete() method on the CustContract data source in the CustContract form to make sure the number sequence is cancelled when the record is deleted. 11. Override the close() method of the CustContract form to make sure the number sequence is cancelled when the form is closed. 12. Open the CustContract form and insert a new record to verify that the Contract ID number is automatically populated. TIP: The code samples for this lab can be found in the AX2012_ENUS_DEVIV_01_01_LAB_CODE.txt file. You can copy and paste these code samples into the correct methods.

Step by Step: Import the Customer Contract Project

Follow these steps to import the Customer Contract project file. 1. 2. 3. 4. Open the Development workspace. Click Command > Import. On the Import dialog box, click Browse.... Browse to E:\\80313_DevelopmentIV_XPOFiles.zip\80313_DevelopmentIV_X POFiles\AX2012_ENUS_DEVIV_01_01_LAB.xpo 5. Click Open. 6. Click OK. 7. Close the Compiler output window when the file is finished importing.

NOTE: You may need to extract the files in the 80313_DevelopmentIV_XPOFiles.zip folder first. You can do this by rightclicking on the folder and selecting Extract All....

Step by Step: Modify the loadModule() Method

To modify the code in the loadModule() method, follow these steps. 1. Open the Projects window. 2. Locate the NumberSequenceLab1_CustContract project that was created by the import, and then double-click it to open it. 3. Close the Projects window. 4. In the AOT window, expand Classes. 5. Expand the Classes node and then expand NumberSeqModuleCustomer class.

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-23

Development IV in Microsoft Dynamics AX 2012

6. Drag the class into the Project NumberSequenceLab1_CustContract window. 7. Save the project. 8. Expand the NumberSeqModuleCustomer in the project and then right-click on the loadModule() method and select View code. 9. Add the following code to the end of the method:
/* Customer Contract ID*/ datatype.parmDatatypeId(extendedtypenum(CustContractID)); datatype.parmReferenceHelp("Unique key for Customer Contracts"); datatype.parmWizardIsContinuous(false); datatype.parmWizardIsManual(NoYes::No); datatype.parmWizardIsChangeDownAllowed(NoYes::No); datatype.parmWizardIsChangeUpAllowed(NoYes::No); datatype.parmWizardHighest(999999); datatype.addParameterType(NumberSeqParameterType::DataArea, true, false); this.create(datatype);

10. Click Save, and then close the Code Editor window. 11. Right-click the Data Dictionary node in the AOT window, and then click Synchronize. NOTE: The Synchronize process can take several minutes to finish.

Step by Step: Modify the Parameters Table

To create a new method on the CustParameters table to find the number sequence reference for customer contract IDs, follow these steps. 1. In the AOT window, expand Tables. 2. Expand the Tables node and then expand the CustParameters table. 3. Drag the table into the NumberSequenceLab1_CustContract project. 4. Save the project. 5. Expand the CustParameters in the project and then right-click on the Methods node and select New Method. 6. Add the following code to the method.

1-24

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

Public server static NumberSequenceReference numRefContractID() { return NumberSeqReference::findReference(extendedtypenum (CustContractID)); }

7. Save the method, and then close the Code Editor window.

Step by Step: Configure the Customer Contract Number Sequence

To configure the customer contract ID number sequence, follow these steps. 1. In the Microsoft Dynamics AX 2012 client, open Organization administration > Common > Number sequences > Number sequences. 2. Click Number sequence in the New group of the Action Pane 3. On the Identification FastTab, enter Contract in the Number Sequence and Customer Contract ID in the Name field. 4. Click the Scope parameters FastTab. 5. Select Company in the Scope field. 6. Select CEU in the Company field. 7. Click the Segments FastTab. 8. Click Add. 9. Select the Company segment in the grid, and then click Remove. 10. Select the Constant segment in the grid, and then change the Value field to C. The Format field should now be C######. 11. Click the Reference FastTab. 12. Click Add. 13. Select Accounts receivable in the Area field. 14. Select Contract in the Reference field. 15. Click OK. 16. Close the Number sequences form.

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-25

Development IV in Microsoft Dynamics AX 2012

Step by Step: Add a Method to the Customer Contract Table
To create a new method on the CustContract table to create a new number sequence, follow these steps. 1. Open the Development Workspace. 2. In the AOT window, expand Tables. 3. Expand the Tables node and then select the CustContract table. 4. Drag the CustContract table into the NumberSequenceLab1_CustContract project. 5. Save the project. 6. Expand the CustContract in the project and then right-click the Methods node and select New Method. 7. Add the following code to the method.
Void setCustContractID() { NumberSeq num; NumberSequenceReference numberSequenceReference; numberSequenceReference = CustParameters::numRefContractID(); if (numberSequenceReference) { num = NumberSeq::newGetNum(numberSequenceReference); this.custContractID = num.num(); } }

8. Save the method, and then close the Code editor window.

Step by Step: Implement the Number Sequence Form Handler

To implement the number sequence form handler on the CustContract form, follow these steps. 1. In the AOT window, expand Forms. 2. Expand the Forms node and then expand the CustContract form. 3. Expand the CustContract form, expand the Methods node, and then right-click the Class Declaration and click View Code. 4. Add the following code to the method.

1-26

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

public class FormRun extends ObjectRun { SysFormSplitter_X verticalSplitter; NumberSeqFormHandler } numberSeqFormHandler;

5. Save the method and then close the Code Editor window. To instantiate the number sequence form handler class in the customer contract form, follow these steps. 6. Right-click the Methods node of the CustContract form in the AOT window, and then click New Method. 7. Add the following code into the new method.
NumberSeqFormHandler numberSeqFormHandler() { if (!numberSeqFormHandler) { numberSeqFormHandler = NumberSeqFormHandler::newForm(CustParameters::numRefContrac tID().NumberSequenceId, element, custContract_DS, fieldNum(CustContract, CustContractID)); } return numberSeqFormHandler; }

8. Save the method and then close the Code Editor window. To override the create() method, follow these steps. 9. Expand the Data Sources node of the CustContract form in the AOT. 10. Expand the CustContract data source and then right-click the Methods node of the data source, and select Override Method. 11. Select Create from the list. 12. Add the following code into the create method.
void create(boolean append = false, boolean extern = false) externally { // If created

element.numberSeqFormHandler().formMethodDataSourceCreatePr e();

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-27

Development IV in Microsoft Dynamics AX 2012

super(append); if (!extern) { element.numberSeqFormHandler().formMethodDataSourceCreate(t rue); } }

13. Save the method and then close the Code Editor window. To override the write() method, follow these steps. 1. Expand the Data Sources node of the CustContract form in the AOT. 2. Expand the CustContract data source and then right-click the Methods node of the data source, and select Override Method. 3. Select Write from the list. 4. Add the following code into the write method.
void write() { ttsbegin; super(); element.numberSeqFormHandler().formMethodDataSourceWrite(); ttscommit; }

5. Save the method and then close the Code Editor window. To override the validateWrite() method, follow these steps. 1. Expand the Data Sources node of the CustContract form in the AOT. 2. Expand the CustContracts data source and then right-click the Methods node of the data source, and select Override Method. 3. Select validateWrite from the list. 4. Add the following code into the validate write method.

1-28

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

public boolean validateWrite() { boolean ret; ret = super(); ret = element.numberSeqFormHandler().formMethodDataSourceValidate Write(ret) && ret; return ret; }

5. Save the method and then close the Code Editor window. To override the delete() method, follow these steps. 1. Expand the Data Sources node of the CustContract form in the AOT. 2. Expand the CustContract data source and then right-click the Methods node of the data source, and select Override Method. 3. Select Delete from the list.

4. Add the following code into the delete method.

void delete() { ttsbegin; element.numberSeqFormHandler().formMethodDataSourceDelete() ; super(); ttscommit; }

To override the close() method, follow these steps. 1. Right-click the Methods node of the CustContract form in the AOT, and select Override Method. 2. Select Close from the list. 3. Add the following code into the close method.
void close() { if (numberSeqFormHandler) { numberSeqFormHandler.formMethodClose(); } super(); }

4. Save the project.

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-29

Development IV in Microsoft Dynamics AX 2012

TIP: You can import the AX2012_ENUS_DEVIV_01_01_LAB_SOL.xpo file to verify and compare your solution. To test that the number sequence for the customer contracts is populating correctly, follow these steps. 1. From the Project window, right-click the CustContract form and select Open. 2. On the Customer contracts form, click New. 3. Verify that the Customer contract ID field has populated with a new number following the format C#####.

1-30

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

Summary
This chapter provided an overview of how number sequences are set up in the application. The chapter showed how the number sequence API works and how to implement a number sequence API in a code. Additionally, the chapter provided the steps that are required to implement a number sequence in a form. The primary purpose of the number sequence framework is to provide unique, user-friendly identifiers while maintaining a continuous or non-continuous alphanumeric sequence. An administrator can assign number sequences by using a page in the parameter forms within individual application modules, or by using a wizard in the Organization administration module. The number sequence framework provides APIs that developers can implement to create new number sequences with global scopes, company scopes, or other organizational scopes. In addition the APIs can be used to implement number sequence in a form so that when records are created the number record is updated automatically with the next number available in the sequence.

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-31

Development IV in Microsoft Dynamics AX 2012

Test Your Knowledge

Test your knowledge with the following questions. 1. TRUE or FALSE? Scope segments cannot be modified for a number sequence that is currently being used. ( ) TRUE ( ) FALSE 2. Describe the difference between a constant segment and an alphanumeric segment on a number sequence format.

3. Which of the following are supported scopes for number sequences in Microsoft Dynamics AX 2012? (Select all that apply) ( ) DataArea ( ) Department ( ) Legal Entity ( ) Fiscal calendar

1-32

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

Chapter 1: Number Sequences

Quick Interaction: Lessons Learned

Take a moment and write down three key points you have learned from this chapter 1.

2.

3.

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement

1-33

Development IV in Microsoft Dynamics AX 2012

Solutions
Test Your Knowledge
1. TRUE or FALSE? Scope segments cannot be modified for a number sequence that is currently being used. () TRUE ( ) FALSE 2. Describe the difference between a constant segment and an alphanumeric segment on a number sequence format. MODEL ANSWER: Constant segments contain a set of alphanumeric characters that do not change. Alphanumeric segments contain a combination of number signs (#) and ampersands (&). These characters represent letters and numbers that increment every time that a number from the sequence is used. Use a number sign (#) to indicate incrementing numbers and an ampersand (&) to indicate incrementing letters. 3. Which of the following are supported scopes for number sequences in Microsoft Dynamics AX 2012? (Select all that apply) () DataArea ( ) Department () Legal Entity () Fiscal calendar

1-34

Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement