Number sequence farmework overview in Dynamics AX 2012

Max Nguyen included in AX2012

January 19, 2017 1387 words 7 minutes

Contents

/2017-01-19-number-sequence-farmework-in-dynamics-ax-2012/number-sequence-overview.png — number-sequence-overview

For this demo, I will create New module along with NumberSequence, about creating Number Sequence without module you also use same steps just leave some steps base on Design picture above.

1. ETD

Create ETD ContosoId extends num datatype.

2. Table

Create Contoso Table with ContosoId field.

3. Enum

Create a new enum value Contoso in BaseEnum NumberSeqModule.

This value will be used to link number sequence to the module and to restrict displayed number sequence by module in Form.

4. NumberSeqModule Class

Create NumberSeqModuleXXX class

Create a new NumberSeqModuleXXX class, such as NumberSeqModuleContoso, which extends the NumberSeqApplicationModule class. The sample code for creating this class is as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
public class NumberSeqModuleContoso extends NumberSeqApplicationModule
{
}

protected void loadModule()
{
	NumberSeqDatatype datatype = NumberSeqDatatype::construct();
	;

	/* Contoso Id */
	datatype.parmDatatypeId(extendedtypenum(ContosoId));
	datatype.parmReferenceHelp("ContosoId");
	datatype.parmWizardIsContinuous(true);
	datatype.parmWizardIsManual(NoYes::No);
	datatype.parmWizardIsChangeDownAllowed(NoYes::No);
	datatype.parmWizardIsChangeUpAllowed(NoYes::No);
	datatype.parmWizardHighest(999999);
	datatype.addParameterType(NumberSeqParameterType::DataArea, true, false);
	this.create(datatype);
}

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

Use of the DataArea segment in Step 4 to describe the default segment for the extended data types used for ContosoId.

Note In Microsoft Dynamics AX 2009, number sequence references could be initialized by restarting the Application Object Server (AOS). In Microsoft Dynamics AX 2012, the initialization of references to populate the NumberSequenceDatatype and NumberSequenceParameterType tables has moved to the initialization checklist. To initialize the newly created references, run a job that executes the LoadModule method likes below.

1
2
3
4
5
6
7
static void loadNumSeq (Args _args)
{
	//define the class variable
	NumberSeqModuleContoso seqMod = new NumberSeqModuleContoso ();
	//load the number sequences that were not generated
	seqMod.load();
}

You can also reinitialize all references by running a job that executes the LoadAll method in the NumberSequenceModuleSetup class. However, for reinitializing all references, you must ensure that there are no existing number sequences already defined in the system.

Then run the wizard in Organization Administration > CommonForms > Numbersequences > Numbersequences > Generate > run the wizard.

5. Parameters Table and Form

Create a Number sequences page in the parameters form of the new module.

You need to Create ContosoParameters Table along with form, See existing forms such as CustParameters or LedgerParameters for examples of the implementation.

These forms are using DetailsFormMaster form parten as Best Practice for Setup form.

5.1. Create `ContosoParameters` Table

Add field key, Extends from ParametersKey
Properties on Field key Visible = false, AllowEdit = false, AllowEditOnCreate = false
Create index name Key with AllowDuplicate = No.
Set table properties.
TableContent = Default data
ConfigurationKey
CacheLookup = Found
TableGroup = Parameter
PrimaryKey = Key
ClusterKey = Key

The sample code for creating method this table as below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
void delete()
{
	throw error("@SYS23721");
}
public void initValue()
{
	;
	super();
	// Key is set to mandatory so set it to 1
	this.Key = 1;
}
static ContosoParameters find(boolean _forupdate = false)
{
	ContosoParameters parameter;

	if (_forupdate)
	{
		parameter.selectForUpdate(_forupdate);
	}

	select firstonly RecId from parameter
		where parameter.Key == 1;

	if (!parameter && !parameter.isTmp())
	{
		Company::createParameter(parameter);
	}

	return parameter;
}
client server static NumberSeqModule numberSeqModule()
{
	;
	return NumberSeqModule::Contoso;
}
public server static NumberSequenceReference numRefContosoId()
{
	;
	NumberSeqScopeFactory::CreateDataAreaScope(curext());
	return NumberSeqReference::findReference(extendedtypenum (ContosoId));

}

5.2. Create `ContosoParameters` form

Note This form can only be used for references that have a scope of DataArea. The administration forms described in the Setup and Administration of number sequences section can be used for references that have any scope. These forms can be found in Organization Administration > Common > Number Sequences

The data source of Parameters form likes picture below, you can also refer to CustParameters form for design.

/2017-01-19-number-sequence-farmework-in-dynamics-ax-2012/ContosoParameters.png — ContosoParameters

Code example for form methods:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
public class FormRun extends ObjectRun
{
	NumberSeqReference          numberSeqReference;
	boolean                     runExecuteDirect;
	TmpIdRef                    tmpIdRef;
	NumberSeqScope              scope;
	NumberSeqApplicationModule  numberSeqApplicationModule;
	container                   numberSequenceModules;
}

void init()
{
	;
	this.numberSeqPreInit();
	super();
	ContosoParameters::find();
	this.numberSeqPostInit();
}

