Configuring EIAs Using EIA Widget

<< Click to Display Table of Contents >>

Navigation:  Enterprise > EQuIS Information Agents >

Configuring EIAs Using EIA Widget

Create New EIA – Step 1: Open EIA Editor

Create New EIA – Step 2: Select EIA Type

New Data (EDD)

Once Option

Recurring Events or Schedules

Daily Schedule

Weekly Schedule

Monthly Schedule

Create New EIA – Step 3: Select Report

Create New EIA – Step 4: Select Delivery Method

Notice (Web/Email) Configuration

Webhook Configuration

Editing an Existing EIA

 

 

EQuIS Information Agents (EIAs) can be created and edited in the EIA widget. New EIAs are created using the EIA Wizard as described in this article. Existing EIAs can be edited using the EIA Editor.

 

Each EIA is assigned a unique REPORT_EVENT_ID in the ST_REPORT_EVENT table when the EIA is created. The EIA REPORT_EVENT_ID value is displayed before the associated report name for the existing EIAs.

 

The EIA will run the selected report and send the information according to the EIA type and settings. Some settings allow the report to run multiple times, depending on a set schedule or other factors. Note that if the report was supposed to have run at least one time during a period of time, but did not for some reason (such as report generation was disabled in the Workflow Widget properties for that day or time of day), the report will run one time for all the missed times.

 

Notes:

Existing EIAs may only be edited by the original creator of the EIA or by an Administrator.

Only user reports created by EQuIS Enterprise users (whether in EQuIS Professional or Enterprise) will work with EIAs.

If the original EIA creator needs to be disabled, the user ID associated to the EIA can be changed in ST_REPORT_EVENT.USER_ID to point to an active and licensed user.

For clients using EQuIS Online (hosted), EIA execution times are always in Coordinated Universal Time (UTC).

 

 

Create New EIA – Step 1: Open EIA Editor

 

Open the EIA Wizard by selecting the Create New Ent-EIA_Wizard_create_new icon in the upper left corner of the EIA widget.

ent-eia_widget-create_eia_zoom50

 

Select the EIA type from the drop-down menu and click Next.

 

Ent-EIA_Widget-New_EIA

 

 

Create New EIA – Step 2: Select EIA Type

 

Choose which type of agent to use and configure the EIA settings. Select from:

New Data (EDD)

Once

Daily Schedule

Weekly Schedule

Monthly Schedule

 

Ent-EIA_Wizard-EIA_Types

 

Scheduling Note: Agents are not guaranteed to run at the exact time they are scheduled. The "Workflow Heartbeat" agent runs every minute (by default) and queues Report Generate tasks when an agent should have run at least once since the last time the schedule was evaluated. The report is not actually run until the "Report Generate" agent processes that entry in the queue. Even under ideal conditions, it could be several minutes before the report is actually run. Also, If EQuIS Enterprise Workflow is down for several days then resumes operation, an agent that may have been scheduled to run several times during the outage will be queued to run only once when the operation resumes.

 

New Data (EDD)

 

This EIA sends a report when a new EDD arrives. There is a short delay of approximately 15 minute between when an EDD is loaded into the database and when an EIA may report on that event. At run time, the values for FACILITY_ID and EBATCH from the EDD are passed to the report, replacing the parameter values saved with the report.

 

After the New Data (EDD) option is selected, the agent can be configured to further limit what EDD information is applicable to the report by selecting any of the following settings. Click Next to select the report.

Ent-EIA_Widget-New_Data_Settings

EDDs facility must match Report's facility – If this setting is checked, then the agent will only run if the EDD was loaded to a facility that equals the facility identified in the report's FACILITY_ID parameter or is a member of the group identified by the report. If the report has no FACILITY_ID parameter, the value may be set in the ST_USER_REPORT.FACILITY_ID database field for the report.

Limit report to only data within the EDD (i.e., new data) – If this setting is checked, the generated report will be limited to the data from the submitted EDD. If it is unchecked, the report will be run according to the report parameter settings. This is performed by passing the EDD's ebatch number to the report's EBATCH parameter. If unchecked, the value -1 is passed to the report. The report must support this feature by interpreting -1 to mean that this parameter should be ignored. When this box is unchecked, the generated report will display all data in the EQuIS database and incoming EDD matching the previously defined criteria.

