Using the Person Business Type (Karol Zadora-Przylecki, Ravi Eda)

Using the Person Business Type (Karol Zadora-Przylecki, Ravi Eda)

Rate This
  • Comments 9

The Person business type is a new LightSwitch feature introduced in Visual Studio 2013. Its goal is to make it easy to add and manage people-related data in your application. In this post we will show you how to use the Person type and what it can do for you.

Getting Started

Suppose you are building an application to track mobile devices that a developer organization is using for testing applications they write. A device can be either checked out to a specific person or be in storage. Here is what a Device entity might look like in the Data Designer:

image

 

In this example we set the Owner and CheckedOutTo properties to be of type Person. Person is a business type, a flavor of .NET Framework string. It is designed to store people’s identities: values that uniquely identify individuals.

You can store any identity value that you want in a Person field, but we make some assumptions about the identity format depending on the authentication type of the application. So if you want the Person type “magic” to work, you’ll want to stick with the defaults:

  • For forms authentication, LightSwitch will use the forms login name as the identity value
  • For Windows authentication it will be the user’s Windows login name (e.g. “contoso\joesmith”)
  • In case of SharePoint-enabled applications, including Cloud Business Applications, the identity is the user’s primary email address
  • If your application does not use any authentication and users are anonymous, their identity is represented by an empty string
  • There is also a special “TestUser” value that represents the identity of a user running the application in debug (F5) mode

The nice thing is that we give you a simple API to get the identity value for the current user of the application. You can use this API in order to get more information about a person represented by a given identity value. So working with Person properties does not require you to deal with the particulars of the different authentication mechanisms.

Rich Information via Info Properties

The entity class we generate from your data model includes two properties for each Person property: the property containing the raw identity (identity property of type string) and a property ending with an “Info” suffix of type PersonInfo (info property). In our example the identity property “CheckedOutTo” has a corresponding info property named “CheckedOutToInfo”. Similarly, there is Owner-OwnerInfo property pair.

The info property exposes information about a person identified by the corresponding identity property. Info properties are read-only; the source of their data is a directory service. You can use the info property value in your code to write various kinds of business logic. For example, here’s how you can use the entity’s Info property to send an email when a Device is saved:

