The Microsoft Dynamics AX Enterprise Portal Blog

I have consolidated various blog posts and feedback to one EP development cookbook based on the suggestion from customers/partners. We will keep this updated to make it as a one stop guide for EP development

http://blogs.msdn.com/epblog/attachment/9944064.ashx

Enterprise Portal supports 8 different page templates. Each of these come with different SharePoint Zones and each has a predefined width assigned to each of the zones. Further SharePoint Zones by nature tend to expand to fit the contents (i.e. Webparts).

Suppose you are using the page template with 2 zones (Left & Right) and you want to set the right zone to be with 20%, EP provides a API that you can use to set the width of the WebPart zone in terms of Percentages.

Just add the following code to your user control –

protected override void OnPreRender(EventArgs e)

    {

        base.OnPreRender(e);

        //Add style to get 80/20 column widths for the left/right web part zones

        Microsoft.Dynamics.Framework.Portal.UI.StyleRegisterHelper.SetWebPartZoneWidths(this.Page, Unit.Percentage(80), Unit.Percentage(20));

    }

Persisting Filter condition in EP Grid

In AX 2009, EP grid control comes with an advanced filter. Here is a code to persist the filter condition the user last entered in a page for that user, so that later when the user comes back to the same page the last filter is applied and user didn’t have to reenter then.

This code sample assumes a dataset with the name “EPSalesTableList” which contains the datasource “SalesTable”

 (1) First override the pack method of the dataset ( EPSalesTableList in this example) in AOT

public container pack()
{

container ret;
SysLastValue sysLastValue;

formdatasource filterDataSource;
;

filterDataSource = SalesTable_ds; // Put your datasource name

    ttsbegin;
       // Delete last saved query for the current dataset
    delete_from sysLastValue
        where sysLastValue.Company      == curext()
           && sysLastValue.UserId       == curuserid()
           && sysLastValue.RecordType   == UtilElementType::DataSet
           && sysLastValue.ElementName  == filterDataSource.name()
           && sysLastValue.DesignName   == filterDataSource.name();

    // If there is a new queryRun() object then serialize and save it
    // in the sys last value table
    // Put your datasource name
   
    if (filterDataSource.queryRun())
   {
   
        sysLastValue.RecId = 0;
        sysLastValue.Company      = curext();
        sysLastValue.UserId       = curuserid();
        sysLastValue.RecordType   = UtilElementType::DataSet;
        sysLastValue.ElementName  = filterDataSource.name();
        sysLastValue.DesignName   = filterDataSource.name();
        sysLastValue.value = SysQuery::packRangeAndSortorder(filterDataSource.queryRun().query());   
        sysLastValue.insert();
    }
    ttscommit;

    ret = super();

    return ret;

}

(2) Second override the init method of the datasource ( SalesTable in this example) within that dataset in AOT

 Make sure you replace the datasourcename variable filterDataSource in the pack method with your datasource name.Save the changes, refresh AOD and now go to the page that is using this dataset and enter some filter condition & apply. Close the browser and reopen the page. Now you should see that the filter that you last applied before the browser was closed is still applied in this page.

Arif Kureshy, who is the dev manager for EP came out with this code snippet. So thanks to him for providing this sample code.

Here is a screencast done by Anunay Kumar (Test on Enterprise Portal team in Redmond)  - http://channel9.msdn.com/posts/diwakarb/Sreencast--Deploying-EP-in-NLB-configuration

This screencast walks through the steps involved in configuring Enterprise Portal on a NLB web farm. The attached PDF describes step for deploying MOSS on NLB. 

Finally i was able to get the recording uploaded. It is not the original recording. Had some issues with Live meeting, so re-recorded the webinar.The recording is available on Channel9 -

http://channel9.msdn.com/posts/diwakarb/Dynamics-AX-Enterprise-Portal-Development-Webinar/

We are having four webinars on Microsoft Dynamics AX EP development and deployment , one each in North America and EMEA time zone. This is open to all partners, customers and Microsoft employees.

Session 1 : EP Development ( repeated) – 28^th April by Diwakar Bedekar ,  Microsoft

