Auto Number attributes in Microsoft Dynamics 365

With the release of Microsoft Dynamics 365 Customer Engagement October service update (v9.0), two of the most requested customization features were finally implemented in the platform:

Multi-select optionsets

Custom auto numbered attributes

The first one has full customization features available in the UI out of the box, but to create and manage auto numbering attributes you have to write code utilizing SDK-functions.

This article will describe how to use the Auto Number Manager tool for XrmToolBox giving an intuitive UI to access SDK-only features for auto numbering.

Auto Number Features

The Auto Number attributes support three different types of placeholders – sequential numbers, random text, and date/time in different formats.

Syntax

Sequential number:

{SEQNUM:n} where n is the minimum number of digits.

Random text:

{RANDSTRING:n} where n is the number of characters in the random string. Maximum value for n is 6.

Date/time:

{DATETIMEUTC:fff} where fff is a standard datetime format string. See documentation.

Other text:

Any other text may be included in the number format. This text will be used as is.

Sample auto number formats:

  Number Format                                Example value
  CAR-{SEQNUM:3}-{RANDSTRING:6}                CAR-123-AB7LSF
  CNR-{RANDSTRING:4}-{SEQNUM:4}                CNR-WXYZ-1000
  {SEQNUM:6}-#-{RANDSTRING:3}                  123456-#-R3V
  KA-{SEQNUM:4}                                KA-0001
  {SEQNUM:10}                                  1234567890
  QUO-{SEQNUM:3}#{RANDSTRING:3}#{RANDSTRING:5} QUO-123#ABC#PQ2ST
  QUO-{SEQNUM:7}{RANDSTRING:5}                 QUO-0001000P9G3R
  CAS-{SEQNUM:6}-{DATETIMEUTC:yyyyMMddhhmmss}  CAS-002000-20170913091544
  CAS-{SEQNUM:6}-{DATETIMEUTC:yyyyMMddhh}      CAS-002002-2017091309

Installation

Update! XrmToolBox now supports SDK v9.0, so installation of Auto Number Manager is done through the Plugins Store in XrmToolBox.

~~The Auto Number Manager will be available in the Plugins Store of XrmToolBox once the SDK for Dynamics 365 v9.0 is released and XrmToolBox delivered using that version.~~

~~Until then:~~

~~Go to the Releases page on the GitHub repository:~~ ~~https://github.com/rappen/AutoNumManager/releases~~
~~Download the ANM zip file (not the source code)~~
~~Right-click the downloaded file and select Properties~~
~~Tick the “Unblock” checkbox and click OK~~
~~Open the zip file and copy all files and folders~~
~~Open the folder where XrmToolBox is installed~~
~~Paste the files from the zip~~
~~Start XrmToolBox~~

~~The release package contains two SDK assemblies for v9.0, and a folder Plugins that contains the ANM plugin assembly.~~

Note: Information on how to install and run XrmToolBox, read the wiki: https://github.com/MscrmTools/XrmToolBox/wiki

Running ANM

Make sure you are connected to an organization with version 9.0 or above. Starting ANM connected to older versions will display an error message.

Opening ANM will load existing unmanaged solutions. Select the solution where you want to manage your auto number attributes.

Selecting the solution will populate a list of entities included in the solution.

Select an entity, and any existing auto number attributes will be show in the table below.

To create a new auto number attribute, click button New Attribute.

The prefix of the Logical Name is taken from the publisher of the selected solution, and cannot be changed.
Enter Logical Name, Display Name and Description for the attribute.
Make sure the Maximum Length is large enough to hold the generated auto number value. If the resulting string is too long, users will not be able to create new records.
The Language Id is retrieved from the current user, and is used to define for which language the Display Name and Description shall be created.
Number Format is the property where the magic is defined. See syntax and samples above. At the time of writing this article, it is somewhat unclear whether the SEQNUM placeholder should be required, but as this is the most probable definition, this is also implemented in ANM. Clicking the blue shortcuts below the number format will help composing the format.
The Seed property can be used to define the next value to be assigned to a new record for the SEQNUM placeholder of the auto number format. The seed can be set when creating a new auto number attribute, and when updating existing attributes.
To make it easier to create the Number Format, a Sample Number of the resulting values is displayed on the form.
Below the sample number a help text is displayed indicating if the Number Format is correctly formatted, or if there are any errors. This help text will let you know if the Maximum Length property is too small, as well as format errors.

The Techy Stuff

Metadata

Technically this is not a new attribute type. It is the same old “Single Line of Text” data type, with format “Text”. What has been added is a new property AutoNumberFormat on the StringAttributeMetadata class. This would indicate that existing attributes, both custom and standard, could be decorated with this new property to activate auto numbering for existing attributes. Initial tests succeed in doing that, but this is most probably a missing constraint in this version of the SDK, and should not be possible. ANM does therefore not support this action.

Stage

The platform core assigns the automatic numbers by an internal plugin at stage Initial Pre-operation (5). This means that custom plugins of all stages can read the assigned number. Another result of this is that custom plugins have no way of really knowing how the value was assigned – by the internal numbering or by programmatic creation of records.

Sequence counter

The technology behind the actual “counting” is based on the SQL Server SEQUENCE feature. There is currently no way of reading the current or last assigned value of the sequence, other than reading the most recently created record of the entity, and parsing the value of the numbered attribute.

Seed

The seed can be set to update the current value of the sequence number. This will, naturally, only affect records created after the seed has been updated. It MAY result in duplicated numbers, if the seed is set to a lower value than current sequence position.

Random characters

At this point it is not possible to define which character set the random string is generated from. This is entirely controlled by the core plugin assigning the auto numbers. But we sure do hope the SDK will be updated to allow us to define exactly which characters that can be included in the random strings!

After investigating the Auto Number features extensively, I wrote about some More Auto Numbering features.