As part of the Relativity Services API (RSAPI) Deprecation, content on this page referring to the RSAPI and the Patient Tracker application is in the process of being deprecated and will no longer be supported. For more information and alternative APIs, see RSAPI deprecation process.

Console event handlers

Note: Console event handlers are ignored when your object type is using Relativity Forms, but the same functionality can achieved within Relativity Forms. For more information, see Relativity Forms API.

Console event handlers execute when a user clicks a console button in Relativity. The details view of an object may display a console, which contains header text and a button collection. When a user clicks a button, a call is made to a method in the event handler that contains the business logic for a specific task. In Relativity, the console has a GetConsole() method that returns a Console event handler. Console event handlers support custom HTML elements. You can use them on Relativity Dynamic Objects.

You can use a console event handler to control the workflow of a job or project. For example, you may expose buttons to insert a job into a queue table for background processing by an agent. Next, you may also want to track the progress of the job. You can display a link in the console so users can review errors if they occur. After resolving the errors, users can resubmit the job.

This page contains the following information:

Guidelines for Console event handlers

Use these guidelines when developing Console event handlers:

  • Create a new class in Visual Studio.

    Note: You can also use a template to create this event handler type. For more information, see Visual Studio templates.

  • Add NuGet packages - ensure your Visual Studio project has installed the relevant NuGet packages, including at a minimum the Relativity.EventHandler and Relativity.Api packages.
  • Add a GUID for the event handler - set the System.Runtime.InteropServices.Guid to the GUID identifying your event handler. Use the GUID generator in Visual Studio.
  • Set the CustomAttributes.Description attribute - provide a description that you want to appear in the Relativity UI for the event handler.
  • Inherit from the ConsoleEventHandler class – extend the ConsoleEventHandler base class.
  • Override the GetConsole() method – returns a console containing buttons and header text.
  • Override the OnButtonClick() method – executes when a button click is detected.
  • Override the RequiredFields property – returns a collection of fields that you need to access. The current layout doesn't need to include the fields .

    Note: The ActiveArtifact.Fields collection includes the fields returned by the RequiredFields property, and those on the current layout. It also includes the values of these fields.

  • Optionally set the CssClass property on the ConsoleButton class – controls the styling used for a console button. If you don't set this property, the default Relativity styles used in console buttons are applied to your new button.
  • Optionally use event handlers to construct HTTP responses - event handlers can't access the request header, cookies, or session information using the HTTPContext object, although they can assisted in constructing an HTTP response.

Code sample for a Console event handler

Review the following code samples for a Console event handler. To download the Patient Tracker application that uses this custom code or to view it in a Visual Studio solution, see Patient Tracker application.

using System;
using System.Collections.Generic;

namespace PatientTracker.EventHandlers
{
    /// <summary>
    /// This event handler creates a console with a button for inserting a job into the PatientProcessingQueue table on the EDDS database.
    /// The Patient Note Processing Agent runs the job that checks the patient note field.
    /// </summary>
    [kCura.EventHandler.CustomAttributes.Description("Patient Console Event Handler")]
    [System.Runtime.InteropServices.Guid("93D7E9F9-A191-4038-B222-F73C51D9A434")]
    class PatientConsoleEventHandler : kCura.EventHandler.ConsoleEventHandler
    {
        private static readonly Guid PATIENT_TRACKER_APPLICATION_GUID = new Guid("b4f52c6c-f55c-488f-ba71-e8ee8b5c74f4");

        private const String CONSOLE_TITLE = "Process Patient Console";

        private const String INSERT_JOB_BUTTON_NAME = "_insertJobButton";
        private const String INSERT_JOB_DISPLAY_TEXT = "Process Patient Notes";
        private const String INSERT_JOB_TOOL_TIP = "Send a job to the Patient Note Processing Agent.";

        private const String PATIENT_PROFILE_BUTTON_NAME = "_insertJobButton";
        private const String PATIENT_PROFILE_DISPLAY_TEXT = "Patient Profile";
        private const String PATIENT_PROFILE_TOOL_TIP = "View the patient profile.";

        private const String JOB_EXISTS_QUERY = "SELECT COUNT(*) FROM [PatientProcessingQueue] WHERE [WorkspaceArtifactID] = @WorkspaceArtifactID AND [PatientArtifactID] = @PatientArtifactID";
        //You want to ensure that there is only one job per patient at any given time.
        private const String INSERT_JOB_QUERY = "IF NOT EXISTS(SELECT TOP 1 * FROM [PatientProcessingQueue] WHERE [WorkspaceArtifactID] = @WorkspaceArtifactID AND [PatientArtifactID] = @PatientArtifactID)"
                + " BEGIN"
                + " INSERT INTO [PatientProcessingQueue] (WorkspaceArtifactID, PatientArtifactID, Status)"
                + " Values (@WorkspaceArtifactID, @PatientArtifactID, 0)"
                + " END";

