Friday, August 15, 2014

Configuring Global Registration Fields in Extranet Collaboration Manager (ExCM) 2013


Registration is one of the core concepts in Extranet Collaboration Manager 2013. There are two types of registration; Anonymous and Invitation. The most common, by far, are the Invitation Registrations. You send an e-mail to a potential new user, they click on the Registration link provided and they are taken to the custom Registration Page on your site. Here is an example:





This page can be completely customized to capture the data you want from your users.  In the example above, we are capturing the following (field type in parentheses): 

·        First Name (Text) 

·        Last Name (Text) 

·        Company Name (Text) 

·        Job Title (Text)

·        Phone Number (Text) 

·        Zip Code (Text) 

·        Captcha (Captcha) 

·        Site Policy (Policy)

In addition to the field types above, you can also implement the following field types: 

·        Description – Provides a way to enter lines of text for descriptive or informational purposes 

·        Choice – Presents selections as either a drop down, radio button, or checkbox 

There are two ways you can edit the fields that appear on the Registration Page: by Site Collection via the User Interface (UI) and globally via the web.config file.  In most cases, you will want to capture certain fields on every site (First Name, Last Name, Company Name, etc.), so it makes sense to configure those globally and add the more specialized fields (Captcha and Policy) via the UI.  However, what if you were running ExCM on hundreds of sites?  It would be very time consuming to go into each site and configure the additional fields.  In that case, you would want to choose the common fields for ALL your sites and configure them globally.  In this blog, we will look at how to configure all the field types globally via the web.config file. 

First, let’s take a look at the area in the web.config file for the content site where the global Registration fields are declared.  Here is the provided tag example from our help site:

This example includes First Name, Last Name, Company Name, Job Title, and Phone Number by default, and all are of the type “text” marked as “required” with the following elements: 

fieldType="Text"
isRequired="true" 
The “name” of the field (how it will appear on the Registration Page) is declared in this way: 
add fieldName="First Name" 
Now, let’s take a look at how to add the additional field types here in the web.config file so that they are available globally.  First, here are examples of the remaining three types:
Description
<add fieldName="Description" fieldType="Description" description="Enter the characters you see." />
Captcha
<add fieldName="Captcha" fieldType="Captcha" isRequired="true" imageStyle="Basic" />
where imageStyle="Basic\GreenDiagonals\PurplePlaid"
Choice
<add fieldName="State" fieldType="Choice" isRequired="true" displayType="DropDown" options="AL,AK,AS,AZ,AR,CA,CO,CT,DE,DC,FM,FL,GA,GU,HI,ID,IL,IN,IA,KS,KY,LA,ME,MH,MD,MA,MI,MN,MS,MO,MT,NE,NV,NH,NJ,NM,NY,NC,ND,MP,OH,OK,OR,PW,PA,PR,RI,SC,SD,TN,TX,UT,VT,VI,VA,WA,WV,WI,WY" />

Policy
The Policy field is a little more complex because it typically contains HTML content, which is invalid in an XML attribute.  As a result you, we will need to add the policy message content to a resource file (.RESX) and place it in the App_GlobalResources directory of the IIS site.
<add fieldName="Policy" fieldType="Policy" policyLabel="Resources:mycompany,RegistrationField_PolicyLabel" policyMessage="Resources:mycompany,RegistrationField_PolicyMessage" />
We have provided a zipped collection of files for use with Global Policy Fields that can be downloaded from here:
In it, you will find the following files:

Note that I have also used “ACME” in the sample config files to remain consistent with the blog post.  In your case, you will basically want to replace all instances of “ACME” with your company name.
The first is the resource file itself.  This is where we will enter the HTML changes we want to make for the Policy Field. The next is a sample anonymous master page that I will use for this blog.  In my environment, I have Anonymous Access turned off on both my Web App and IIS for this site, so I will need to reference this anonymous master page to allow the users to see the Policy Field.

The third is a text file that simply contains the HTML portion of the resource file to make editing easier.  Decoded, it looks like this:



The “policy_web_config” file is the Policy Field tag that will need to be added to the content site web.config file for the Registration Field as mentioned earlier: 

<add fieldName="Policy" fieldType="Policy" policyLabel="Resources:ACME,RegistrationField_PolicyLabel" policyMessage="Resources:ACME,RegistrationField_PolicyMessage" /> 

Finally, “PrivacyStatement.aspx” and “ServiceAgreement.aspx” are sample files we can edit to suit our needs.  For the purpose of this blog, we will only configure the Service Agreement.  The configuration of the global Privacy Statement would follow the exact same steps.
The first thing we need to do is create a folder in the 15 hive to store our custom Policy.  By default we would create it here: 

C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\15\TEMPLATE\LAYOUTS 

In this case, I will create a folder named “ACME”:

Once it’s created, we need to copy the following files from the zip file into our new directory:

Now we need to edit the “ServiceAgreement.aspx” file to reflect our customizations.  I have highlighted the areas I changed below:
 
The first change I made was to reference the “anonymous.master” master page due to my environment configuration.  Next, I gave the header the name “ACME Service Agreement,” and did the same for the PageTitle and PageTitleInTitleArea tags.  Finally, I put a very brief custom agreement in the “descriptiontext” tag.

Next, let’s make the necessary edits to the included resource file.  The area we are looking for is at the bottom of the file:
The full text as it appears there is as follows:
data name="RegistrationField_PolicyLabel" xml:space="preserve">
    <value>I accept</value>
  </data>
  <data name="RegistrationField_PolicyMessage" xml:space="preserve">
    <value>Clicking &lt;STRONG&gt;I accept&lt;/STRONG&gt; means that you agree to the &lt;A href=&quot;javascript:ShowPopupDialog(&#39;/_layouts/ACME/ServiceAgreement.aspx&#39;)&quot;&gt;service agreement&lt;/A&gt; and &lt;A href=&quot;javascript:ShowPopupDialog(&#39;/_layouts/ACME/PrivacyStatement.aspx&#39;)&quot;&gt;privacy statement&lt;/A&gt;. </value> 
  </data>
Notice I have simply changed the path from “/SPSolutions/ExCM” to reflect our newly created folder “/ACME.”  Once the changes have been saved, we just need to copy the resource file to the “App_GlobalResources” directory under our content site:
The final step is to add the Policy Registration Field in our web.config file using the “policy_web_config” example from the zip file.  This will make it globally available to all Site Collections in our Web App:
In addition, I will also go ahead and add the rest of the global field types we mentioned at the beginning of this post:
Now we’re ready to take a look at the update Registration Page with our Global Fields:
And here is how our customized Service Agreement now appears:

As mentioned earlier, you can follow the same steps to also customize the Privacy Agreement.

No comments: