Creating metrics

Several scripts and triggers are required when creating and displaying a metric on a user’s Home Page. This portion of the documentation describes them.

Adding a metric

The AddMetric procedure of the syHomePageMetric form is used to add metrics to a Home Page template. You will use this command in the trigger processing procedure that adds Quick Links and metrics for your integration.

The following example is a portion of the IG_HomePage_SetupRoles trigger processing procedure that runs when a new Home Page is created for a user. The AddMetric procedure is used to add the “Top 5 Leads” metric to the Home Page.

in integer iIndustry;
in integer iUserRole;

local string sUserID;

sUserID = 'User ID' of globals;

{Add a Metric for the Operations Manager}
if iUserRole = ROLE_OPSMGR then
	call AddMetric of form syHomePageMetric, 
		sUserID, 
		IG_PROD_ID, 
		METRIC_TOP5LEADS;
end if;

Metric name

The name for a metric is maintained separately from the metric. You must add a global procedure named MetricGetName that will be called each time the metric’s name is displayed. Based on the Metric ID passed into the procedure, the appropriate metric name should be returned. The procedure must have the following parameters:

inout string sMetricName;
in 'Metric ID' iMetricID;
in DictID iDictID;

The following example is the MetricGetName procedure for the sample integrating application. It returns the name of the metric defined for the sample.

inout string sMetricName;
in 'Metric ID' iMetricID;
in DictID iDictID;

{Retrieve metric names}
if iDictID = IG_PROD_ID then
	if iMetricID = METRIC_TOP5LEADS then
		sMetricName = "Top 5 Leads";
	end if;
end if;

Metric security

Since metrics can display sensitive data, it’s important to secure them so only authorized users can view their content. To control access to metrics, you must add a global procedure named MetricHasAccess to your application. Based on the Metric ID passed in, this procedure must determine whether the current user has access. Typically, the procedure will examine security settings for forms that access the same data as the metric. It will return true if the user has access to those forms, or false if they don’t. The procedure must have the following parameters:

inout boolean bAccess;
in 'Metric ID 'iMetricID;
in DictID iDictID;

The following example is the MetricHasAccess procedure for the sample integrating application. It uses the Security() function in Microsoft Dynamics GP to determine whether the current user has access to the Lead Maintenance or Lead Inquiry forms. If the user has access, the value true is returned to indicate the user has access to the metric.

inout boolean bAccess;
in 'Metric ID 'iMetricID;
in DictID iDictID;

local integer security_result;
local integer prod_id;

prod_id = IG_PROD_ID;

{Does the user have access to the underlying metric data?}
if iDictID = IG_PROD_ID then
	if iMetricID = METRIC_TOP5LEADS then
		{Check the maintenance form for access}
		security_result = Security(prod_id, FORMTYPE, resourceid(form IG_Lead_Maintenance));
	
		if security_result = REJECT_RECORD then
			{Check the inquiry form for access}
			security_result = Security(prod_id, FORMTYPE, resourceid(form IG_Lead_Inquiry));
		
			if security_result = REJECT_RECORD then
				bAccess = false;
			else
				bAccess = true;
			end if;
		else
			{User has access}
			bAccess = true;
		end if;
	end if;
end if;

Executing a metric

When a Home Page is loaded or refreshed, Microsoft Dynamics GP will execute all of the metrics that have been added to that page. To execute the metrics you have defined for your integration, you must add a global procedure named MetricExecute to your application. This procedure will be called, and the ID of the metric to execute will be passed in. The procedure must gather the data required for the metric and return it through the following set of required parameters:

in 'Metric ID' iMetricID;
in DictID iDictID;
inout integer iNumCategories;
inout integer iNumSeries; 
inout string sChartType;
inout string sCategories[12];
inout string sSeriesName[10];
inout string sCategoryAxis;
inout string sValueAxis;
inout currency iSeries1Values[12];
inout currency iSeries2Values[12];
inout currency iSeries3Values[12];
inout currency iSeries4Values[12];
inout currency iSeries5Values[12];
inout currency iSeries6Values[12];
inout currency iSeries7Values[12];
inout currency iSeries8Values[12];
inout currency iSeries9Values[12];
inout currency iSeries10Values[12];

The MetricExecute procedure will call the appropriate procedure specific to the metric to be run. This metric-specific procedure will gather the data for the metric and return it to the MetricExecute procedure through the inout parameters.

For example, the following is the MetricExecute global procedure for the sample integrating application. The Microsoft Dynamics GP application will call the MetricExecute procedure, requesting that the “Top 5 Leads” metric be processed. In turn, the MetricExecute procedure calls the Metric_Top5Leads procedure which actually assembles the data for the metric and passes it back to MetricExecute. (You will learn more about this procedure in Writing a metric procedure.)

in 'Metric ID' iMetricID;
in DictID iDictID;
inout integer iNumCategories;
inout integer iNumSeries; 
inout string sChartType;
inout string sCategories[12];
inout string sSeriesName[10];
inout string sCategoryAxis;
inout string sValueAxis;
inout currency iSeries1Values[12];
inout currency iSeries2Values[12];
inout currency iSeries3Values[12];
inout currency iSeries4Values[12];
inout currency iSeries5Values[12];
inout currency iSeries6Values[12];
inout currency iSeries7Values[12];
inout currency iSeries8Values[12];
inout currency iSeries9Values[12];
inout currency iSeries10Values[12];

local long nStatus;

{Is it our metric to process?}
if iDictID = IG_PROD_ID then
	if iMetricID = METRIC_TOP5LEADS then
		call Metric_Top5Leads, 
			iNumCategories,
			iNumSeries, 
			sChartType,
			sCategoryAxis,
			sValueAxis,
			sCategories,
			iSeries1Values;
	end if;
end if;

Documentation Feedback

---