Here is another opportunity for you to join a developer oriented deep-dive technical session on Enterprise portal for Microsoft Dynamics AX 2009. We will cover how to build and customize EP pages, user controls for lists/tasks/wizards, and common programming tasks. You are invited to participate in this virtual meeting bringing your experiences with Dynamics AX to the table, your questions and feedback, too. The discussion will be facilitated by our key R&D folks responsible for this part of the solution.

Please use the LiveMeeting invitation details below to join the meeting. If you have any questions about this meeting or others like this, please send us an email at dynresch@microsoft.com.

Session 2 : EP Deployment ( repeated) – 04^th May by Mey Meenakshisundaram,  Microsoft

Here is another opportunity for you to join an administrator oriented Deployment and Setup discussion on Enterprise Portal for Microsoft Dynamics AX 2009. We will dive into some key “how-to” points on deploying and setting up EP, understanding the infrastructure, etc. You are invited to participate in this virtual meeting bringing your experiences with Dynamics AX to the table, your questions and feedback, too. The discussion will be facilitated by our key R&D folks responsible for this part of the solution.

Please use the LiveMeeting invitation details below to join the meeting. If you have any questions about this meeting or others like this, please send us an email at dynresch@microsoft.com.

We look forward to you joining the call!

Kind regards,

The Dynamics AX Team

Make sure the Office Live Meeting client is installed before the meeting:

·        I am connecting from inside the Microsoft network

·        I am connecting from outside the Microsoft network

TROUBLESHOOTING

Unable to join the meeting?  Start Office Live Meeting and join the meeting with the following information:

Meeting 1

I am presenting Enterprise Portal for Microsoft Dynamics AX 2009 at Covergence 2009 in New Orleans

Attend this deep-dive session on the enterprise portal for Microsoft Dynamics AX 2009. See how to build and customize enterprise portal pages. Understand how to develop user controls with Visual Studio and ASP.NET to develop new portal functionality for Microsoft Dynamics AX 2009 . 

I will also be doing a repeat on the next day at 2 PM.

If you would like to meet before or after the presenation, send me email and I will scheudle something.

See you all at Convergence 2009.

Enterprise portal allows filtering the list pages using the Filter control available on the EP Grid. The Filter control provides a UI to select the field, criteria and the values you want to filter the grid. It is also possible to add multiple conditions.

But there may be scenarios where you want to use your own controls to filter the grid or the underlying DataSet. The EP framework provides the following classes to do this –

- FilterObject

- ConditionType

Let’s look at how we can do the filtering from code behind.

1. Add a Filter to list only the Customer whose name that starts with “Light”

2. Using Between operator – Between operator is a special case. There are two ways to use the Between operator -

a. Using – value..value

b. Using – valueCollection class

3. How do I use more than one condition -

4. Filter on a date – which format should a date be in? Is there a single format which can always be used?

When using the Filter control available in EP Grid, the date will be in user regional settings. But when using from the code behind, the IIS server’s regional settings will be applicable. So if the regional settings on the IIS are ‘MM/DD/YYYY’ the date value must be specified in ‘MM/DD/YYYY’ format.

One of the commonly asked questions is - How do I share code between different EP controls.

Enterprise Portal in AX 2009, supports sharing of code using a dummy User Control (we call this a dummy user control as it doesn’t have any UI and contains only reusable functions). Create a User control and add all the common reusable code into this dummy user control and then include it into your other user controls where you want to use this common code.

For the sake of simplicity, I am going to show how you can display the current logged in User’s information in multiple user controls by sharing the code.

Let's assume that you have two user controls that need the Current Logged in User's name. To achieve this I will be creating a User Control called - MyCommonCode.ascx and two controls that will be using the common code - MyUserControl1 & MyUserContorl2.

Creating the User Control to store the common code

So the first step is to open Visual Studio and to create a Dynamics AX Web Project. In Visual Studio select \New\New Web Site from the File menu. In the subsequent New Web Site dialog a Dynamics AX Web Project should be located under My Templates. The dialog should look something like the following screen shot.

