# External Interface

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:

1. Create a Web Service or .Net Assembly that contain the functions described below.
2. Specify the Web Service or .NET Assembly in the External Interface property of Other Settings.

> 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.

# Report Execution Start Event

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.

# User Preference Management

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:

1. In the User Settings, set User Preference Storage Method to “External Interface”
2. Implement the following methods:

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

# Handling Time Zones

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 Culture Setting, Server Time Zone Offset, or use the external interface functions below.

> NOTE. For these functions to be called the Culture setting Sever Time Zone Offest must be 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.

# Email List for Report Scheduling

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>

# Custom Scheduler Recipient Window

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.

# Scheduler Repository Notification

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.