partial void Devices_Updating(Device entity)
{
    if (entity.Details.Properties.CheckedOutTo.IsChanged
        && !string.IsNullOrEmpty(entity.CheckedOutTo))
    {

        O365PersonInfo owner = entity.OwnerInfo;
        O365PersonInfo currentUser = entity.CheckedOutToInfo;
 

if (string.IsNullOrEmpty(owner.FullName) || string.IsNullOrEmpty(currentUser.FullName)) { // We could not resolve the owner or the current user of the device. // Continue without sending email. return; } string emailBody = "Hey, just FYI, your device " + entity.AssetNumber + " (" + entity.Description + ") has been checked out to " + entity.CheckedOutToInfo.FullName; SendEmail("DeviceTracker@contoso.com", entity.OwnerInfo.Email, "Device " + entity.AssetNumber + " checked out", emailBody); } }

If the identity property contains a value that the directory does not recognize, the info property returns an object that represents the unresolved, raw identity and the full person information will be unavailable.

In Visual Studio 2013, SharePoint-enabled LightSwitch apps (Cloud Business Apps) use either Active Directory or Azure Active Directory (for on-premises vs. cloud-based applications, respectively) to retrieve contact, organizational and security-related information about people. If the application uses Windows or Forms authentication, only basic, security-related information is exposed via info properties.

Current User Data

Information about the current user of the application is available via the User property of the global Application object. In Visual Studio 2013 this property will return an object of PersonInfo type, so you can handle the “current” user and other users in the application in the same way. For example:

partial void Devices_Inserting(Device entity)
{
    // If the Owner has not been set, assume the current user is the owner
    if (string.IsNullOrEmpty(entity.Owner))
    {
        entity.Owner = Application.User.PersonId;
    }
}

We use the PersonId property to retrieve the identity of the current user in a format that is appropriate for the authentication mechanism used by the application.

Filtering Data for the Current User

A common scenario in a business application is to filter data based on the current user. This would show the most relevant data for the user to consume. For example, in the device tracking application we want to have a screen that shows all the devices checked out to the current user. To support this case, two new Global types are introduced in the query designer – Current User and Anonymous User. Current User refers to the user who is currently logged into the app. Anonymous user is one that the server is not able to authenticate.

To use these Global types, use the Query Designer to add a query to the Device table. Add a filter in the query designer. Select “CheckedOutTo” as the left operand. From the operator type dropdown select “Global”. Select “Current User” as the right operand. The filter should be as shown in the screenshot shown below:

image

Now a screen that uses this query as a data source will display all devices that are checked out to the current user logged in to the app. Note that this filtering can only happen at the server side since current user information is available only at the server.

Working with People Data

There are a few things worth remembering when working with people data and PersonInfo types. First, rich data on people is only available to server-based code. This is particularly important to remember if you have a desktop (Silverlight) client, because in this case the default is to compile entity code (methods such as property_Changed) twice: first in the context of the server project, and second in the context of the desktop client project. (This is so you can write business logic once but LightSwitch can run it from both the client & server side). Any type references that are invalid will cause a build error. The solution is to use a separate entity code file for the client (default is to re-use server code files via a file link in the client project), or to employ conditional compilation. Here is an example of the latter approach:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.LightSwitch;
#if !SILVERLIGHT
using Microsoft.LightSwitch.Framework.Server;
#endif

namespace LightSwitchApplication
{
    public partial class Device
    {
        partial void CheckedOutTo_Changed()
        {
#if !SILVERLIGHT
            O365PersonInfo currentUser = this.Application.User as O365PersonInfo;

            if (currentUser != null)
            {
                // ... business logic using rich information ...
            }
#endif
        }
    }
}

Second, you are free to store any value in a Person property, including values that are not resolvable. These might be identities that have become invalid, or valid identities that the directory service just does not know how to resolve later. So it’s always a good idea before using any Info property to check whether it was properly resolved. The presence or absence of the FullName is a good way to check this (see our first code example).

Finally, it is not impossible for the same human being to have multiple identities, or for her identity (email address, login name) to change. It is even possible to have the same identity be assigned to a different person. The Person type does not have any specific support for these scenarios, so you are responsible for any checks or compensation logic for those cases. With unrestricted read/write access to raw identity in the Person type, you have the flexibility to do what you want in your business logic.

Person Viewer and Picker Controls

Visual Studio 2013 also introduces two new controls for the Person data type - Person Viewer and Person Picker. These controls are available in an HTML client of a SharePoint-enabled app. A SharePoint enabled app can be either an app that was created using the Cloud Business Application project template or you Enabled SharePoint on your LightSwitch HTML application.

Person Viewer is a read-only control that shows the user’s full name, title, picture and Lync Presence Status. The Person Viewer control uses NameCtrl ActiveX to display Presence Status. The Lync Contact Card is shown on mouse hover on this control. A user can click or tap on this control to navigate to the user’s SharePoint profile site.

In our example, when we create a View Details Screen for the Device entity, this will automatically create the Person Viewer controls. Notice the Person Viewer Control has name, title, and picture shown for “Owner” and “Checked Out To” properties. Presence Status information of these users is also available. A mouse hover on Owner property shows the user Lync Contact Card.

image

The Person Viewer can display a person in two different ways. The first option (which is the default) shows just the user’s name. The second option shows the title and picture in addition to the person’s name. This choice can be selected in the Screen Designer as shown in the screenshot below:

image

The Person Picker control is an editable text control. This control is used to search for a person and select one from the results shown in the dropdown. Similar to Person Viewer controls, Person Picker control’s search results can be customized to show just the user name or user name along with title and picture. Using the “Name only” option would just show only full names in search results. The screenshot below shows all the matches for “Karol Z” among the SharePoint users.

image

The Picker or Viewer control is automatically chosen based on the type of a screen. For example, on a screen that uses the View Details Screen template, a Person type property will use the Viewer control. Whereas, the same property in a screen built with Add/Edit Details Screen template will use the Picker control. You can change this in the Screen Designer.

These controls behave in a certain way depending on the underlying components that are used to integrate SharePoint and Lync. Some of these behaviors are highlighted below:

  • The Lync 2013 desktop application needs to be running in the background and you need to be logged in using the same credentials that were used to log into SharePoint.
  • If the app is not able to resolve the person correctly then the Viewer control will show the person ID in plain text. Reloading the app should allow it to re-query SharePoint and resolve the person correctly. If the problem persists it is most likely due to SharePoint Cross Domain Library being unable to connect to SharePoint. One reason this could happen is the SharePoint site uses “https” and the app can only run “http” thus putting them in different protection levels.
  • NameCtrl is a 32 bit ActiveX control. Such controls have some limitations:
    • These work only in 32 bit browsers (IE Desktop, Chrome Desktop and Firefox Desktop). There is a workaround to make these controls work in a 64 bit browser.
    • The control must be allowed to run in the browser

If you are using a SharePoint server on premises (not Office 365) then the user’s profile picture in Viewer control will not show. However, the Lync Contact Card will have the correct picture.

Wrapping Up

We hope that the Person type proves useful in your applications. Please install the Visual Studio 2013, try it and let us know what you think by leaving a comment below or visiting the forum.

But wait, there is more! A couple new LightSwitch features leverage the Person type to automatically track the relationship between people and data they have created or modified. These features will be described in an upcoming post so please stay tuned!

Karol Zadora-Przylecki, Lead Developer, Cloud Business Apps

Ravi Eda, Software Development Engineer in Test, Cloud Business Apps

Leave a Comment
  • Please add 7 and 4 and type the answer here:
  • Post
  • Hi Ravi

    Thank you for this nice post.

    In my on going project I have one requirement to filter data based on current user and manager. So is it possible to filter the database using person data type for this requirement. If yes then how?

    e.g - current user can see only his/her data. If the current user is manager for some other users then the current user can see his/her data including the other users data related to him.

    Thanks

  • Thanks Rashmi.  

    Yes, you should be able to filter out data based on the current user.  For example, say you have a table named 'Project' with three properties –

    1. ProjectName – name of the project.  A string type.

    2. ContactPerson – primary contact for the project.  A Person data type.

    3. Manager – the manager of the ContactPerson.  A Person data type.

    Add a query under ‘Project’.  Add two single filters - “Where Manager = Current User” Or “ContactPerson = Current User”.

    Add a Browse screen with this query as a data source.  Now each user should be able to see only projects where he/she is listed as the Manager or as the ContactPerson.  Hope this clarifies.

    Thanks,

    Ravi

  • Hi Ravi

    Thank you. Its working as expected.

    Is there any person viewer/picker control for Silverlight client. If not then is there any future road map to integrate person viewer/picker control for SL client?

    Thanks

  • Glad it helped.  Person Picker and Viewer controls are not available for Silverlight client.  Please submit a request for these controls at connect.microsoft.com/visualstudio

  • Hi,

    We are using VS 2013 RC and Sharepoint 2013 for developing Lightswitch HTMLCLient application. We enabled sharepoint in our application. We are exited to see the People picker / viewver control.

    Our expectation is that all the column of type Person in Sharepoint will map to Type Person in Lightswitch application . But unfortunately Colum of type Person is defined as UserInformationlist in the Lightswitch HTML application. So, these fields are not having People picker control. Is there any way to get people picker control for all the sharepoint columns of type Person ( Created By, ModifiedBy,etc) .

    We are looking for similar functionality as in the sharepoint for lightswithc HTML.

    Thanks in advance,

    Abdul Raheem

  • It's a greatest advance in Lighswitch, congratulations!

    Since 2011 version, Lighswitch technology becomes esier to use and more powerful.

    Managing persons in Database gives a lot of uses and the option to create social applications.

  • Is the Email property of the PersonInfo type only available in Sharepoint enabled applications?

    I'm trying out the Person data type in a Silverlight desktop app that uses Windows authentication.  I don't see the Email property in intellisense at all.

    And some reference pages on some of these Lightswitch namespaces (like is available on MSDN for other .Net namespaces) sure would be nice, essential even.  Am I just not looking in the right place?

  • "Is the Email property of the PersonInfo type only available in Sharepoint enabled applications?"

    Yes, it has to be a SharePoint enabled app. Person Viewer and Picker controls are available in HTML client only.

  • Thanks, Ravi.  Bad news for me, but I appreciate the quick response.

    It might help others if you make it a little clearer in the "Rich Information" code example that the Email property is only available in Sharepoint enabled apps.  I based my entire data design around the idea that a single column with the Person data type could contain a network id, full name, and email address.  I probably should have know that was too good to be true.  And since Windows authentication is going to be very common in internal LOB apps, that information could affect a large number of people.

Page 1 of 1 (9 items)