Enterprise Portal development

Enterprise Portal development (AX 2009)

We Will complete this tutorial in four steps as:

Step 1 – the prerequisites
Step 2 – Understanding proxies
Step 3 – Visual Studio
Step 4 – Debugging in Visual Studio

Step 1 – the prerequisites:

Enterprise Portal must installed on the same server as Your development environment (Visual Studio). If possible, You should also consider to have EP set up on a 32 bit platform – meaning that the OS and Windows Sharepoint Services (WSS) is running in 32 bit mode.
In matters of EP development, running on 64 bit platform is the mother of all evil – examples on this will follow…
Enterpise Portal development tools must be installed. This can be done from the installation medias.
Generally the EP dev tools installs EP project- and control templates. Please note that the EP dev tools should be installed after installing Visual Studio 2008 – if not, the VS templates will most likely not be installed correctly. To ensure that the EP dev tools are successfully installed and that the Dynamics AX web project template is available from within Visual Studio, please do the following:
The Web Site project template AxWebProject.zip is installed in My Documents folder under Visual Studio 2008\Templates\ProjectTemplates\Visual Web Developer\CSharp and page and control templates AxWebpartPage.zip and AxWebUserControl.zip under Visual Studio 2008 \Templates\ItemTemplates\Visual Web Developer\CSharp.
If these files are not found under Your user profile, You will have to copy them from the user who installed the EP dev tools.
The Add-in is installed in Program Files\Microsoft Dynamics AX\50\EnterprisePortalTools and is added to the VS Add-in files path and enabled.

1. You can check this in VS Tools->Options->Environment->Add-in/macros security, you should see
   Visual Studio Options dialog
   
2. In VS Tools -> Add-In Manager Dynamics AX Enterprise Portal Tools must be enabled.
   Visual Studio Add In manager dialog
   

To check if everything is installed corrected, when you create a new Web Site Project in VS 2008 C#, you should see Dynamics AX Web project template. After creating the project, in the solution explorer when you right click on app_code folder you should get Generate Proxies menu option.

Once this has been verified everything is good to go, but before firing up Visual Studio, You should check in which layer VS connects to AX. VS uses the business connector when connecting to AX. This means that You have to check that the BC is connecting to the layer of Your choice. In my case, we always use the CUS layer. By default the BC connects to AX using the USR layer. If You want to change this do the following:

• On the server where EP is installed, click the “Start” button in Windows. Select “administrative tools” and enter the “Microsoft Dynamics AX Configuration Utility”.
• Change the “Configuration Target” to “Business Connector”.

Select the “Developer” tab and change the “Application object layer to open” to “CUS” (or whatever You want) Remember to fill in the license code for that layer

DAX 2009 Configuration utility

Step 2 – Understanding proxies:

In order to being able to reference common AX types (Objects from the AOT – Classes, tables, methods and enums) AX needs to generate proxies for the objects that You want to use. These objects are defined in the AOT from Web->Web files->Static files->proxies. If You want other objects to be recognized by EP and Visual Studio, You need to edit this file manually. A guide how to do that can be found here:
http://msdn.microsoft.com/en-us/library/cc568275(v=ax.50).aspx
To deploy the proxies to EP, please do the following:

• From the Microsoft Dynamics AX menu click Tools -> Development Tools-> Web development -> Proxies.

In the “Generate Proxies” window You will find two options for deploying the proxies

DAX Generate Proxies Dialog

• Using the first option will deploy the proxies to the EP site automatically.
• When using the second option the proxies will be deployed to a folder location of Your choice. From here You will have to copy the new proxies toC:\inetpub\wwwroot\wss\VirtualDirectories\80\App_Code\Proxies
• Remember to also update the proxies from within Visual studio, in order to have VS recognize any of the new objects. From within You project in VS, right click the App_Code node and select “Generate Proxies”. You could also choose to copy the manually from the folder mentioned in the previous step.

Step 3 – Visual Studio

A new user control is easily created by right clicking Your project node and selecting “Add new item”. From the “Add new item” dialog choose “Dynamics AX user control

Visual Studio Add new item dialog
In order to add the new user control to the AOT. Right click the control and select “Add to AOT”.
Once added to the AOT changes to the control will automatically be submitted to AX. Once AX recognizes a change AX will update the control automatically on the EP site. However if running in 64 bit mode, this will not work! You can work around this in two ways:

