Working with Organizations on the IRB Exchange

In this tutorial, we'll show how to work with Organizations on the IRB Exchange using the .NET client library. This assumes you have already setup an ASP.NET Core web application as described within the Setting Up ASP.NET Core Web Application to Integrate with IRB Exchange tutorial.

This tutorial will cover the following Organization operations:

  • Listing Organizations
  • Finding Organizations
  • Retrieving an Organization's Certificate

Setting Up ASP.NET Core MVC Controller

Since we are working within an ASP.NET Core web application, we will need to create a new Controller which will be responsible for making requests to the IRB Exchange using the ExchangeClient. The information being returned by the IRB Exchange will then be rendered into an html page using Razor.

  1. Right click the Controllers folder within the Solution Explorer.
  2. Select Add > New Item...
  3. Select the MVC Controller Class
  4. Name the file OrganizationsController.cs
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;

namespace Example.Exchange.AspNetCore.Controllers
{
    public class OrganizationsController : Controller
    {
        // GET: /<controller>/
        public IActionResult Index()
        {
            return View();
        }
    }
}

To access the IRB Exchange, we need to use the configured ExchangeClient. We can easily get access to it by simply creating a new constructor method and adding the ExchangeClient as a parameter, and a private field to store the reference. The dependency injection system will handle the rest for us.

public class OrganizationsController : Controller
{
    private readonly ExchangeClient exchangeClient;

    public OrganizationsController(ExchangeClient exchange)
    {
        this.exchangeClient = exchangeClient;
    }

    // rest of the file...
}

Listing Organizations

Now let's go ahead and update the Index action method on the OrganizationsController to retrieve the list of organizations. We will then construct a view model and pass that on to our razor page for rendering. Additionally we will switch this to an async method which will improve performance.

  1. Create the Models/Organizations folder within the project.
  2. Add a new class to Models/Organizations and name it ListOrganizationsViewModel.

Models/Organizations/ListOrganizationsViewModel.cs

using Huron.IrbExchange;
using System.Collections.Generic;

namespace IRBExchange.Tutorials.AspNetCore.Models.Organizations
{
    public class ListOrganizationsViewModel
    {
        public List<Organization> Organizations { get; set; }
    }
}

Controllers/OrganizationsController.cs


[HttpGet]
public async Task<IActionResult> Index()
{
    // Make the request to the IRB Exchange
    List<Organization> orgs = await this.exchangeClient.GetOrganizationsAsync();

    // Build the view model
    var viewModel = new ListOrganizationsViewModel
    {
        Organizations = orgs
    };

    // Render the page
    return View(viewModel);
}

Next create a Razor page and render the organizations.

  1. Add a new folder to Views named Organizations.
  2. Right click the Views/Organizations folder.
  3. Select Add > New Item...
  4. Select the MVC View Page
  5. Name the file Index.cshtml

Open the Views/Organizations/Index.cshtml, remove the default boilerplate code and add the following code.

@model IRBExchange.Tutorials.AspNetCore.Models.Organizations.ListOrganizationsViewModel

<h3>Organizations</h3>

@foreach (var org in Model.Organizations) 
{
    <div>
        <h4>@org.Name</h4>
        <div>Id: @org.OrganizationId</div>
        <div>Thumbprint: @org.Thumbprint</div>
        <div>Is sIRB: @org.IsSirb</div>
    </div>
    <hr />
}

There is one last step, and that is to test it out! Hit F5 to start the web app, then go to /Organizations. Something similar to the following should be displayed.

IRB Exchange Organizations

Finding Organizations

Listing all the organizations is useful, but it often more beneficial to find a specific organization. The IRB Exchange allows you to filter the organization list by the providing the name or partial name of an organization. Let's expose this functionality within our web application. We will need to build a form which takes the name of the organization we are looking for, and we will need to modify our controller to send the name to the IRB Exchange.

Building the Form

Add the search form to the Views/Organizations/Index.cshtml

<form asp-controller="Organizations" asp-route="Index" method="post">
    <input type="text" name="organizationName" placeholder="Enter the name of an organization" />
    <button type="submit">Search</button>
</form>

Building the Controller Action Method

Add the following code to Controllers/OrganizationsController.cs. The form variable organizationName will be bound to the parameter with the same name in the action method by the model binding system within ASP.NET Core. We then call the same GetOrganizationAsync method, but this time we pass in our organization name parameter.

[HttpPost]
public async Task<IActionResult> Index(string organizationName)
{
    List<Organization> orgs = await _exchange.GetOrganizationsAsync(search);
    ListOrganizationsViewModel viewModel = new ListOrganizationsViewModel
    {
        Organizations = orgs
    }
    return View(viewModel);
}

Hit F5 to fire up the site and test it out. Type the name or partial name of an organization and click Search. The list should now to filtered to only the organizations that match the specified name.

Retrieving an Organization's Certificate

Retrieving an Organization's certificate is fairly common operation when working with the IRB Exchange, because the certificate is needed whenever you need to grant an organization access to an item. Certificates are typically only used by the application, but we can easily expose some functionality that makes a certificate available as a downloadable file.

First let's create a new action method on our controller.

Controllers/OrganizationsController.cs

[HttpGet]
public async Task<FileResult> DownloadCertificate(string organizationId)
{
    // Get the organization from the IRB Exchange
    Organization organization = await this.exchangeClient.GetOrganizationAsync(organizationId);
    // Get the organization certificate from the IRB Exchange
    X509Certificate2 certificate = await organization.GetCertificateAsync();
    // Convert the certificate into bytes
    byte[] fileBytes = certificate.Export(X509ContentType.Cert);
    // Create a friendly file name using the organization's name
    string friendlyName = organization.Name.Replace(" ", "-").ToLower();
    // Send the file for download
    return File(fileBytes, "application/pkix-cert", $"{friendlyName}.cer");
}

Next, let's expose a link on our view to initiate the download. We will be adding an anchor tag within the loop that renders each of the organizations.

Views/Organizations/Index.cshtml

@model IRBExchange.Tutorials.AspNetCore.Models.Organizations.ListOrganizationsViewModel

<h3>Organizations</h3>

<form asp-controller="Organizations" asp-action="Index" method="post">
    <input type="text" id="search" name="organizationName" />
    <button type="submit">Search</button>
</form>

@foreach (var org in Model.Organizations)
{
    <div>
        <h4>@org.Name</h4>
        <div>Id: @org.OrganizationId</div>
        <div>Thumbprint: @org.Thumbprint</div>
        <div>Is sIRB: @org.IsSirb</div>

        <a asp-controller="Organizations" asp-action="DownloadCertificate" asp-route-organizationId="@org.OrganizationId">Certificate</a>
    </div>
    <hr />
}

Hit F5 to test it out. Click on one of the Certificate links and the certificate file will be downloaded.

Summary

In this article, we created an new web page that lists all organizations that are registered on the IRB Exchange. We also provided a way to filter the set of organizations. Finally, we added functionality to download an organization's public certificate.

Additional Resources