After clicking OK a project is created in Visual Studio that contains amongst other things a node called AxUserControl.ascx. Right click on the AXUserControl.ascx node and rename it to MyCommonCode.ascx.

Go to the Code behind file for this user control and add the following static methods to get the GetCurrentLoggedInUser() method.

Save the File.

Create Controls to use the common code

To add new user controls to the web site project, right-click on the Project and select Add New Item.

Repeat to above steps to add a second user control.

Open the MyUserControl1.ascx and add the following markup -

The First line is the most important line as it enables the code sharing.  The rest of the markup is just standard ASP.NET markup. We are adding a label to display the User name.

Go to the Code behind for this user control and add the following highlighted code to the Page_Load event.

Repeat the same for the other user control.

To add the User Controls to the AOT right-click on the user controls and select "Add to AOT".  The user controls will be saves in AOT under \Web\Web Files\Web Controls and in addition they will be deployed to the web server where the EP development site is deployed.

Now go to SharePoint create a new page and add the two user controls - MyUserControl1.ascx & MyUserControl2.ascx and you will see the Current Logged in user name displayed in both the user controls.

Anytime you want to share some common code across user controls, just add your methods to the Common user control and include the user control (using the ASP.NET Register directive) where you want to use the common code.

As promised in part 1 I will continue with discussing the new Managed DataSet and in particular focus on how to write code that uses the DataSet. As I am writing this I realize that there will be many parts to this saga which will gradually uncover more and more parts of the DataSet and its related classes. As is customary I will start with discussing the basics and then move forward from there.

So in this post I will show how to create and run a DataSet and how to enumerate the rows in a DataSetView in order to print some of the field values. The code for this post is located here.

The first step is to create the DataSet and in order to that I need an AX session – the following code which is part of a simple class does exactly that.

The static ISession object is instantiated via the SessionCache object which in this case will return a non-cached standard AX session i.e. it logs on to AX via BC.NET. The CreateAndRun function will create a DataSet by calling the DataSet constructor which takes the AOT node of a DataSet. It will then also “run” the dataset by calling Run which effectively calls ExecuteQuery on all the form datasources in the dataset. In other words run will fill the dataset with data.

For this example I will use the tutorial DataSet that is shipped with AX 2009 called tutorial_CustomerDetail. The dataset consists of one dataset view constructed by the inner join of the ContactPerson table to the CustTable. The CreateAndRun method above is this used as follows to create the dataset.

The code then continues to print the values of the AccountNum and ContactPerson!Name fields for all the rows in the CustTable dataset view. A couple of things are worht noticing here. First is how the dataset view is accessed. The DataSet contains a collection that is keyed by index and by dataset view name of all the views in the dataset (for further discussion of views go here). The name of a view is the name of master form datasource in the view which in this case is CustTable since the ContactPerson form datasource is inner joined to the CustTable form datasource. Secondly notice the name of the second field in the field list that I want to print the values of. Because the view consists of all the fields from two tables the fields of the child tables are prefixed with their name to avoind conflicts e.g. all tables in AX have RecId so in order to distinguish between CustTable.RecId and ContactPerson.RecId in the above exmaple the fields from ContactPerson are prefixed with ContactPerson! e.g. ContactPerson!Name.

The PrintDataSetViewRows function will enumerate all the rows in the dataset view which is possible because the DataSetView class implements IList and this IEnumerable.

And finally I call PrintRowValues for each DataSetViewRow in the dataset view in order to print the actual values of the fields in the  row.

The code uses the managed metadata object model defined in the Microsoft.Dynamics.Framework.Metadata.Ax namespace to lookup the label of the field. The metadata object model contains a set of classes that describes the metadata for many of the objects in the AOT making it easy to access the metadata from managed code. In this case here I grab the label so I can print it together with the actual field value. To get the field value I call the GetFieldValue function the DataSetViewRow.

The output when calling the above ReadFieldValues from a console app is shown below. You might be suprised that you only see 10 records but that is because the dataset by default has paging enabled with the page size set to 10. To disable or change the paging parameters you call the SetPagingParameters function on the DataSetView class which takes the PagingParameters struct as a parameter.

