Working with Matter Team Membership Using the IntApp Walls API

The IntApp Walls API is a powerful tool for managing ethical walls and securely controlling access to sensitive data. By leveraging its operations, developers can efficiently interact with matter teams, manage memberships, and ensure compliance with confidentiality requirements.

The Intapp Walls API is a SOAP web service that provides a programmatic interface for interacting with the Intapp Walls application. It is deployed as a standard component web service.

For the sake of simplicity, the sample code in this document omits error checking, exception handling, logging, and other practices. It is intended for illustrative purposes only and does not necessarily reflect best coding practices.

Here I walk through two key scenarios:

1. Retrieving and listing matter team membership.
2. Adding a new member to an existing matter team.

By understanding and using IntApp Walls API operations such as "GetMatterTeamForMatter", "LoadMatterTeam", and "AddUsersToMatterTeam", you can streamline tasks related to ethical wall management. The following examples include code snippets and step-by-step guidance.

This document will not cover the specifics of configuring development access to the IntApp Walls API. However, the management solution must be installed on your local domain, and the web service is typically accessible via a file named "APIService.svc", which should be added as a service reference in Visual Studio.

The sample code references the following IntApp Walls API operations:

GetMatterTeamForMatter: Gets the ID of the matter team that is associated with the specified matter.
LoadMatterTeam: Loads the properties of a matter team.
GetDMSUserID: Get the DMS user ID. Some of the API methods require the DMS user ID for a user. For example, the CreateWall() method requires the user ID to be that of the DMS, not a user's timekeeper ID or records system ID. This method can be used to get the DMS user ID given another known ID for the user.
LoadMatterTeamMembership: Loads the matter team membership.
GetWarningsIfUserIsIncluded: Gets any warnings that would be generated if the specified user was granted access (i.e., included) to a particular client or matter. This function returns any warnings that may be generated by conflicting ethical walls.
AddUsersToMatterTeam: Adds the user to an existing matter team with a specified role.

Example: Retrieving and Listing Matter Team Membership
The following code snippet uses the IntApp Walls API "GetMatterTeamForMatter" and "LoadMatterTeam" operations to retrieve a list of matter team members and then write the team membership particulars to the console.

Notes:
• Working with the IntApp API typically requires specific privileges, often granted to a service account with appropriate IntApp Walls access.
• References to "intapp_web_api" in the code snippet below, refers to the name of your IntApp API service reference as defined in Visual Studio.

Step 1 Retrieve the unique IntApp Walls-managed matter team ID number.
Retrieve the ID of the matter team associated with a specified matter. This matter team ID will then be used to obtain the matter team membership details.

To achieve this, invoke the "GetMatterTeamForMatter" operation, which requires a "matterID" parameter. The "matterID" is typically an internally generated ID, sometimes referred to as a "case number." This value is supplied by the user or programmer from their own Timekeeper-type source.

string matterID = "01234"; // matterID supplied by you
string matterTeamID = String.Empty; // the return value

// get the walls matter team id
// example of matter team id "COOLE-033517"
matterTeamID = intapp_web_api.GetMatterTeamForMatter(matterID);

public static string GetMatterTeamForMatter(string matterID)
{
  intapp_web_api.Matter matter = new intapp_web_api.Matter();
  string matterTeamID = string.Empty;

  try
  {
    intapp_web_api.APIServiceClient intapp_web_api = new intapp_web_api.APIServiceClient();
    matterTeamID = intapp_web_api.GetMatterTeamForMatter(matterID);

    if ((string.IsNullOrEmpty(matterTeamID)))
    {
      matterTeamID = "blank";
    }
  }
  catch (Exception ex)
  {
    if (string.IsNullOrEmpty(matterTeamID) || ex.Message == "Error")
    {
      matterTeamID = "blank";
    }
  }
  return matterTeamID;
}

Step 2 Load the Matter Team Results
Define the "LoadMatterTeam" method and use the unique IntApp Walls-managed matter team ID number "matterTeamID" variable obtained from executing the "GetMatterTeamForMatter" method to call the "LoadMatterTeam" method to retrieve the matter team. Iterate through the "UserMemberships" collection within the matter team and output the user team ID and role to the console.

public static intapp_web_api.MatterTeam LoadMatterTeam(string matterTeamID)
{
  intapp_web_api.MatterTeam matterTeam = new intapp_web_api.MatterTeam();

  try
  {
    intapp_web_api.APIServiceClient intapp_web_api = new intapp_web_api.APIServiceClient();
    matterTeam = intapp_web_api.LoadMatterTeam(wallscaseteamid);
  }
  catch (Exception ex)
  {
    throw new Exception(ex.Message.ToString());
  }

  return matterTeam;
}