void numberSeqPostInit()
{
	numberSequenceReference_ds.object(fieldNum(NumberSequenceReference, AllowSameAs)).visible(numberSeqApplicationModule.sameAsActive());
	referenceSameAsLabel.visible(numberSeqApplicationModule.sameAsActive());
}

void numberSeqPreInit()
{
	;
	runExecuteDirect            = false;

	numberSequenceModules       = [NumberSeqModule::Contoso];
	numberSeqApplicationModule  = new NumberSeqModuleContoso ();
	scope                       = NumberSeqScopeFactory::createDataAreaScope();
	NumberSeqApplicationModule::createReferencesMulti(numberSequenceModules, scope);

	tmpIdRef.setTmpData(NumberSequenceReference::configurationKeyTableMulti(numberSequenceModules));
}

Code example for NumberSequenceReference data source methods

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
void removeFilter()
{
	;
	runExecuteDirect = false;
	numbersequenceReference_ds.executeQuery();
}

void executeQuery()
{
	if (runExecuteDirect)
	{
		super();
	}
	else
	{
		runExecuteDirect = true;
		this.queryRun(NumberSeqReference::buildQueryRunMulti(numberSequenceReference,
															 tmpIdRef,
															 numberSequenceTable,
															 numberSequenceModules,
															 scope));
		numbersequenceReference_ds.research();
	}
}

6. How to use on Table

Set number sequence in Contoso Table

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
private void setContosoId()
{
	NumberSeq num;
	NumberSequenceReference numberSequenceReference;
	;
	numberSequenceReference = CVRParameters::numRefContosoId();

	if (numberSequenceReference)
	{
		num = NumberSeq::newGetNum(numberSequenceReference);
		this.Id = num.num();
	}
}

Optional method – in case you don’t want to expose Number sequence on Form Level

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
public void initValue()
{
	;
	super();

	// Initialise the title id
	this. setContosoId ();
}

public void insert()
{
	;
	if(!this.Id)
	{
		this. setContosoId ();
	}

	super();
}

From now on you can create new record in Contoso Table with number sequence.

7. How to use on Form

How to use on form level (In case you don’t want to expose NS in Table Level)

In the class declaration of the form that will be accessing data, add a variable declaration for the number sequence handler. The following example shows the variable definition for a number sequence handler.

1
2
3
4
public class FormRun extends ObjectRun
{
	NumberSeqFormHandler numberSeqFormHandlerContosoId;
}

Add the NumberSeqFormHandler method to the form. The code in this method will create an instance of the number sequence form handler and return it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
public NumberSeqFormHandler numSeqFormHandlerContosoId()
{
	if (!numberSeqFormHandlerContosoId)
	{
		numberSeqFormHandlerContosoId = NumberSeqFormHandler::newForm(ContosoParameters:: numRefContosoId().NumberSequenceId,
															 element,
															 Contoso_ds,
															 fieldNum(Contoso, ContosoId)
															);
	}
	return numberSeqFormHandlerContosoId;
}

Add create, delete, and write methods to the data source of the table that contains the field for which the number sequence is being used. The following code examples show these methods that are added to the data source for the Contoso table to support the number sequence for the ContosoId field.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
public void create(boolean _append = false)
{
	//before create, (ensure the number seuence has not run out of numbers)
	element.numSeqFormHandlerContosoId().formMethodDataSourceCreatePre();

	// start: inherited table code
	// we need to let the create happen so the user can
	// choose the type
	super(_append);

	//number sequence, create action, (get next number)
	element.numSeqFormHandlerContosoId().formMethodDataSourceCreate();
}
public void delete()
{
	//release the number sequence value.
	element. numSeqFormHandlerContosoId().formMethodDataSourceDelete();

	//delete the record
	super();
}
public void write()
{
	super();
	element. numSeqFormHandlerContosoId().formMethodDataSourceWrite();
}

public boolean validateWrite()
{
	boolean         ret;
	ret = super();
	ret = element.numberSeqFormHandler().formMethodDataSourceValidateWrite(ret) && ret;
	if (ret)
	{
		Contoso.validateWrite();
	}
	return ret;
}
Link Active()
public void linkActive()
{
	;
	element.numberSeqFormHandler().formMethodDataSourceLinkActive();
	super();
}

8. Optional method

Continuous sequence

To avoid having gaps for continuous sequence you should add this code to the delete of the table.

1
2
3
4
5
public void delete()
{
	super();
	NumberSeq::releaseNumber(ContosoParameters::numRefContosoId().NumberSequenceId, this.ContosoId);
}

9. Testing

Testing Number sequence by Job

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
static void Max_numberSeqRefCustAccount(Args _args)
{
	NumberSequenceReference numberSeqRefCustAccount = CustParameters::numRefCustAccount();
	NumberSeq               numSeqCustAccount;
	try
	{
//Use the TTS level to decide whether sequence is consumed or not.
		ttsBegin;
		if (numberSeqRefCustAccount)
		{
			numSeqCustAccount = NumberSeq::newGetNum(numberSeqRefCustAccount);
			if (numSeqCustAccount)
			{
				info(numSeqCustAccount.num());
			}
		}
		ttsCommit;
	}
	catch (Exception::Error)
	{
	   info("Caught 'Exception::Error'.");
	}
}

Thank you for reading!