Furthermore notice the effect of the inner join between the CustTable and the ContactPerson table i.e. some rows from CustTable are repeated in order to produce the join.

Enterprise Portal in Microsoft Dynamics AX 2009 is built on ASP.net/AJAX and provides full power and flexibility  to  developers to build real , modern, interactive and responsive web applications for intranet, extranet and Internet scenarios.

For any new platform adoption by developers, good documentation supported by simple to understand code samples are very much essential. When ASP.net debuted , ASP.net Quick start samples helped many people get a grasp of the new technology, acquaint with the controls, APIs and syntax and was the starting place for all.

Same way to help Microsoft Dynamics AX developer community and ASP.net developer community to easily adopt Enterprise Portal, the EP framework and application teams built  number of simple, brief, easy to use samples for various controls & APIs. The dev support team reviewed and edited these quick starts and UA team helped us to publish these. This email is to announce the broad availability of these resources on msdn. Please leverage these great assets to familiarize with EP and help evangelize, sell, implement, customize and support Microsoft Dynamics AX 2009 EP better.

Few more quickstarts are going to be uploaded in the next few weeks. They are currently undergoing the review process. Below is the complete list of quick starts that will be made available through the axcodesamples site

Many Thanks to

Many thanks to above quickstart authors and Becky Newell& Bill Thompson for reviewing and validating the quickstarts, Dianne Siebold & Gene Milener for help publishing it and Steve Kubis, Dewey Stegmiller, Sue Brandt for their support. Many thanks to EP team and Jay, Sitaram, Ximing and Suki for supporting this effort overall.

EP 2009 comes with a whole new way to data bind and access AX data and yet it is still very familiar (as you will learn in this post) if you have developed EP WebForms and AX client Forms. The new way is the DataSet. Since EP 2009 is implemented using ASP.NET we needed to come up with a new way to enable data binding for the ASP.NET based UI since the existing data binding in AX is tied to specific display targets that I just mentioned. So enabling ASP.NET data binding to AX data was one of the major design goals for the DataSet. Another important design goal for the DataSet was to deliver the rich and familiar programming model from the AX client forms around data binding which essentially means the FormDataSource.

So what we ended up with was the new DataSet node in the AOT which looks like an AX Form node except it does not have a Design node. At the heart is the FormDataSource. The DataSet comes with the same data shaping constructs (join types) to combine many tables via the FormDataSource as well as a similar programming model:

• X++ event overrides (init, run, validateField, modifiedField, validateWrite, write, etc.)
• Metadata
• Access to the runtime instance of the FormDataSource’s
• Access to the Query and QueryRun objects

The list is probably incomplete but it highlights the concepts that are known from developing an AX Form.

The DataSet is natively supported by the AX kernel (client and BC.NET) via two new classes available in X++

• DataSet – implements the design time functionality around the DataSet AOT node
• DataSetRun – implements the runtime functionality

The DataSet thus provides AX data binding functionality independent of the UI. But how does this make it into ASP.NET?

Managed DataSet

The answer is the managed DataSet. To bridge the gap between ASP.NET and other managed clients there is a new managed DataSet which is shipped with EP 2009. The managed DataSet is a set of classes that are implemented in the Microsoft.Dynamics.Framework.Data.Ax assembly. At a quick glance the DataSet and it its related classes look somewhat similar to the ADO.NET data set but there is not much in common between the two.

The managed DataSet serves three main purposes:

1. Formalize and expose the DataSet Views concept
2. Enable data binding 
3. Provide a managed programming model for the MorphX DataSet

In this post I will talk about 1 and 2. In a later post I will dig into the programming model around the managed DataSet with some samples.

DataSet Views

