Rok v číselné řadě (AX2012)

Na diskusních fórech jsem zaznamenal hodně otázek o tom, jak přidat rok do číselné řady v AX2012, tedy jak generovat ID jako 2013-xxxxx a 2014-xxxxx, která by automaticky použila aktuální rok. Někteří lidé chápou, že by to měly umožňovat rozsahy (scopes) číselných řad, ale neví jak.

Naštěstí je to nejen možné, ale i celkem jednoduché. Než se snažit o teoretický popis nebo něž opakovat dokumentaci, pojďme si raději projít jeden jednoduchý příklad od začátku do konce.

Datový typ

Nejprve potřebujeme nový datový typ, se kterým bude číselná řada spojena. Vytvořte nový řetězcový datový typ, nazvěte jej DocuRevisionId, nastavte jeho Label na Revision ID a StringSize na 20. Tento datový typ reprezentuje hypotetické ID revize dokumentu.

Pak je třeba zaregistrovat daný typ pro nějaký aplikační modul – v našem případě to bude správa dokumentů. Otevřete metodu loadModule() třídy NumberSeqModuleDocument a přidejte na její konec následující kód (úmyslně jsem vynechal všechno, co není pro náš příklad nezbytné):

datatype.parmDatatypeId(extendedTypeNum(DocuRevisionId));
datatype.addParameterType(NumberSeqParameterType::DataArea, true, false);
datatype.addParameterType(NumberSeqParameterType::FiscalCalendarPeriod, true, false);
this.create(datatype);

Zde vytváříme definici nové číselné řady pro datový typ DocuRevisionId. Také definujeme dva parametry rozsahu: společnost a fiskální kalendářní období. Deklarace podporovaných parametrů rozsahu je velmi důležitá – bez nich nemůžete rozsahy číselných řad používat.

Definice nemá žádný efekt, dokud není modul načten. Můžete to zařídit spuštěním následujícího kódu v jobu:

new NumberSeqModuleDocument().load();

Když je to hotovo, můžete jít do Správa organizace > Společné > Číselné řady > Konfigurace segmentu a ověřit, že tam náš nový typ je a má oba očekávané segmenty.

Image may be NSFW.
Clik here to view.

Fiskální období

Než začneme konfigurovat číselné řady, vytvořme nejprve fiskální období, která budeme používat v rozsahu číselných řad. Vytvoříme období pokrývající celý rok, ale mohli byste použít cokoli, co dává ve vašem případě smysl.

Otevřete Hlavní kniha > Nastavení > Fiskální kalendáře a vytvořte nový kalendář – já jej nazvu MyYear. Měl by pokrývat celý rok:

Image may be NSFW.
Clik here to view.

Pro náš příklad budeme potřebovat dva kalendáře, takže stiskněte tlačítko Nový fiskální rok a vytvořte ještě jeden kalendář (pro rok 2014):

Image may be NSFW.
Clik here to view.

Zobrazte vygenerované období a nastavte Zkrácený název pro aktivní období. Zkrácený název, pokud je zadán, se automaticky použije v číselné řadě. V tomto formuláři můžete také období přejmenovat.

Image may be NSFW.
Clik here to view.

Číselné řady

Nyní vytvoříme dvě číselné řady – pro roky 2013 a 2014. Nemusí mít stejný kód číselné řady, ale mohou, protože unikátní identifikátor není kód samotný, ale ve spojení s rozsahem. My použijeme stejný kód, protože to bude třeba pro jeden dodatečný případ.

Jděte do Správa organizace > Společné > Číselné řady >Číselné řady a vytvořte novou řadu. Vyplňte pole následovně:

Jakmile vyberete rozsah, dostanete dodatečná pole – číselná řada bude použita pouze pro hodnoty, které zde určíte. Vyberte vaši společnost a aktivní období pro rok 013 v našem novém kalendáři.

Číselná řada automaticky obsahuje segmenty pro všechny parametry rozsahu, takže formát vypadá nějak jako DAT2013-######. Protože tam společnost nepotřebujeme, smažte segment Společnost. Hodnota segmentu Fiskální kalendářní období se přebírá ze zkráceného názvu období a můžete ji změnit, je-li třeba.

Také potřebujeme (alespoň v typickém případě) asociovat číselnou řadu s datovým typem. Přidejte novou položku na záložce Odkazy, vyberte oblast Správa dokumentů a dostanete jedinou možnost pro Odkaz: Revision ID. To je proto, že Revision ID je jediný typ ve zvoleném modulu, který podporuje Společnost a Fiskální kalendářní období.

Výsledek by měl vypadat takto:

Image may be NSFW.
Clik here to view.

Nyní udělejte to samé ještě jednou, jen použijte rok 2014 místo 2013.

Použití číselných řad

V tuto chvíli je všechno připraveno, potřebujeme jen nějaký kód, který najde správnou číselnou řadu a získá vygenerované číslo.

Podívejte se na následující implementaci. Nejdříve ze všeho najdeme fiskální období pro dané datum. Pak jej použijeme (společně s aktuální společností) k vytvoření objektu reprezentující rozsah. Nakonec najdeme číselnou řady pro daný typ a rozsah a získáme nové číslo obvyklým způsobem.

date        effectiveDate = mkDate(25,05,2013);
RefRecId    calendarRecId = FiscalCalendar::findByCalendarId("MyYear").RecId;
RefRecId    periodRecId   = FiscalCalendars::findPeriodByPeriodCodeDate(calendarRecId, effectiveDate).RecId;
 
NumberSeqScope scope = NumberSeqScopeFactory::createDataAreaFiscalCalendarPeriodScope(
    curext(),
    periodRecId);
 
NumberSequenceReference seqRef = NumberSeqReference::findReference(extendedTypeNum(DocuRevisionId), scope);
 
NumberSeq::newGetNum(seqRef).num();

Měli byste dostat číslo jako 2013-000001. Pokud změníte rok na 2014, dostanete 2014-000001, přesně jak bylo zamýšleno. Pokud změníte rok na 2015, dostanete chybu, protože žádná takové řada neexistuje.

Existuje ještě jeden přístup – normálně se nedoporučuje, ale je dobré o něm vědět. Mohli jsme vynechat referenci na datový typ a odkazovat se na číslené řady jen společným kódem. Tyto řady mají stejný kód, ale liší se rozsahem:
Image may be NSFW.
Clik here to view.
Tento zdrojový kód je podobný tomu předchozímu, jen hledáme číselnou řadu pomocí jejího kódu:

date effectiveDate = mkDate(25,05,2013);
RefRecId calendarRecId = FiscalCalendar::findByCalendarId("MyYear").RecId;
RefRecId periodRecId = FiscalCalendars::findPeriodByPeriodCodeDate(calendarRecId, effectiveDate).RecId;
 
NumberSeqScope scope = NumberSeqScopeFactory::createDataAreaFiscalCalendarPeriodScope(
    curext(),
    periodRecId);
 
info(NumberSeq::newGetNumFromCode("Revision", scope).num());

Závěr

Rozsahy číslených řad rozšiřují schopnosti číselných řad vcelku přímočarým způsobem. Nicméně pokud jim lidé dostatečně nerozumí, mají často nesprávná očekávání. Například chtějí použít segment Fiskální kalendářní období pro datový typ, který takový parametr rozsahu nepodporuje. Protože parametr není podporován, neexistuje žádný kód, který by pro něj poskytl konkrétní hodnotu (AX například neví, jaké datum a jaký kalendář by měla použít).

Můj záměr byl ukázat všechny komponenty na jednom místě – doufám, že to lidem pomůže pochopit, jak do sebe jednotlivé části zapadají.