Microsoft Dynamics AX Support

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

AX for Retail: The Blank Operation Explained

AX for Retail: The Blank Operation Explained

Rate This
  • Comments 10

One of the easiest and fastest ways to extend the AX for Retail POS is by using the Blank Operation.  Blank Operations can be assigned to buttons in your Retail POS till layout – and you can deploy as many of them as you wish, which makes using them very flexible.  Certain aspects of the the BlankOperations plug-in may a bit of a mystery, so here are a few tips to get you started.

[Note:  The Blank Operation has not changed from AX for Retail 2009 and AX for Retail 2012, so this article pertains to both versions.]

Creating the Blank Operation button in POS

The Till Layout designer is a good place to start understanding how the BlankOperations plug-in works.  In a production environment you would do this in the Dynamics AX client (Retail Headquarters > Setup > POS > Retail POS > Till layout), but for quick testing, you can modify buttons directly in the POS.  Just remember that your changes will be overwritten the next time you run the N-1090 job.

If you are using the sample layout, launch POS and go to the Tasks menu.  Right-click on an empty button and select Button Properties.  In the resulting window, select Blank Operation as the Action Item:

ButtonProperties    BlankOperationOptions

After you select Blank Operation, you will see that two new fields are added to the window:  Operation Number and Blank Operation Param.  These two fields are used to make each instance of a Blank Operation button unique and they are the key for how the the POS communicates to the BlankOperations plug-in.  Both of these fields are simple string fields; you don’t have to actually send in a number for the Operation number.

Developing the BlankOperations Plug-in

When you first open the BlankOperations.cs file, you’ll see that it is a very simple class:  just a constructor and one method.  Here is the starting code for the method (I removed some of the code):

       public void BlankOperation(ref BlankOperationInfo operationInfo, ref PosTransaction posTransaction)
       