        public override kCura.EventHandler.Console GetConsole(kCura.EventHandler.ConsoleEventHandler.PageEvent pageEvent)
        {
            //Construct a console object to build the console appearing in the UI.
            kCura.EventHandler.Console returnConsole = new kCura.EventHandler.Console();
            returnConsole.Items = new List<kCura.EventHandler.IConsoleItem>();
            returnConsole.Title = CONSOLE_TITLE;

            //Construct the submit job button.
            kCura.EventHandler.ConsoleButton submitJobButton = new kCura.EventHandler.ConsoleButton();
            submitJobButton.Name = INSERT_JOB_BUTTON_NAME;
            submitJobButton.DisplayText = INSERT_JOB_DISPLAY_TEXT;
            submitJobButton.ToolTip = INSERT_JOB_TOOL_TIP;
            submitJobButton.RaisesPostBack = true;

            //Construct the patient profile button.
            kCura.EventHandler.ConsoleButton patientProfileButton = new kCura.EventHandler.ConsoleButton();
            patientProfileButton.Name = PATIENT_PROFILE_BUTTON_NAME;
            patientProfileButton.DisplayText = PATIENT_PROFILE_DISPLAY_TEXT;
            patientProfileButton.ToolTip = PATIENT_PROFILE_TOOL_TIP;
            patientProfileButton.RaisesPostBack = false;
            patientProfileButton.Enabled = true;

            //If a job is already in the queue, change the text and disable the button.
            if (pageEvent == PageEvent.PreRender)
            {
                System.Data.SqlClient.SqlParameter workspaceArtifactIDParam = new System.Data.SqlClient.SqlParameter("@WorkspaceArtifactID", System.Data.SqlDbType.Int);
                workspaceArtifactIDParam.Value = this.Helper.GetActiveCaseID();

                System.Data.SqlClient.SqlParameter patientArtifactIDParam = new System.Data.SqlClient.SqlParameter("@PatientArtifactID", System.Data.SqlDbType.Int);
                patientArtifactIDParam.Value = this.ActiveArtifact.ArtifactID;

                int jobCount = this.Helper.GetDBContext(-1).ExecuteSqlStatementAsScalar<Int32>(JOB_EXISTS_QUERY, new System.Data.SqlClient.SqlParameter[] { workspaceArtifactIDParam, patientArtifactIDParam });

                //Use the helper function to check if a job currently exists. Set Enabled to the opposite value.
                if (jobCount > 0)
                {
                    submitJobButton.Enabled = false;
                }
                else
                {
                    submitJobButton.Enabled = true;
                }

                //Get the base path to the application.
                String basePath = this.Application.ApplicationUrl.Substring(0, this.Application.ApplicationUrl.IndexOf("/Case/Mask/"));

                //Construct the path to the custom page with the current patient artifact id and current workspace.
                String patientProfilePageUrl = String.Format("{0}/CustomPages/{1}/Patient/Index/?patientArtifactID={2}&workspaceArtifactID={3}", basePath, PATIENT_TRACKER_APPLICATION_GUID, this.ActiveArtifact.ArtifactID, this.Helper.GetActiveCaseID());

                //Create the JavaScript for the button and set the button property.
                String windowOpenJavaScript = String.Format("window.open('{0}', '', 'location=no,scrollbars=yes,menubar=no,toolbar=no,status=no,resizable=yes,width=300,height=400');", patientProfilePageUrl);
                patientProfileButton.OnClickEvent = windowOpenJavaScript;
            }

            //Add the buttons to the console.
            returnConsole.Items.Add(submitJobButton);
            returnConsole.Items.Add(patientProfileButton);

            return returnConsole;
        }

        public override void OnButtonClick(kCura.EventHandler.ConsoleButton consoleButton)
        {
            //Use the name to determine which button was clicked. 
            switch (consoleButton.Name)
            {
                case INSERT_JOB_BUTTON_NAME:
                    //The user clicked the button for the insert job so add the job to the queue table on the EDDS database.
                    System.Data.SqlClient.SqlParameter workspaceArtifactIDParam = new System.Data.SqlClient.SqlParameter("@WorkspaceArtifactID", System.Data.SqlDbType.Int);
                    workspaceArtifactIDParam.Value = this.Helper.GetActiveCaseID();
                    System.Data.SqlClient.SqlParameter patientArtifactIDParam = new System.Data.SqlClient.SqlParameter("@PatientArtifactID", System.Data.SqlDbType.Int);
                    patientArtifactIDParam.Value = this.ActiveArtifact.ArtifactID; ;

                    this.Helper.GetDBContext(-1).ExecuteNonQuerySQLStatement(INSERT_JOB_QUERY, new System.Data.SqlClient.SqlParameter[] { workspaceArtifactIDParam, patientArtifactIDParam });

                    break;
            }
        }

        /// <summary>
        /// You don't need access to any specific field on patient and you can return an empty list.
        /// </summary>
        public override kCura.EventHandler.FieldCollection RequiredFields
        {
            get
            {
                kCura.EventHandler.FieldCollection retVal = new kCura.EventHandler.FieldCollection();
                return retVal;
            }
        }
    }
}

Additional Resources

DevHelp Community GitHub Release Notes NuGet

Share knowledge with the Relativity developer community.

Access tools and resources to build an application.

Review the most recent product release notes.

Create .NET Apps faster with NuGet.