There are certain features of Exago that the host application may want to control directly. In some cases Exago provides the ability for the host application to do this by calling out to a specified Web Service or .NET Assembly with specific methods.
To utilize the External Interface:
Note: A different external interface can be specified within the Scheduling Service configuration. For more details see Configuring Scheduler Settings.
Note: The Web Service should be formatted as ‘url=http://WebServiceUrl.asmx’. The .NET Assembly should be formatted as ‘assembly=AssemblyFullPath.dll;class=Namespace.ClassName’. For a .NET Assembly all methods should be static.
The functions below will use the parameters ‘companyId’ and ‘userId’, which should be set through the Api as users enter Exago.
To enable the host to track report executions, Exago and the Exago Scheduling Service will fire an event at the start of each report execution. The following method will be used:
void ReportExecuteStart(string companyId, string userId, string reportName)
Description |
Used to track report execution by user. |
Remark |
Should not return any value. |
By default Exago will store User Preferences such as which Dashboard Reports to execute on startup in a browser’s cookie. While convenient this means if a user switches browsers or machines their preferences will be lost. Instead the host application can manage how these User Preferences are stored using the External interface.
To handle the storage of User Preferences:
void SetUserPreference(string companyId, string userId, string id, string value)
Description |
Used to set a particular user preference value. The id is a unique identifier for the user preference, and the value is the user preference value (may be null). |
Remark |
Should not return any value. |
string GetUserPreference(string companyId, string userId, string id)
Description |
Used to retrieve the value parameter of most recent SetUserPrefernce call for the companyId and userId. |
Remark |
Returns a string |
A server in one time zone may be utilized by users around the globe. This presents problems when handling functions that run on the server such as Now(). There are two ways to handle such a situation: Use the Server Time Zone Offset or Time Zone Name (v2019.1+) Culture Settings, or use the external interface functions below.
For these functions to be called the Sever Time Zone Offset setting must be left blank.
DateTime ConvertToServerDateTime(string companyId, string userId, DateTime clientDateTime)
Description |
Used to adjust clients time to server's time zone. |
Remark |
Returns a DateTime. |
DateTime ConvertToClientDateTime(string companyId, string userId, DateTime serverDateTime)
Description |
Used to adjust server time to client's time zone. |
Remark |
Returns a DateTime. |
To utilize an external interface for time zone conversions, the external time zone converter flag must be enabled in both the web configuration (PageInfo.SetupData.General.UserExternalTimeZoneConverter) and the Scheduler (Config.UseExternalTimeZoneConverter).
These functions utilize the Instant and LocalDateTime classes of the Noda Time library. The Instant class represents a global, linear time in seconds. It does not map onto any calendar system and does not consider DST. The LocalDateTime class represents a point in time of a particular IANA time zone. These values can be mapped onto a calendar system and can take DST into consideration. The system operates using Instants while users operate in the LocalDateTime of their legislative time zone of residence.
Note: Please see the Time Zone Enhancements in v2019.1 article as well as the Noda Time documentation for an in-depth discussion on time zone calculations.
TZConverterExternal.GetInstant(LocalDateTime localDateTime)
Description |
Converts the computed LocalDateTime of the client's time zone to an Instant. |
Remark |
Returns an Instant. |
TZConverterExternal.GetInstant(Instant instant)
Description |
Converts an Instant to the LocalDateTime of the client's time zone. |
Remark |
Returns a LocalDateTime. |
Through the external interface, the Exago Scheduling Service can retrieve email distribution groups from the host application. This prevents having to maintain separate lists of email addresses within Exago.
When a report is scheduled, a call out is made to the host application to get the list of email addresses and distribution groups for the user to select from. This is done with the following method.
string GetEmailListXml(string companyId, string userId)
Description |
Returns a string listing folders and report names in xml format (see example). |
Remark |
Leave the tag <email> blank for an entry to indicate it is a distribution group. |
Example |
<emailAddressList> <item> <name>John Smith</name> <email>jsmith@mycompanydomain.com</email> </item> <item> <name>Sales Group</name> <email></email> </item> </emailAddressList> |
If a scheduled report uses a distribution list then the following method will be called at the time the report is executed.
string GetEmailDistributionListXml(string companyId, string userId, string listName)
Description |
Returns a string listing folders and report names in xml format (see example). |
Remark |
Do not leave the <email> tag blank. The name item does not need to be returned for this method. |
Example |
<emailAddressList> <item> <email>jsmith@mycompanydomain.com</email> </item> <item> <email>ajones@mycompanydomain.com</email> </item> </emailAddressList> |
To utilize the Custom Scheduler Recipient Window feature the following function may exist in the External Interface. See Custom Scheduler Recipient Window for more information.
string GetEmailList(string controlData)
Description |
Sends the external interface the Control Data previously provided by host application when a user clicks OK in the Custom Scheduler Recipient window. |
Remark |
Returns a string of email addresses separated by commas or semi colons. |
To use the 'userEmail' parameter as a "Reply To" email address (v2018.2+), the Regular Expressions namespace should also be added to the code:
using System.Text.RegularExpressions;
The following code should be added as a member of the class:
private static Regex emailRegex = new Regex(@"^[\w\!#\$%\&'\*\+/=\?\^_`{|}~\-]+[\w\._\-\&\!#\$%'\*\+/=\?\^`{|}~\\\:]*[\w_\-\&\!#\$%'\*\+/=\?\^`{|}~\\\:]*@(?:[\w\-]+\.?)*[\w]\.[a-zA-Z]{2,63}$");
This method should be added in the class:
private bool IsValidEmail(string email){ Match emailMatch = emailRegex.Match(email); return emailMatch.Success; }
Finally, this code should be added to the GetEmailList method:
else if (this.IsValidEmail(controlData))
list.Add(controlData);
Example Code:
public List<string> GetEmailList(string companyId, string userId, string controlData) { List<string> list = new List<string>(); if (controlData == "Rendezvous with Rama") list.Add("rama@rendezvous.com"); else if (controlData == "Starship Troopers") list.Add("troopers@starship.com"); else if (this.IsValidEmail(controlData)) list.Add(controlData); else list.Add("person@mail.net"); return list; }
For more information on the "Reply To" address, please see the Scheduler Reply To Address article.
When Email Scheduled Reports is set to False in the Administration Console the following method will call the External Interface to let the host application know when a scheduled report has been saved in the Scheduler Repository.
See Saving Scheduled Reports to External Repository for more information.
void ScheduledReportExecutionComplete(string companyId, string userId, string reportName, string exportFileName, int statusCode, string statusMsg)
Description |
Sends the external interface a notification that a scheduled report has been saved to the Scheduler Repository. |
Remark |
statusCode is 0 if the execution was successful, 1 if an error occurred or no data qualified. statusMsg details the result of the execution (eg. "Report has successfully executed", or "There were errors in the report layout; please edit or contact your administrator"). Return value is void. |