Microsoft Dynamics 365 Blog

In AX for Retail 2012 we added the ability to create custom fields for use on the POS.  Because there is a bit of programming involved, a good example will probably help out.

Note:  One of the first hotfixes released for AX for Retail 2012 POS was KB 2690582.  This is a required hotfix if you want to use custom fields.  Please contact your Partner or Microsoft Dynamics Support for this hotfix.

Note:  (2013-May-31):  We recently published a hotfix that backports the Custom Fields for Receipts functionality from AX 2012 R2 to AX 2012 R1 (Feature Pack).  Please contact your Partner or Microsoft Dynamics Support for this hotfix (KB 2852548) if you would like to use this functionality.

Step 1:  Creating the Custom Field

When you open the Custom Fields window (Retail > Setup > POS > Profiles > Custom fields) you’ll notice that there are three columns for each field you can define:  Name, Type, and Caption Text ID.  The Name field is the technical name you will use when referring to the field in your POS code.  The Type can be one of four choices:

  • Payment Grid:  section 1 on screenshot below
  • Product Receipt Grid: section 2 on screenshot below
  • Totals Area: section 3 on screenshot below
  • Receipt:  the field can be added to a receipt (note:  this functionality requires KB 2852548)

Note that the payment grid is kind of an odd duck – it only appears after you create a payment and it resizes when necessary (i.e., more than one payment is added).



The Caption Text ID is the unique number that will be used when displaying the field on the POS.  This value is stored in the RetailLanguageText table in the POS database; notes about POS labels and strings can be found in this post.

Step 2:  Add the Custom Field to the layout using the Screen Layout Designer

After you create the custom fields they will be available in the screen layout designer (Retail > Setup > POS > Screen Layout).  I highly recommend using the “Copy” button on this window to make a copy of an existing layout.  I made a copy of the 1024×768 manager layout (“3b”):




Inside the layout designer, go to the Design Mode button and select one of the three sections.  This will bring up the column chooser which should now contain your custom field:


From here you can simply drag your custom field to the grid in question.  You can then resize and re-order the columns:



Note how the column disappears from the chooser after it is added to the grid.  You are only allowed to use a field once on a given grid.  You can also add your custom fields to the other two sections (payment and totals):



After you have completed your changes, make sure to hit “OK” to save your changes.  Also note that your changes are not committed to the database until you leave the line in the main Screen Layout window (I’ve been burned on that a few times).

Step 3:  Assign a Screen Layout

There are a couple of places you can assign a screen layout:  at the Worker level and at the Store Level (worker has precedence if it exists).

  • Worker:    Retail > Common > Workers.  Select a worker and Edit.  The Layout ID is on the Retail section.
  • Store:  Retail > Common > Retail Channels > Retail stores.  Select a store and Edit.  The Screen Layout ID is under the General > POS terminal section.



After you have assigned the new screen layout, push down the changes to your POS database (N-1060, N-1070 and N-1090).

Step 4:  Customize the CustomField service

Now comes the programming bit.  On your development machine, open the Services solution (the services.sln file should be located in the C:\Users\[user]\Documents\Retail POS Plug-ins\Services directory).  Under the CustomField project you should see a CustomField.cs file.  This is the code that you will edit for your custom field.



There are three methods in this class which correspond to the three custom field types:  PopulateItemReceiptFields, PopulatePaymentFields, and PopulateTotalFields.  To oversimplify things, all you have to do here is add your custom field to the fieldResults dictionary along with the value.  Make sure to spell your field exactly as you created it in AX.

  1:     public IDictionary<string, string> PopulateItemReceiptFields(IEnumerable<CustomFieldValue> fields, ISaleLineItem saleLineItem, IPosTransaction posTransaction)
  2:     {
  3:         if (saleLineItem != null)
  4:         {
  5:             Dictionary<string, string> fieldResults = new Dictionary<string, string>();
  6:             SaleLineItem saleLine = (SaleLineItem)saleLineItem;
  7:             fieldResults.Add("CustomProdReceipt", "ABCD");
  8:             return fieldResults;
  9:         }
 10:         return null;
 11:     }

(I removed the “#if DEBUG” lines from the file.  You can also add a “#define DEBUG” at the top of your .cs file)

Note that I said “oversimplify” above;  my example only shows a constant value:  “ABCD”.  This means that every row will show “ABCD” on the display.  Of course in a real-world example you would do something else here:  pull the value from a web service (not recommended; that would be slow), a custom column in a database, or (most likely) a field in the RetailTransaction object that we don’t expose by default.  I’ll leave the real-world usage as exercise for the developer.

After you have added your code to the CustomField service, give it a compile and deploy the DLL to your POS services subfolder (C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail POS\Services\).  Restart your POS and add some items and/or payments to your transaction.

If you did everything correctly, you should see your fields and values on the screen:





Step 5:  Fix the labels

The first thing you’ll notice is the not-so-subtle “({0})??Missing String??” as the text on the window.  As mentioned above, this is because we do not have labels defined in the RetailLanguageText table yet.  In AX, add an unused label ID to the fields:




And then insert some text values into the table on your POS database:



After restarting the POS you should now see the fields displayed properly (don’t forget to run the N-1090 job after adding the Caption Text ID fields):



This should get you started with this new feature for AX for Retail 2012.  Don’t forget about that hotfix mentioned above.

We're always looking for feedback and would like to hear from you. Please head to the Dynamics 365 Community to start a discussion, ask questions, and tell us what you think!