1. From a command prompt You can run the D:\Microsoft Dynamics AX\50\Setup\AxUpdatePortal.exe command. (The file may be located elsewhere in Your environment). Running this command will deploy all web related changes to all EP sites.
   http://msdn.microsoft.com/en-us/library/dd261467(v=ax.50).aspx
2. Running the AXUpdatePortal command may be very timeconsuming. You may find it more useful to manually copy Your usercontrol  to Your EP site. The default path for the EP site is: C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\LAYOUTS\ep. You may want to consider writing a small script to help You automate this process just a little bit.

Step 4 – Debugging in Visual Studio

Ofcourse You will want to be able to debug Your  code from within Visual Studio. In order to do so, there are a few things You need to know:

• Changes made to your usercontrols are automatically updated at the EP site when running on a 32 bit platform. If running on a 64 bit platform, You will have to update EP manually. The process for doing so is described above.

You will have to change the debugging start options. Right click Your project and select “properties->Start options”. In the start options dialog enable the “start url” radio button:

Visual Studio Debugger Start Options
and fill in the complete url for the page You want to hit on startup. This page is best found by browwing the actual EP site.
In the “use custom server” fill in the base url for the EP site. This can be fetched from within AX by entering  administration->Setup->Internet->Enterprise portal->web sites

Common issues

One of the most annoying things about working with EP related development is that You may quite often experience that EP causes Visual Studio to crash

EP Tools causes VS to crash
The only working fix that I know of, is to create a new solution/website and have Your content transferred to that website. When the problem reoccurs the procedure has to be repeated.

-Harry

Dynamics AX – Form lookups and how they work

There are few different ways to achieve a lookup field on a form.

1.     Create an Extended data type – EDT123

2.     Create a table Table123

3.     Add EDT123 to the table and the Description EDT field

4.     Go back to the EDT and create a relation between table123.EDT123 and the EDT123

5.     Automatically when the EDT field is added to another table lets say CustTable a lookup displaying the values from table123 will be displayed in the drop down.

6.     Now let’s say you want to add the description field to the lookup as well. Add the description field to the AutoLookup field group on the table. Now the lookup will display EDT123 and the description field from table123.

That is a simple way to create a lookup. Another way to create a lookup is to write a dynamic lookup on the table in which the data is coming from. This method will be a static method and will require the passing of arguments – typically the formstringcontrol that is to be the point of lookup. I prefer this method and use it often.

This a very simple example of a static lookup from a table

static void lookupTruckLoadIdEndingInv(FormStringControl  _ctrl)
{
    SysTableLookup          sysTableLookup  = SysTableLookup::newParameters(tablenum(WfsRMTruckLoadStatus), _ctrl);
    Query                   query           = new Query();
    QueryBuildRange         qbr;
    ;

    query.addDataSource(tablenum(WfsRMTruckLoadStatus));

    sysTableLookup.addLookupfield(fieldnum(WfsRMTruckLoadStatus, truckLoadId ));

    query.dataSourceTable(tablenum(WfsRMTruckLoadStatus)).addRange(fieldnum(WfsRMTruckLoadStatus,retTransferred)).value(SysQuery::value(NoYes::No));

    sysTableLookup.parmQuery(query);
    sysTableLookup.performFormLookup();
}

Joins can be peformed as well to pull back the desired data so you are not limited to querying on one table to return the proper data back to your lookup

static void lookupSettledTruckLoadIdCashier(FormStringControl  _ctrl)
{
    SysTableLookup          sysTableLookup  = SysTableLookup::newParameters(tablenum(WfsRMTruckLoadHeader), _ctrl);
    Query                   query           = new Query();
    QueryBuildRange         qbr;
    queryBuildDataSource    qbdsTruckLoadStatus,qbdsTruckLoadHeader,qbdsTenderSlipHeader;
    ;

    qbdsTruckLoadHeader = query.addDataSource(tablenum(WfsRMTruckLoadHeader));

    qbdsTruckLoadStatus         = qbdsTruckLoadHeader.addDataSource(tablenum(WfsRMTruckLoadStatus));
    qbdsTruckLoadStatus.relations(true);

    qbdsTruckLoadStatus.addRange(fieldnum(WfsRMTruckLoadStatus,settled)).value(enum2str(NoYes::No));
    qbdsTruckLoadStatus.addRange(fieldnum(WfsRMTruckLoadStatus,HHTruckLoadIdEnded)).value(enum2str(NoYes::Yes));
    qbdsTruckLoadStatus.addRange(fieldnum(WfsRMTruckLoadStatus,RetTransferred)).value(enum2str(NoYes::Yes));

    qbdsTenderSlipHeader         = qbdsTruckLoadStatus.addDataSource(tablenum(wfsRMTenderSlipHeader));
    //qbdsTenderSlipHeader.relations(true);
    qbdsTenderSlipHeader.addLink(fieldnum(WfsRMTruckLoadStatus, truckLoadId),fieldnum(wfsRMTenderSlipHeader, truckLoadId));
    qbdsTenderSlipHeader.joinMode(joinMode::NoExistsJoin);

    sysTableLookup.addLookupfield(fieldnum(WfsRMTruckLoadHeader, truckLoadId));
    sysTableLookup.addLookupfield(fieldnum(WfsRMTruckLoadHeader, routeId));
    sysTableLookup.parmQuery(query);
    sysTableLookup.performFormLookup();
}

