Institutional Profiles

This tutorial shows you how to add a selector UI element to enable selection of another institution's IRB Exchange account from an institutional profile, essentially performing a lookup in a directory of accounts on the IRB Exchange site.

Background

To support multi-site research, Huron IRB uses a custom data type called IRB Institutional Profile to represent the other organizations (outside institutions) that are involved. Among many other data elements, these key pieces of data elements are tied together in the institutional profile (IP):

  • The contacts in your store that represent the staff members of the external IRB, which is crucial for making sure the external IRB receives the email notifications you configure in your store to notify them of invitations to participate in studies and other data that you have made available on the IRB Exchange.
  • The external IRB's account on the IRB Exchange, which you must supply to set up appropriate security when exchanging data with the external IRB.

This tutorial shows you how to enable selection of an IRB Exchange account by name from an institutional profile, or from a similar type that you create, using a supplied Site Designer page.

What's Involved

Adding the account selector involves three pieces:

  1. Adding a string attribute to your institutional profile type for temporarily storing an IRB Exchange account ID to be used by the form handler in post-processing for linking an IP to an IRB Exchange account.
  2. Creating the Site Designer page wrapper for the IRB Exchange account selector Site Designer page provided by the Huron Portal IRB Client Library.
  3. Adding a SymLink to your Site Designer page.
  4. Adding a method to your Institutional Profile type that returns the IRB Exchange account ID for the linked IRB Exchange account on the store's default IRB Exchange endpoint.

Creating the Site Designer Page

The Site Designer page you create should have two elements:

  1. Page.bindToEntities script
  2. SymLink to IRB Exchange account selector

Page.bindToEntities Script Example:

function bindToEntities(sch)
{
    var ce = sch.currentEntity();
    if(ce == null) {
        return null;
    }
    var org = ce.getQualifiedAttribute("customAttributes.institution");
    return org;
}

In this example, the attribute path "customAttributes.institution" refers to the attribute on your institutional profile type that references the Organization in your store that represents the institution.

For the SymLink, you can simply drag the Site Designer page Applications:/IrbExchange/AccountChooser onto your Site Designer page to create a standard SymLink to it. No staticqs is required for this SymLink.

SymLink HTML Example:

<img _atei_dontuse="Target = Applications:/Irb/IrbInstitutionalProfileIrbExchangeAccountChooser" alt="Applications:/Irb/IrbInstitutionalProfileIrbExchangeAccountChooser" class="group" id="searchresults" layoutid="SymlinkControl:6718E77ED7D97341977E35F0DE0CD382" linktarget="Applications:/Irb/IrbInstitutionalProfileIrbExchangeAccountChooser" staticqs="updateFormField=_ClickIRBInstitutionalProfile.customAttributes.exchangeID&amp;showUnlink=true&amp;showLinkStatus=true" />

In this example, the staticqs attribute has some important metadata used by the Site Designer pages.

  • updateFormField should be set to the fully qualified attribute path to the string attribute you create, starting with the internal type name of your Institional Profile type.
  • showUnlink should be set to true if you want to enable the ability to unlink an Institional Profile from an IRB Exchange account, or false if you would like to disable this ability.
  • showLinkStatus should be set to true to show the link status between the Institional Profile and any linked IRB Exchange account, or that there is no link.

Adding the getExchangeId Method

This method is used for getting the IRB Exchange account ID for the linked IRB Exchange account on the store's default IRB Exchange endpoint. It's used in numerous places in the code related to downloading sites and site modifications, as well as granting access to participating sites.

_ClickIRBInstitutionalProfile.getExchangeId Method Example

/** Gets the Exchange ID of the Exchange account corresponding to this IP and the current endpoint for the store.
 @return (string) Exchange ID of the Exchange account
**/
function getExchangeId() {
    var org = this.getQualifiedAttribute("customAttributes.institution");
    var endpoint = IrbExchange.GetDefault().GetEndpoint() + "";
    return IrbExchangeReference.GetExchangeId(org + "", null, endpoint);
}

Technical note about this method example:

  • Note that this method is getting the endpoint for the store's default IRB Exchange account, not the store's default endpoint.
  • updateFormField should be set to the fully qualified attribute path to the string attribute you create, starting with the internal type name of your institutional profile type.
  • showUnlink should be set to true if you want to enable the ability to unlink an IP from an IRB Exchange account, or false if you would like to disable this ability.
  • showLinkStatus should be set to true to show the link status between the IP and any linked IRB Exchange account, or that there is no link.