Build your first custom page

This tutorial illustrates how to create a simple custom page available from an external tab in Relativity. It describes how to complete the following tasks:

  • Add references to your Visual Studio project.
  • Write the source code for a custom page.
  • Package the custom page files.
  • Add the custom page to an application.
  • Create an external tab for displaying it in Relativity.

Your completed custom page displays your name and the current time in the Relativity UI.

This page contains the following information:

Before you begin

Complete the following tasks to before you begin implementing a custom page:

Build a custom page

Note: The following example is based on MVC4. You can also use MVC5, WebApi2, or other frameworks supported under IIS and .NET 4.6.2.

Use these steps to build a simple custom page:

  1. In Visual Studio, create a new project using the Relativity Custom Page MVC4 template.

    dialog for creating a web application

  2. Add references to the following SDK libraries to the project:
    • %PROGRAMFILES%\kCura Corporation\Relativity SDK\Custom Pages\Client\Relativity.CustomPages.dll
    • %PROGRAMFILES%\kCura Corporation\Relativity SDK\Services API\Client\kCura.relativity.Client.dll
    • %PROGRAMFILES%\kCura Corporation\Relativity SDK\Relativity API\Lib\Relativity.API.dll
  3. Under Controllers, update HomeController.cs using this sample code:
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Web;
    using System.Web.Mvc;
    using Relativity.API;
    using Relativity.CustomPages;
    using kCura.Relativity.Client;
    
    namespace HelloUser.Controllers
    {
        public class HomeController : Controller
        {
            public ActionResult Index()
            {
                try
                {
                    //Get the user's first and last name with Relativity API Helpers
                    String firstName = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.FirstName;
                    String lastName = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.LastName;
    
                    //Get the current time
                    String currentTime = DateTime.Now.ToLongTimeString();
    
                    //Set the text value        
                    String helloStr = String.Format("Hello {0} {1}! The current time is: {2}",
                                firstName,
                                lastName,
                                currentTime);
    
                    //Set message
                    ViewBag.Message = helloStr;
                }
                catch (Exception Ex)
                {
                    Console.WriteLine(Ex.Message);
                }
    
                return View();
            }
    
        }
    }
    
  4. Under Views > Home, update Index.cshtml as follows:
    @{
        ViewBag.Title = "Index";
    }
    
    <h2>@ViewBag.Message</h2>
    
  5. Make sure the RouteConfig.cs under App_Start points to the correct view:
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Web;
    using System.Web.Mvc;
    using System.Web.Routing;
    
    namespace HelloUser
    {
        public class RouteConfig
        {
            public static void RegisterRoutes(RouteCollection routes)
            {
                routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
    
                routes.MapRoute(
                    name: "Default",
                    url: "{controller}/{action}/{id}",
                    defaults: new { controller = "Home", action = "Index", id = UrlParameter.Optional }
                );
            }
        }
    }
  6. Publish the project using a custom profile to an arbitrary location on the file system:
    1. Right-click on your MyFirstProvider web project and click Publish.

      Publish option in Visual Studio 2015

    2. Highlight Profile in the sidebar, and click Custom.
    3. Enter a name in the Profile name box. Click OK.

      defining a custom profile

    4. In the Publish Method drop-down box, select File System.
    5. Click ellipsis button to set the Target location for your published files.

      selecting a publish method

      Note: Make sure not to overwrite any of your project files when specifying the target location. If publishing to the project directory, select a subdirectory.

    6. Click Next and select Release from the Configuration drop-down box.
    7. Under File Publish Options, click Delete all existing files prior to publish.

      adding configuration settings

    8. Click Publish.
    9. Navigate to the directory where you choose to publish your web application.
    10. Add the contents of the parent directory to a .zip file. (Don't add the parent directory to this file.)

      adding web project to compressed file

  7. Deploy your custom page as described in the next section.

Deploy a custom page

To deploy a custom page:

  1. Open the Relativity instance used for development.
  2. Create a new workspace called Basic Samples.
  3. Open the Relativity Applications tab and then click the New Relativity Application button. Add your new custom page to the application that you create in the workspace.

  4. In Application Type field, click Create new Application.
  5. In New Application Name field, enter Basic Samples Application.
  6. Click Save to display the detail view of the application.
  7. In the Custom Page associative list, click New to display a form for adding an new instance of the custom page.

    New button on Custom Page associative list

  8. In the Name field, enter Basic Samples Custom Page.

    dialog for adding a new custom page

  9. In the File field, click Browse to upload your compressed archive created in step 12.
  10. In the Relativity Applications field, click ellipsis button to select the application that you created.
  11. Click Save to display the detail view of your custom page. It lists a base URL for the custom page. You can use this URL to link your page to a tab In Relativity. Copy this link for use in step 27.

    detail view of a custom page displaying its base URL

  12. In the Tab section of the application details view, click New to display a form for adding a tab.

    dialog for creating a new tab

  13. In the Name field, enter My Custom Page.
  14. Select External as the Link Type.
  15. In the Link field, paste the base URL for your custom page generated in step 23. Append Default.aspx to it. Your link uses the following format, which includes the GUID for your application:
    %applicationPath%/CustomPages/<YourRelativityApplicationGUID>/Home/Index

    This string illustrates how to use the %applicationPath% as replacement key in this string. Relativity automatically replace this key with the correct value. For other keys that you can use in URLs, see Use external tabs as links to custom pages.

  16. Click Save > Back.
  17. To add your application to the Application Library, click Push to Library in the console on the application details view.

    You must add your application to the Application Library stored on the EDDS database before you can deploy your page. After the application exists in the library, the Custom Page Deployment Manager agents detect the new entry. They deploy the pages to the appropriate area on the web server. They also set the required IIS settings to ensure your application is configured and ready to receive requests.

    Push to Library button on Relativity Application console

  18. Click the My Custom Page tab to view your custom page. You may need to wait several minutes for the agents to deploy the pages so that your custom page is visible.

    sample custom page