Users

An organization will have users that are all assigned roles and types based on what they are doing in your organization. The API allows you to get information about a user, or add/update users.

Creating a new user

There are four required components of any user: First Name, Last Name, Email, and at least one UserType.

User user = new User
{
    FirstName = "First",
    LastName = "Last",
    Email = "[email protected]"
};

We have defined a UserType as its own class, holding a user's UserRole, in order to make it easier to interact with them throughout the API. Here is an example of a Faculty/Staff Learner who is a Nonsupervisor.

user.UserTypes.Add(new UserType(UserRole.FacStaffNonSupervisor));
// All possible UserRoles: UndergraduateHE, GraduateHE, NonTraditionalHE, GreekHE, HEAdmin, FacStaffSupervisor, FacStaffNonSupervisor, FacStaffAdmin, CodeConductSupervisor, CodeConductNonSupervisor, CodeConductAdmin, AdultFinancialLearner, AdultFinancialAdmin, EventVolunteer, and EventManager.

Setting the User's Location

The Location attribute, which may be required for certain organizations depending on the business rules for their configuration, allows Users to be added to specific organization locations. The location given to a User must be one that already exists in Foundry (retrieved from before, or created and then added to Foundry).

// Assigned to a particular location in your saved list:
user.Location = locationsList.ElementAt(0);

If the business logic for your integration has logic that associates a Location's Id or its External Location ID to your organization's various locations, then you can set the User's location this way:

user.Location = foundry.GetLocationById("2892");

or:

user.Location = foundry.GetLocationByExternalId("HQ");

Note that the above calls does not cause the SDK to make an outgoing API call because locations are retrieved once and then cached within the API's internal logic each time the API is instantiated.

There are other attributes you can add to a user, which are not required: SingleSignOnId, StudentId, EmployeeId and others.

Setting a User's Category Label(s)

A User may have Labels, which are demographic attributes grouped within Categories. These values are unique to each organization in Foundry.

A User has a list of Labels in a property called Labels.

You can get, add or remove a user's Labels, and then Add or Update the user.

Be aware that GetCategories is an expensive API call, so make this call only once per session, save the results locally, and do not run this method every time you interact with a user.

User myUser = new User();

// First, get all the categories and labels
List<Categories> cats = foundry.GetCategories(true);

// Find the specific Category
Category myCat = cats.Find(x => x.Name == "Start Year");

// Find the specific Label in the Category:
Label myLabel = myCat.Labels.Find(y => y.Name == "2021");

// Add that label to the User's Labels
myUser.Labels.Add(myLabel);

Altering Labels for an Existing User

A user may have at most one Label per parent Category. Therefore, if you want to add a Label to a User, you first must remove any other Label in the same Category.

{
   myUser = foundry.GetUserByID("xyz-123");

   // First, get all the categories and labels
   List<Categories> cats = foundry.GetCategories(true);

   // Find the specific Category
   Category myCat = cats.Find(x => x.Name == "Department");

   // Find the specific Label in the Category:
   Label myLabel = myCat.Labels.Find(y => y.Name == "Accounting");

   // check to see if user already has this label
   if(!myUser.Labels.Contains(myLabel))
   {
      // if user already has a Label in the same category, then you must remove the other Label first
      // because a User may have at most on Label per parent Category:
      Label otherLabelInSameCategory = myUser.Labels.Find(x => x.CategoryId == myLabel.CategoryId);
      if(otherLabelInSameCategory != null)
      {
         myUser.Labels.Remove(otherLabelInSameCategory);
      }
      
      // add the Label
      myUser.Labels.Add(myLabel);
   }
}

Alternately, you could remove all the user's Labels and add them back on each update, so long as your integration code "knows" what all the Labels are.

Adding a user to your organization

user = foundry.AddUser(user);

You need to assign your original user to the AddUser function so that the user is updated with the new UserId, which won't exist until you add it to Foundry. You cannot add a UserId to a user yourself.

Retrieving users

When retrieving users, you can choose to retrieve a single user by their UserId, or retrieve multiple using paging.

By UserId

string UserId = "58c836fd-ebe3-4533-aee4-7a6f1a064de9";
User retrievedUser = foundry.GetUserById(UserId);

If the user is not found, then the SDK will respond with a FoundryException.

By email

User retrievedUser = foundry.GetUserByEmail("[email protected]");

If the user is not found, then the SDK will respond with a FoundryException.

Multiple users

The Foundry API is designed to return at most 100 users per page. Because of this, you can choose to access the users of your organization in different ways. To get a specific page of users, you can specify the page number in the method call (Getting the first hundred: page = 1)

List<User> users = foundry.GetUsers(1);

You can also loop through and get some or all of the users of your organization. The paging is done by the caller, as the API only returns 100 users.

// Getting all users
List<User> allUsers = new List<User>();
bool keepGoing = true;

while (keepGoing)
{
    List<User> currentUsers = new List<User>();
    (currentUsers, keepGoing) = foundry.GetUsers(); // Returns the next 100 users and if there are more.
    myUsers = myUsers.Concat(currentUsers).ToList();
}

// Getting the first 300 (or less) users
List<User> my300Users = new List<User>();
bool keepGoing = true;
int i = 0;
while (i < 3 && keepGoing)
{
    List<User> retrievedUsers = new List<User>();
    (retrievedUsers, keepGoing) = foundry.GetUsers();
    my300Users = my300Users.Concat(retrievedUsers).ToList();
}

Once you have gotten the users you want, you can choose to reset the position of the paging by calling foundry.ResetGetUsers(). This allows you to reset the position so paging will begin at the beginning if foundry.GetUsers() is called again. Otherwise, you can simply continue paging. (Note, after reaching the end of the user list, the API will automatically reset the page.)

Searching for users

You can also use different terms to search for a user, or multiple users. To search with Foundry, you need to create a dictionary holding pairs of SearchTerms and the term (SearchTerms are an Enum that hold values such as FirstName, Email, StudentId, etc.).

List<User> myUsers = new List<User>();

Dictionary<SearchTerms, string> search = new Dictionary<SearchTerms, string>();
search.Add(SearchTerms.FirstName, "Aman");

myUsers = foundry.GetUsersBySearch(search);

If the search finds no users, then the response will be an empty list.

Updating an existing user

// Make some change(s) to the user (ex. user.Email = [email protected])
foundry.UpdateUser(user);

When updating a user it's important to note that you cannot remove any of the required fields (i.e. there must be a name, email, and at least one UserRole), but you can still update them.

Getting the Users’ Progress

First, initialize a DateTime object to a specific date (you will see all users’ progress from that date) Call the getUserProgress() method on your API object, using the DateTime struct and desired scroll size (int) as the arguments.

DateTime d = new DateTime(2018, 5, 29);
var progress = foundry.GetUserProgress(d, 10);