Microsoft Dynamics AX Support

This blog contains posts by the Microsoft Dynamics AX Support teams Worldwide

AX for Retail 2012: Working with Custom Fields

AX for Retail 2012: Working with Custom Fields

Rate This
  • Comments 14

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).

CustomField01    CustomField01a

 

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 1024x768 manager layout (“3b”):

 

CustomField02

 

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:

CustomField03   CustomField04

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

CustomField05

 

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):

CustomField06

 

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.

CustomField07    CustomField08

 

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.

CustomField09

 

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:     }
 12: 

(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:

 

CustomField10

 

 

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:

 

CustomField11

 

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

CustomField12

 

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):

CustomField13

 

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

Leave a Comment
  • Please add 4 and 3 and type the answer here:
  • Post
  • Hi Shane,

    Nice article and I can see it is fairly simply to customize and add new custom fields to the defined areas but  in AX 2012 R2 there is one more type called as "CUSTOM CONTROL". It would be great if you provide the example of how to use that "CUSTOM CONTROL" at POS end and what types of controls can be developed?

    Thanks,

    Neeraj

  • Hi Neeraj - thanks for the feedback.  I just published a companion article to this one about custom fields on receipts - a sample for Custom Control is next!  Stay tuned...

  • Hi, May I know how to change  the colour of the buttons. I have selected Colour Dropdown to the Blue but it doesn't appear on the Screen... if I check custom checkbox and edit the colours then the colours appear on the Button...

    Thanks In Advance...

  • Hi Shane, great posts...but i'm needing to add some fields like store name, sales agent, url company... any hint or clue to me?

  • Venu - what version are you referring to?  In 2012 R2 I don't see the color dropdown anymore, just the custom theme that you refer to.  You have much more control over the colors that way (compared to 2012 R1).

    Lori - where do you need to add the fields to?  The receipt?  If so, please see the companion article to this one:  blogs.msdn.com/.../ax-for-retail-2012-r2-working-with-custom-fields-for-receipts.aspx.  Note that this functionality was added in 2012 R2.

  • Venu - I believe the Color drop-down was removed in R2 CU1 so you should be using the theme option for the POS that ships with R2.  The Color dropdown should only be present if you are using N-1 POS support.

  • Hi Shane,

    Custom Fields are added successfully to TotalsArea but not able to sum decimal value to Total Amount of the transaction. How can accomplish this task?

    Thanks in advance...

  • Hello Shane,

    I read your article its nice but i work on Retail Ax 2009. Can you help me on this how to add any new field on Form layout and how to customize Retail class. Kindly help me Thanks in Advanced

    Rajnish

  • We notice the custom Field can be overwritten by the user. Is there any way to make it read-only ( Like a label not a textbox)?

  • Hi Shane,

    Added few custom columns in product grid. However those new custom fields are editable on screen. Is there any ways to make them non-editable as like standard columns.

    Also is there any way to rename existing column header text like 'Quantity' as 'QTY'?

    Thanks

    Neetu

  • Neetu:  Thanks for the feedback.  The fact that the custom fields are editable is a known issue which isn't slated to be fixed at this time.  Even though the fields are editable, the changes aren't saved anywhere and a screen refresh should revert back to the values.  It is an annoyance, though, and I will raise the issue with the product team again.

    You can easily change the column headers.  Take a look at the notes in this blog post and start the POS with the '-tr' flag.  That will tell you what labels need to be changed:  blogs.msdn.com/.../ax-for-retail-modifying-pos-labels-and-strings.aspx

  • Oscar - see my my other response about the read-only status on the field.  Currently a known issue.

  • Rajnish - unfortunately this feature was only added for AX 2012.  There is no equivalent for 2009.

  • Ibrahim:  I'm not sure if you can modify what is shown by a standard field (Total Amount).  You may have to hide the standard field and add another custom field with your calculation.  You can re-use the label of "Total Amount".

Page 1 of 1 (14 items)