{

           
StringBuilder comment = new StringBuilder(128);
           
comment.AppendFormat(ApplicationLocalizer.Language.Translate(50700), operationInfo.OperationId);
           
comment.AppendLine();
           
comment.AppendFormat(ApplicationLocalizer.Language.Translate(50701), operationInfo.Parameter);
           
comment.AppendLine();
           
comment.Append(ApplicationLocalizer.Language.Translate(50702));
            
           
using (LSRetailPosis.POSProcesses.frmMessage dialog = new LSRetailPosis.POSProcesses.frmMessage(comment.ToString(), MessageBoxButtons.OK, MessageBoxIcon.Error))
           
{
               
LSRetailPosis.POSProcesses.POSFormsManager.ShowPOSForm(dialog);
           
}

By default, all this code does is open a message box with the two strings that were passed from the POS.  For instance, if I passed in “Hello” and “World”, this is what would appear when the button was pressed:

HelloWorld MessageBox

As you can see by the BlankOperation() method, you have two parameters available to you:  a BlankOperationInfo variable and a PosTransaction variable.

If you examine the BlankOperationInfo datatype, you’ll see that there are two main properties, both string values:  operationID and parameter.  These match up with the two values passed from the button.  In addition, there are a few other values that get passed from the POS, including the currently selected item line and payment line.

Also of great interest is the POSTransaction parameter.  This is a substantial object which represents everything to do with the current transaction:  all of the items, including price, discount, and tax; all of the payments that have been made so far; any customer information; etc.  Explaining the POSTransaction is beyond the scope of this article, but if you set a breakpoint at the start of the BlankOperation() method, you can examine the properties of the POSTransaction object and get an idea of the information available to you.  Hopefully the examples I provide will help you get started.

The key to making a multi-purposed BlankOperations plug-in is to separate your code based on the Operation Number passed in.  This can be done with a simple Case statement on the operationInfo.OperationId value:

            switch (operationInfo.OperationId)
           
{

               
case "GetLoyaltyStatus":
                   
//add code here to echo current Loyalty balance for customer
                    break;
               
case "Price":
                   
// add % amount to the last item added
                    break;
               
case "Bing":
                   
//open an Internet Explorer window with results of a bing search
                    break;
               
case "Image":
                   
//open a window with an image for the item
                    break;
               
default:
                   
//default, just echo the operation number and parameter value
                    break;
           
}

If you download the project attached to this article, I have included code for each of these operations.

After deciding which block of code needs to be executed, you have at your disposal two main pieces of information:  the POSTransaction parameter mentioned earlier, and the operationInfo.Parameter value, which is the string passed in from the second box on the button. 

In the “Price” example, you might want a separate button for +10%, +20%, +30%, etc.  You would set up three buttons passing in “10”, “20”, “30”.  Your code would then be responsible for using the value passed in (and from converting from a string to a numeric value).  If you need to get more complicated, you could pass in multiple values, delimiting them accordingly.  If you need to add 20% to all yellow items in the transaction, you could pass in “20;yellow”.  Your code would simply break apart the two values that it needs.

Tips for the BlankOperations Plug-in:

The attached project will show you some fun stuff that you can do with the Blank Operation.  All of the operations were done as proof-of-concept so they would definitely need to be cleaned up before using them.  A few other notes:

  • Make sure to use plenty of try/catch blocks in your code and do lots of type-checking.  You don’t know what will be passed in from the button, and there or infinite combinations of what will be in the POSTransaction object.  Don’t make any assumptions on what you will get.

 

  • You’ll notice that the POSTransaction is also declared as a “ref” parameter. This means you have full read-write access to all values in the transaction! While this means you have incredible flexibility, you can also get into trouble if you’re not careful.

 

  • There is only one BlankOperations plug-in available.  This means that all of your code has to be shared into one single DLL.  Since multiple developers (and possibly other organizations!) can be developing functionality for this plug-in, you will want to modularize your code as much as possible and just put in calling stubs from the BlankOperations() method.

 

  • There are two additional files in the BlankOperations project:  SupportClasses\LogOff.cs and SupportClasses\ItemSale.cs.  The latter can be used to programmatically add items to the transaction.  There are two bugs in these support classes which I will address in another article.

Hopefully this will get you started down the road of adding functionality to your POS implementation.  Please use the comments below to share any ideas you have for the BlankOperations plug-in or any issues you may have run into.

Attachment: BlankOperationsSamples.zip
Leave a Comment
  • Please add 5 and 1 and type the answer here:
  • Post
  • sorry, when I try to build this example, I have this error:

    Error 2 The type or namespace name 'ApplicationFramework' does not exist in the namespace 'LSRetailPosis' (are you missing an assembly reference?) C:\Users\Administrator\Desktop\Retail POS Plug-ins\Retail POS Plug-ins\Services\BlankOperations\BlankOperations.cs 73 37 BlankOperations

  • could you help me?

    Antonio

    a.chiaravalloti@avanade.com

  • Hi Shane!

    Thank you for another excellent article regarding POS, however I'm intensly awaiting the bug-workarounds that you mentioned: "There are two bugs in these support classes which I will address in another article"

    Any idea when you will publish that?

    BR

    Lars

  • I thought that I responded to these comments... sorry 'bout that.

    Antonio - I believe you are missing a reference to one of the DLLs.  In 2012 you don't have to worry about that since we provide the .csproj files for you.  For 2009 it's still kind of a pain to get them all correct.  If you're still having problems getting the DLL compiled, please open a support case and we can help them out.

    Lars - you may have already found it, but there is now an article out there with the bug fixes for 2009.  See the link above.

  • i would create a new retailtransaction when i first hit the blankoperation button.but the postransaction was reverted next time. How can i always keep the postransation? pls help for me.

  • Jack,

    If you are talking about 2012, please see the note that I just published with respect to how to add an item to a transaction using the blank operation:  blogs.msdn.com/.../ax-for-retail-two-bug-fixes-for-the-blank-operation-sell-item.aspx

  • Hi Shane,

    we are customizing AxRetail POS using the blank operations. We are facing a problem in posting the current transaction on the screen through a button on our custom form. How can we post the current transaction using our own code?

  • HI Asad and Tahir,

    What you're after is the ability to conclude the current transaction from the blank operation - I'm not aware of a way to do this programmatically.  The product will do this automatically at the end of operations if it determines that it is time to do so (i.e., after a payment has been made that brings the outstanding balance to zero).

    If you are looking to integrate to an online payment processor (I'm wondering if this is the same request that you have been working on with one of my colleagues from Dubai?) then this should be something that could be accomplished with a customization to the EFT plug-in.  You can find the 2009 version of the sample here:  blogs.msdn.com/.../ax-for-retail-a-better-sample-for-eft-plug-in-credit-card-processing.aspx

    Shane

  • Hi Shane,

    I want to create a new form to display the item information. How to get the item price. I want to enter the item is and it should display the item price taking into consideration the discount if any on the same item.

    Thanks

  • Kamran - this sounds like it is similar functionality that is available in the Price Check form which resides in the Dialog plug-in.  You should be able to grab code from that form.  Essentially what it does is creates a temporary transaction with the currently-selected customer and adds the item to that transaction.  This then gets run through the same price/discount/tax engine as a normal transaction.

    Look for the "checkItemPrice()" method in the frmPriceCheck.cs file.

Page 1 of 1 (10 items)