The form datasource enables combining multiple tables via joins to shape the data surfaces in the UI. When doing an inner or outer join the tables are combined into one execution unit which basically means one SQL query issue against data base. That is in contrast to an active join which results in two queries – one for each execution involved in the active join (an active join is basically a filter applied to the child table). An inner or outer join is exposed as a DataSet View through the managed DataSet. A view is rectangular representation of the data in the tables involved in the join by changing the projection list to include all the fields of the tables. A view corresponds to one execution unit. The view adds a layer of abstraction on top of the tables so that the data is no longer access via the tables but through the view. The DataSet view is implemented by the class DataSetView in the Microsoft.Dynamics.Framework.Data.Ax assembly.

Side Note: The DataSet does not support Exist and Not Exist joins.

In the example on the right the various join types in a MorphX DataSet are mapped to DataSet Views. Table1, Table2 and Table3 are all joined into one view (View1) as a result of the join types and Table4 is represented by View2. The DataSet thus contains two views.

Data Binding

A DataSetView can be thought off as a uber-table that makes it easy to data bind to multiple tables in a control (a view can just as well only contain one table). The DataSetView implements the necessary interfaces to enable data binding. The AxDataSource control which is the primary way for controls to bind to AX data in EP contains a reference to a DataSet. The data set is determined by the value of the DataSetName property on the AxDataSource control. The data source control contains a list of type AxDataSourceView which inherit from DataSourceView and each AxDataSourceView contains a reference to a DataSetView in the list of views defined on the DataSet that is referenced by the AxDataSource. Finally the DataSetView contains a list of type FormDataSource for each form datasource that makes up the view.

When binding a DataBoundControl in ASP.NET you pick a DataSourceView from the list of views in the data source control by setting the DataMember property on the control. As a result of this when binding a control to the AxDataSource control you are effectively picking the DataSetView (and ultimately the AX tables) that you are binding to when setting the DataMember property.

Side Note: The fields in a DataSetView follow a special naming guideline to prevent name clashes. The fields off the inner joined tables are prefixed with the name of the form datasource and a ! character. For example in the previous examples the fields in View1 from Table2 would be named Table2!Field1, Table2!Field2, etc.

The picture on the left shows the interaction between the AxDataSource control, the DataSetViews and the kernel DataSet.

Current View

The notion of the current record is heavily used in AX form data binding. Typically you have the overview tab in an AX form displaying a grid of records and the subsequent tabs display further information for the currently selected record in the grid. The form datasource defines a notion of a current record and most of the controls display only data from the current record. Furthermore when leaving the current record (e.g. through the VCR controls on a form) any changes made to the record are automatically saved before moving to the next record in the form datasource cache. Moving to a new record will trigger the controls to rebind and thus display the information for the new record.

These concepts are also available in EP 2009.  The DataSetView exposes the current record and to enable EP controls to easily data bind against the current record a special view called the Current view is exposed by the AxDataSource control. As described for each DataSetView in the DataSet the AxDataSource control will create AxDataSourceView’s and in addition it will create a current view for each DataSetView e.g. in the previous example there would be two additional views named View1_Current and View2_Current.

The AxForm should always be bound to the current view i.e. it’s DataMemeber property is always set to e.g. View1_Current. The AxForm is ideal to display information from the current record in the DataSetView. In a similar fashion as the grid control in an AX form the EP grid control (AxGridView) will change the current record to the record that is selected in the grid. So if you data bind an AxGridView and AxForm to the same AxDataSource control and the grid is bound to View1 and the form to View1_Current the form will automatically rebind and display information from the currently selected record in the grid.

Summary

So this was the first post on the managed DataSet and the concept of DataSetViews. It showed how the MorphX DataSet defined in the kernel is made available for data binding in ASP.NET via the AxDataSource control. As the title of the post indicates there will a second part where I will give concrete samples on how to program against the managed DataSet.

It was pointed out to me that I had made a small mistake on my previous post. There is an ugly gap between my toolbar and the grid.

There is actually some javascript code that runs when the page is rendered that will remove the gap which makes it look a lot nicer. Take a look at the before and after shots on the right. You can see that the gap is gone.

So what was the mistake? When I added the User Control Web Part to the page in Sharepoint I had added it to the Header web part zone. To make the gap disappear I had to move the web part to the Middle Column web part zone.

That’s it.