Note: The Limit report to only data within the EDD (i.e. new data) option MUST be selected for "by EDD" reports (e.g., Analytical Results by EDDs) to run as an EIA and return results ONLY from that submitted EDD.

Limit EIA by EDD Format – If this setting is checked, the "New Data" EIA will be limited to a specific EQuIS EDD format.  When a new EDD is loaded via Enterprise EDP, the EIA will only be triggered when the EDD type (ST_EDD_BATCH.EDD_TYPE) matches the format name (ST_REPORT_EVENT.FORMAT_NAME) as specified in the drop-down selection.  

Limit agent to EDDs from user – Allows users with Administrator permissions to limit an EIA to only run when a specific user submits an EDD.

Only trigger EIA if the following report returns results – Allows definition of a secondary "Trigger Report" to determine if the waiting report, identified on the Data tab, should be run. When an EDD is loaded, the "Trigger Report" is run and limited to only data within the EDD. If the "Trigger Report" returns any results, then a task is created to generate the waiting report. If the "Trigger Report" does NOT return any results, then the waiting report is not run. Since using an existing report as the "Trigger Report" runs the risk of parameters being changed elsewhere, you will need to create a new report to use for this purpose.

To define the "Trigger Report", perform the following steps:

1.Select the type of report from the Define Trigger drop-down list. One option is "Report triggers itself." If this selection is made, no other steps are needed.

2.In addition to the "Report triggers itself" option, a list of available user reports will be displayed. Select the desired report.

 

Note: The list of available user reports contains all users reports for which a user has permission and the base report has the MAY_TRIGGER_OTHERS_YN field set to “Y” in the ST_REPORT table.

 

Once Option

 

This EIA sends the report once (and has no recurring event or schedule). This option is useful for generating long running reports that would cause the web browser to abort before completion. There is no auto-delete to remove these agents once the report is generated and delivered.

 

After the Once option is selected, the agent can be configured to schedule the EIA. Click Next to select the report.

Ent-EIA_Wizard-EIA_Once

Begin schedule on – This is the date and time the schedule will begin to run. This will default to the current date and time. The date/time may be edited using the calendar tool or by entering the date/time manually in the text box. Click the calendar tool icon Ent-Calendar-Icon to use the calendar tool. Note that when entering the date manually in the text box, the date must be in the same format as the current default date. Changing the value in the text box will also update the calendar tool. The calendar shows the selected date highlighted in blue and today's date highlighted in gray. If Today's date is selected in the calendar tool, it will remain highlighted in blue. To select a different month or year using the calendar control, click on the name of the month or the arrow pointing forward at the top of the control. This changes the calendar tool from the month view to the year view. Once in the year view, scroll through the available years as desired. The current selected month will be highlighted in blue. Select the desired month/year combo to return to the month view to pick a specific date. Scroll in the Time pane to select the desired time. Click the Done button to save the selected date and time.

 

 

Recurring Events or Schedules

 

Note: The time displayed in Begin schedule on (above) is the time that will be used for determining when events will recur.

 

Daily Schedule

 

Use this EIA type to schedule reports on a daily recurrence. Daily recurrences can occur every day or every N days. Daily recurrence schedules may also include a time base recurrence to schedule the report to run multiple times during the day. Once configured, click Next to select the report.

Ent-EIA_Wizard-EIA_Daily

Daily Schedules are configured as:

Repeat after every ____ day(s)Entering a positive integer value will result in a schedule that starts at "Begin schedule on" and repeats every N days.

Stop Schedule On – The date/time when the recurrence should end. This field is enabled when End Date is selected (slider is to the right). When End Date is off (default), the recurrence has no end.

Repeat during the day – Schedule the agent to run more than once per day by enabling this option (move slider to the right).

Repeat after every – These fields are enabled when the 'Repeat during the day' option is on. When enabled, the valid range of values is 0 to 23 hours and 0 to 59 minutes.