Another way is to create an actual form and call it in a method on the table. You will
still need to pass in the formstringcontrol object but in this case you will be
calling an actual existing form that you have created. Now why do this? Well
one reason may be that you want to be able to filter on a specific field in the
lookup that maybe you could not on a typical lookup or maybe you need to add a
field to the lookup that would otherwise not be possible like you can add a
display method to a lookup but maybe you want to see the field referenced in
the display method and have the ability to sort on the field or filter on the
field. For example, like DirPartyTable.Name. Sure, you can access it using a
display method but maybe you want to see it in your lookup and be able to filter on it.
So you will create a form and call it like a lookup so you can have all the the filtering of a standard form

public client static void WfsRMlookupEmplIdCashier(Object _ctrl)
{
    Args        args;
    FormRun     formRun;
    ;

    args = new Args();
    args.name(formstr(WfsRMEmplIdLookupCashier));
    args.caller(_ctrl);
    formRun = classfactory.formRunClass(args);
    formRun.init();
    _ctrl.performFormLookup(formRun);
}

The standard lookups present in AX like the item number lookup and the customer lookup are very interesting in that you only see one field on the relation but no fields in the autolookup. In these cases the lookup fields are coming from the standard indexes on the table. Take note of what you see in the itemId lookup when unchanged and then reference the indexes coincidence not really. this can apply to any new lookup you create as well.
You can also override the lookup on the datasource - field of a form or an actual field string edit control on a form and perform a lookup
Form design object

public void lookup()
{

    SysTableLookup        sysTableLookup;
    Query                 query=new Query();
    QueryBuildDataSource  qbds;

    ;
    sysTableLookup=SysTableLookup::newParameters(tablenum(Dimensions),this);

    sysTableLookup.addLookupfield(fieldnum(Dimensions,Num));
    sysTableLookup.addLookupfield(fieldnum(Dimensions,Description));

    qbds = query.addDataSource(tablenum(Dimensions));

    qbds.addRange(fieldnum(Dimensions, DimensionCode)).value(queryValue(COSAllowedDimensions::getAllowedDimensionValue(sysDim)));

    sysTableLookup.parmQuery(query);
    sysTableLookup.performFormLookup();
}

//Lookup from a field on the form data source

public void lookup(FormControl _formControl, str _filterStr)
{
    Args    args;
    FormRun formRun;
    SysTableLookup      sysTableLookup = sysTableLookup::newParameters(tablenum(InventTable),_formControl);
    Query               query = new Query();
    QueryBuildDataSource     queryBuildDataSource;
    QueryBuildRange     queryBuildRange;
    ;
    sysTableLookup.addLookupfield(fieldnum(InventTable,ItemID));
    sysTableLookup.addLookupfield(fieldnum(InventTable,ItemName));
    sysTableLookup.addLookupfield(fieldnum(InventTable,ItemGroupID));
    sysTableLookup.addLookupfield(fieldnum(InventTable,NameAlias));
    sysTableLookup.addLookupfield(fieldnum(InventTable,ItemType));
    sysTableLookup.addLookupfield(fieldnum(InventTable,DimGroupID));

    queryBuildDataSource = query.addDataSource(tablenum(Inventtable));
    queryBuildRange = queryBuildDataSource.addRange(fieldnum(InventTable,ItemGroupID));
    //FGL, FGR, Returns
    queryBuildRange.value('xxx');

    queryBuildRange = queryBuildDataSource.addRange(fieldnum(InventTable,ItemGroupID));
    queryBuildRange.value('yyy');

    queryBuildRange = queryBuildDataSource.addRange(fieldnum(InventTable,ItemGroupID));
    queryBuildRange.value('Returns');

    sysTableLookup.parmQuery(query);
    sysTableLookup.performFormLookup();

}

-Harry