MatterTeam the_matter_team_list = LoadMatterTeam(wallscaseteamid);

using (APIServiceClient intapp_web_api = new APIServiceClient())
{
  // iterate through the usermemberships collection in the matterteam
  foreach (UserMembership user in the_matter_team_list.UserMemberships)
  {
    string _userid = user.UserId.ToString(); // get the user id
    string _therole = user.Role.ToString(); // get the user role

    // output the user team id and role to the console
    Console.WriteLine($"user team id: {_userid}");
    Console.WriteLine($"user team role: {_therole}");
  }
}

Example: Adding a New Member to an Existing Matter Team Membership
Building on the "GetMatterTeamForMatter" and "LoadMatterTeam" operations to retrieve a list of matter team members, the following code snippet demonstrates how to use the IntApp Walls API to check existing team membership and add a new member to the team if they are not already a member.

Notes:
• Manipulating IntApp Walls teams via the IntApp API requires specific privileges, which are beyond the scope of this document. The requester will also need to be in an IntApp Walls matter admin role as defined in IntApp Walls.
• Working with the IntApp API typically requires specific privileges, often granted to a service account with appropriate IntApp Walls access.
• References to "intapp_web_api" in the code snippet below, refers to the name of your IntApp API service reference as defined in Visual Studio.

Step 1: Using the "GetDMSUserID" operation, Get the "sAMAccountName" of the user you want to add to the Walls team.
The "sAMAccountName" (Security Account Manager Account Name) is an attribute in Microsoft Active Directory (AD) that represents a user's logon name used to authenticate to the domain.

string theid = "jsmith"; // the sAMAccountName ad account name of user to add
string wallsuserid = string.Empty;

wallsuserid = intapp_web_api.GetDMSUserID(UserIDSource.WindowsNetworkLogon, $@"YourDomainName\{theid}") // change "YourDomainName" to your domain name

// check if wallsuserid contains a value
if (string.IsNullOrEmpty(wallsuserid))
{
  Console.WriteLine("the user you are trying to add to Walls team does not exists in Walls");
  return;
}

Step 2: Check if the Matter exists in Walls.

string matterID = "01234"; // matterID supplied by you

try
{
  matterTeamID = intapp_web_api.GetMatterTeamForMatter(matterID);
}
catch (Exception ex)
{
  if (ex.Message.Contains("The matter") && ex.Message.Contains("does not exist"))
  {
    Console.WriteLine("the matter does do not exist");
    return;
  }
  else
  {
    Console.WriteLine(ex.Message);
    return;
  }
}

Step 3: If the Matter exists, is the user already a team member?

// is the user you are trying to add already on the case team?
// use matterTeamID from step #2 above
// use wallsuserid from step #2 above
MatterTeam matterteamlist = intapp_web_api.LoadMatterTeamMembership(matterTeamID);
foreach(UserMembership user in matterteamlist.UserMemberships)
{
  if (smaccountname == wallsuserid) // are they on the case team already?
  {
    Console.WriteLine("the user you are trying to add is already a member");
    return;
  }
}

Step 4: Will adding the user to the Matter team cause an internal conflict?

// will adding the user to the case team cause a conflict?
// use wallsuserid from step #2 above

string matterID = "01234"; // matterID supplied by you

string[] warning = intapp_web_api.GetWarningsIfUserIsIncluded(null, wallsuserid, SecurableEntityType.Matter, matterID);
if (warning.Length > 0 && warning[0].Contains("has conflicting case-level access"))
{
  Console.WriteLine("adding the user as a member will cause a conflict");
  return;
}

Step 5: Finally, add the user to the Matter team.

// Add the user to the Matter team
// use wallsuserid from step #2 above
// use matterTeamID from step #3 above
// UserMembership is a partial public class
// of the Wallbuilder API service reference

string caseteamrole = "Member";
string theReason = $"{theid} added programmatically via the Walls API Service"

UserMembership _mbr = new() // _mbr membership string array
{
  UserId = wallsuserid,
  Role = caseteamrole,
  Reason = theReason
};

// build user membership- must be string array for AddUsersToMatterTeam
UserMembership[] TheAddUserMmbrshipList = { _mbr };

// actually add the user now
intapp_web_api.AddUsersToMatterTeam(matterTeamID, UserIDSource.DMS, TheAddUserMmbrshipList); // do the add

Conclusion
The IntApp Walls API offers a comprehensive set of operations for managing matter team memberships and safeguarding sensitive information. From retrieving team details to adding new members while checking for conflicts, these API functions enable seamless integration with your workflows and adherence to ethical wall policies. With the right implementation, managing matter teams becomes a streamlined and efficient process that upholds data integrity.