Note: If both the repeat after every hour and minutes text boxes are left blank, repeat after every one minute is assumed.

Repeat during the day until – This option is enabled when the 'Repeat during the day' option is on. The hour portion of the time field is corrected from UTC and may represent a time either on the previous day or the following day. The end time must be after "Start Time." The end time will be 11:59 PM or 23:59, local time, by default.

 

Weekly Schedule

 

Use this EIA to create a recurring schedule that repeats on a weekly basis. Once configured, click Next to select the report.

Ent-EIA_Wizard-EIA_Weekly

Weekly schedules are configured as:

Repeat after every ___ week(s) Define a schedule that runs every N weeks. If left blank, then the value one (1) is assumed.

On the following days Check the box for the day(s) of the week that the agent should run. At least one day must be selected.

Stop Schedule On – The date/time when the recurrence should end. This field is enabled when End Date is selected (slider is to the right). When End Date is off (default), the recurrence has no end.

Repeat during the day – Schedule the agent to run more than once per day by enabling this option (move slider to the right).

Repeat after every – These fields are enabled when the 'Repeat during the day' option is on. When enabled, the valid range of values is 0 to 23 hours and 0 to 59 minutes.

Note: If both the repeat after every hour and minutes text boxes are left blank, repeat after every one minute is assumed.

Repeat during the day until – This option is enabled when the 'Repeat during the day' option is on. The hour portion of the time field is corrected from UTC and may represent a time either on the previous day or the following day. The end time must be after "Start Time." The end time will be 11:59 PM or 23:59, local time, by default.

 

Monthly Schedule

 

Use this EIA to create a recurring schedule that repeats on a monthly basis for every calendar month that is selected. The monthly schedule may also be used for yearly or quarterly recurrence. Once configured, click Next to select the report.

Ent-EIA_Wizard-EIA_Monthly

Monthly schedules are configured as:

Months – Select the months that the recurrence may be scheduled. At least one month must be selected.

On Week of Month – Allows a schedule to be setup on a specific week of the month. Note that selecting the "5th" week of a month will not be applicable to every month and the schedule may not run these months.

On Calendar Day – Schedule the agent to run on the specified date of the month. This option is mutually exclusive with the "On Week of month" option. Note that some calendar days are not applicable to every month (such as February 30 or 31) and the schedule will not run on these days.

Stop Schedule On – The date/time when the recurrence should end. This field is enabled when End Date is selected (slider is to the right). When End Date is off (default), the recurrence has no end.

Repeat during the day – Schedule the agent to run more than once per day by enabling this option (move slider to the right).

Repeat after every – These fields are enabled when the 'Repeat during the day' option is on. When enabled, the valid range of values is 0 to 23 hours and 0 to 59 minutes.

Note: If both the repeat after every hour and minutes text boxes are left blank, repeat after every one minute is assumed.

Repeat during the day until – This option is enabled when the 'Repeat during the day' option is on. The hour portion of the time field is corrected from UTC and may represent a time either on the previous day or the following day. The end time must be after "Start Time." The end time will be 11:59 PM or 23:59, local time, by default.

 

 

Create New EIA – Step 3: Select Report

 

Select the report for the EIA using the Report Chooser. After the report is selected, a button for the Report Parameter Editor will appear.  Make any necessary selections or changes to the report,and  then click Next.

 

Ent-EIA_Wizard-EIA_Report_Chooser

 

 

Create New EIA – Step 4: Select Delivery Method

 

Either enter information for the Notice (Web/Email) that will be used when the EIA sends the notification email OR configure a Webhook as the notification method (see below). Select the desired option and configure settings as appropriate. Once completed, click the Save Changes and Close Ent-Widget_Save-Icon icon to finish creating the EIA.

Ent-EIA_Wizard-EIA_Deliver_Method

Do not create a notice if there are no report results – When this box is checked, a notice will not be created if the EIA runs and no report results are obtained.

Do not send an email to notice recipients – Check this box to turn off notifying EIA recipients by email (restricts EIAs to only web notices).

