Using date bookmark keys in M3 Mashups

This post describes some of things you need to be aware of when building a Mashup using bookmarks that have dates as part of the primary key. The first part is a rather long discussion of why things are the way they are but if you’re just interested in how to get things working you can skip this and jump to the second part directly.

Background

An important thing to know about the Mashup framework is that all event parameter values are transferred as strings. If a value is of a different data type it must be converted to a string before it can be used as an event parameter. The Mashup framework requires numeric decimal values to use a period (.) as decimal separator and that date values are formatted in the yyyy-MM-dd date format (2012-02-29). Mashup controls are thus required to convert any numeric or date values to the correct format when supplying values and also to parse them using the correct format when consuming values.

In cases where all event parameters are strings or an integer there is nothing to worry about, everything will work as expected. When using decimal values and dates in event parameters you have to be a bit more careful. In these cases it is recommended to explicitly select the correct type for the parameter on the Event tab in the Mashup Designer. Mashup controls that support typed parameters will then make sure that the values converted and parsed using the correct format. It should be noted that all Mashup controls do not support typed parameters. Setting the parameter type in these cases won’t have any effect.

The way dates are handled in M3 makes things a bit complicated in Mashups for a couple of reasons. The first issue is that the primary keys for a M3 bookmark are expected to be sent in the M3 database format. Decimals should use period as decimal separator and dates should be on the format yyyyMMdd (20120229) and as you can see this format is not the same as the one the Mashup framework uses. The user might have a date format such as ddMMyy as the default date format but in some programs the same user might use MMddyy. To complicate things further there is actually no way for the client to know if a M3 list column contains dates. It is actually possible to create a M3 Mashup where three or more date formats are used on or behind the screen.

Even though the date handling in M3 is complex it is possible make it work in a M3 Mashup but you have to provide some help for the Mashup controls. The first step is to select the correct type for parameters that are dates or decimals as mentioned above. The second step is to specify both source key and target key for these parameters. The M3 panel knows what date format the current program is using but it has no idea what columns that actually contain dates. The fact that you specify that the parameter is a date makes it possible for the ListPanel to convert the string to a .NET DateTime using that date format.

When all these things are specified the following will happen for a date parameter when an event is triggered:

  • The Mashup framework will request a date value using the IMashupCurrentItemTyped interface.
  • The source M3 ListPanel will convert the string in the list to a .NET DateTime.
  • The Mashup framework will convert the DateTime to a string on the yyyy-MM-dd format.
  • The parmeter is passed in the event to the target control.
  • The target control will check the parameter and notice that it is a typed date parameter.
  • The taget controls converts the value from the Mashup date format to a .NET DateTime.
  • The DateTime is then finally converted to the M3 database format and used as a key in the bookmark.

Date bookmark example

With the background discussion out of the way we can now focus on how to use this in a Mashup. The simple test Mashup in the following example has a list from PDS002 that is started with some hardcoded values. When a row is selected in the list some fields from the PDS002/E panel are shown below the list. The interesting part is the fact that the key PMFDAT in the PDS002 bookmark is a date (from date). A screenshot of the test Mashup can be seen below.

First we’ll test what happens when the date parameter is not specified to be a date. To visualize the event the Debug property of the Event is set to “True” so that the Debug Mashup Event dialog is displayed when the event is triggered. Note that the SourceKey is also defined for all parameters so that the values can be seen in the dialog. Setting the SourceKey is not always necessary for M3 Mashup controls if both the source and target controls are M3 Mashup controls.

The event is specified like this in XAML:

<mashup:Event SourceName="List" SourceEventName="CurrentItemChanged" TargetEventName="Get" Debug="True">
   <mashup:Parameter SourceKey="CONO" TargetKey="PMCONO" />
   <mashup:Parameter SourceKey="FACI" TargetKey="PMFACI" />
   <mashup:Parameter SourceKey="PRNO" TargetKey="PMPRNO" />
   <mashup:Parameter SourceKey="STRT" TargetKey="PMSTRT" />
   <mashup:Parameter SourceKey="MSEQ" TargetKey="PMMSEQ" />
   <mashup:Parameter SourceKey="FDAT" TargetKey="PMFDAT"  />
</mashup:Event>

When a list row is selected in the list we can see that the date is transferred as 070101. This is just the string directly from the M3 list where the dates are formatted on the BE server using the current date format which is yyMMdd.

To transfer the date parameter correcly we need to specify that the parmeter is a date. In the Events tab in the Settings dialog for the panel you simply select Date in the ComboBox in the DataType column. Note that you MUST specify a SourceKey when you select a data type, otherwise the date conversion won’t work. For the other parameter you are not required to specify the SourceKey in this scenario (unless you want to be able to see the values in the debug dialog).

The event is now specified like this in XAML:

<mashup:Event SourceName="List" SourceEventName="CurrentItemChanged" TargetEventName="Get" Debug="True">
   <mashup:Parameter SourceKey="CONO" TargetKey="PMCONO" />
   <mashup:Parameter SourceKey="FACI" TargetKey="PMFACI" />
   <mashup:Parameter SourceKey="PRNO" TargetKey="PMPRNO" />
   <mashup:Parameter SourceKey="STRT" TargetKey="PMSTRT" />
   <mashup:Parameter SourceKey="MSEQ" TargetKey="PMMSEQ" />
   <mashup:Parameter SourceKey="FDAT" TargetKey="PMFDAT" Type="Date"   />
</mashup:Event>

When we run the Mashup again and select a list row the debug dialog will show the date as 2007-01-01 using the Mashup framework date format yyyyMMdd. This is the expected behavior. The target control will then convert this to the M3 database format required for the bookmark.

To verify that the date used in the bookmark is correct you can also check the log file. Just make sure that the log level is set to DEBUG first. In the log entry example below the date is fomatted as 20070101 which is correct.


2012-06-15 10:15:12 DEBUG MForms.Mashup.MashupPanel.Run Run panel using event driven Bookmark. Bookmark parameters: program=PDS002, tablename=MPDMAT, option=5, panel=E, panelsequence=E, includestartpanel=False, requirepanel=True, suppressconfirm=False, source=MFormsMashup, sortingorder=1, stateless=True, keys=PMCONO,330,PMFACI,A04,PMPRNO,12282+FP+01,PMSTRT,001,PMMSEQ,0030,PMFDAT,20070101,

The full Mashup is provided here but note that the values for the Startup event are hardcoded for a specific environment and must be changed.

<Grid xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:ui="clr-namespace:Mango.UI.Controls;assembly=Mango.UI" xmlns:mashup="clr-namespace:Mango.UI.Services.Mashup;assembly=Mango.UI" xmlns:m3="clr-namespace:MForms.Mashup;assembly=MForms">
	<Grid.ColumnDefinitions>
		<ColumnDefinition Width="*" />
	</Grid.ColumnDefinitions>
	<Grid.RowDefinitions>
		<RowDefinition Height="*" />
		<RowDefinition Height="Auto" MinHeight="100" />
	</Grid.RowDefinitions>

	<m3:ListPanel Name="List" Grid.Row="0" IsListHeaderVisible="True">
		<m3:ListPanel.Events>
			<mashup:Events>
				<mashup:Event SourceEventName="Startup" TargetEventName="List">
					<mashup:Parameter TargetKey="PMCONO" />
					<mashup:Parameter TargetKey="PMFACI" Value="A01" />
					<mashup:Parameter TargetKey="PMPRNO" Value="12282 FP 01" />
					<mashup:Parameter TargetKey="PMSTRT" Value="001" />
					<mashup:Parameter TargetKey="PMMSEQ" />
					<mashup:Parameter TargetKey="PMFDAT" />
				</mashup:Event>
			</mashup:Events>
		</m3:ListPanel.Events>
		<m3:ListPanel.Bookmark>
			<m3:Bookmark Program="PDS002" Table="MPDMAT" KeyNames="PMCONO,PMFACI,PMPRNO,PMSTRT,PMMSEQ,PMFDAT" />
		</m3:ListPanel.Bookmark>
	</m3:ListPanel>

	<m3:DetailPanel Name="Detail" IncludeFields="PMMSEQ,WWFDAT,PMOPNO,PMMTNO,PMWAPC,PMPRNO" Grid.Column="0" Grid.Row="1" ColumnCount="2">
		<m3:DetailPanel.Events>
			<mashup:Events>
				<mashup:Event SourceName="List" SourceEventName="CurrentItemChanged" TargetEventName="Get" Debug="True">
					<mashup:Parameter SourceKey="CONO" TargetKey="PMCONO" />
					<mashup:Parameter SourceKey="FACI" TargetKey="PMFACI" />
					<mashup:Parameter SourceKey="PRNO" TargetKey="PMPRNO" />
					<mashup:Parameter SourceKey="STRT" TargetKey="PMSTRT" />
					<mashup:Parameter SourceKey="MSEQ" TargetKey="PMMSEQ" />
					<mashup:Parameter SourceKey="FDAT" TargetKey="PMFDAT" Type="Date" />
				</mashup:Event>
			</mashup:Events>
		</m3:DetailPanel.Events>
		<m3:DetailPanel.Bookmark>
			<m3:Bookmark Program="PDS002" Table="MPDMAT" KeyNames="PMCONO,PMFACI,PMPRNO,PMSTRT,PMMSEQ,PMFDAT" Panel="E" PanelSequence="E" SortingOrder="1" />
		</m3:DetailPanel.Bookmark>
	</m3:DetailPanel>
</Grid>

2 thoughts on “Using date bookmark keys in M3 Mashups

  1. Johannes Schwartzer

    Hi and thanks for the great example!
    I still have a problem i cant solve by myself. I have a mashup with two datepickers, first one to select a from date and second one is to select a to date. i need the datepicker because i want to supply these dates to multiple programms in the mashup.

    Then i have a list with an Current-Item-Changed Event. When the event triggers the selected from date and to date should be transfered to another programm an to the fields WWFRDT and WWTODT.

    The transfer works but the results in the list are not correct, because the date values are ignored.
    Does anyone have a solution ?

    Reply

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s