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:

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.

image

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.

image

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:

  1. Go to the Releases page on the GitHub repository: https://github.com/rappen/AutoNumManager/releases
  2. Download the ANM zip file (not the source code)
  3. Right-click the downloaded file and select Properties
  4. Tick the “Unblock” checkbox and click OK
  5. Open the zip file and copy all files and folders
  6. Open the folder where XrmToolBox is installed
  7. Paste the files from the zip
  8. 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.

image

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.

image

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.

image


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!


Read more

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


Links

Labels: , , , ,