Delivery Type – Select either Notice (Web/Email) or Webhook.

 

 

Notice (Web/Email) Configuration

Ent-EIA_Wizard-EIA_Delivery_Method_Notice

To – Enter a comma-separated list of email addresses. This field will be pre-populated with the email address of the current user. The email addresses may be other users, but are not required to be. If you enter an email address that does not exist as a user, that user will be created as a Limited User.

Subject – Enter the subject of the notice/email. See Replacement Tags below for additional information.

Attachment – Enter the file name for the attachment and select the desired file type. See Replacement Tags below for additional information.

Output Type – Select output type for the report from the drop-down options.

Message – Enter the body of the notice/email. See Replacement Tags below for additional information.

Replacement Tags – The Subject, Attachment, and Message may contain replacement tags that will be replaced with the run time values.

 

Webhook Configuration

 

An EQuIS webhook is a type of EIA that connects to an external Web service, such as Microsoft Power Automate or Logic Apps. Whenever an EIA trigger event occurs (scheduled or new data load), the webhook makes an HTTP request to the URI configured in the webhook. The body of the webhook can be configured to populate with report data.  All report output for webhook EIAs will be formatted as JSON.

Ent-EIA_Wizard-EIA_Delivery_Method_Webhook

HTTP Method – (Required) Select the HTTP method as required by the external web service.  GET and POST are supported.

URI – (Required) Enter the URI of the external web service. An error message will be displayed beneath the URI field if the URI is invalid (i.e., does not begin with http:// or https://, followed by a domain name, and lastly a top level domain. The Save button will also be disabled until a valid URI is entered.

Headers – (Required) A content-type header of application/json is required. Example:  Header = Content-Type Value = application/json.

To paginate report output, set the Content-Range header equal to the page size.

Example: Content-Range: 100

This will result in the report output being broken up into pages of 100, and each hook request being sent separately with a Content-Range header in the following format "rows x-y/z", where z is the total number of rows in the report, and x and y are the lower and upper bound of the rows in the request.

 

Note: When opening the editor for a webhook EIA, an "Authorization" header Key field will always display the Authorization value as null for security purposes.

 

Body – Enter custom message. If left empty, the body will be the EIA's report output.  

Edits can be made via either the Plaintext mode or the JSON Editor component, which allows JSON validation in the body of a webhook EIA.  The text within each mode is not synchronized and it is recommended to avoid switching modes while editing.

All EIAs will initially load in Plaintext mode and the user will need to manually copy over any body text that the user wishes to validate in the JSON editor.

 

When using JSON to configure the body of a webhook, it is possible to set the JSON "data" property value to "DATA_ROW_ARRAY". This will set the "data" property to the EIA's report output.

 

Example:

{  "template": {     "name":"my-jsreport-template"   },  "data": "DATA_ROW_ARRAY"}

 

The "data" JSON property is the most used, however, certain software may use other naming conventions for their data property (e.g., "rows" instead of "data" for Power BI). This may result in negative consequences if the "data" property uses "DATA_ROW_ARRAY" for the naming convention instead of “data” (e.g., "DATA_ROW_ARRAY":"DATA_ROW_ARRAY").

 

Notes:

The Hook Process Agent must be running for Webhook EIAs to process. A Webhook EIA that fails to run will have three opportunities to succeed before it is marked as a failure and a notice is sent to the user that created the Webhook EIA.

If a Webhook EIA fails to receive a successful response from the target resource, an email notice will be sent to the user stating "Hook not delivered. Invalid permissions.". Two potential causes of this are invalid user credentials to the hook's target resource or incorrect permissions configured for the user authenticating the request to the hook's target resource.

 

 

Editing an Existing EIA

 

To edit an EIA, select the desired EIA (row in the grid) from the widget. The row will be highlighted in blue, and the Edit Ent-Edit_Icon icon at the top of the grid will be enabled. Click the Edit Ent-Edit_Icon icon to open the EIA Editor window for the selected report. See the the EIA Editor article for more details.

ent-eia_widget-edit_eia_zoom50