Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

Overview

The Regent 8 financial aid system supports third-party integration via a rich and robust API in the form of web services. The Regent Award API covers nearly 100% of all functionality available in our management UI. Interoperability is achieved via the SOAP protocol. The service definitions are provided as WSDL documents.

With few exceptions, service methods follow the convention of accepting a custom, complex type as an input parameter, and returning a custom, complex type as an output parameter. This version of the Web Service API User Guide details service methods relating to document, user, and role management.

This guide is geared towards Microsoft .Net C# developers. However, the majority of the concepts and examples provided apply to all programming languages and frameworks.


Adding a Service Reference in Visual Studio

Adding a reference to these services to your Visual Studio project can be accomplished in a number of ways including use of svcutil for more advanced scenarios, or by simply using the Add Service Reference available within your Visual Studio project as illustrated in the screenshot below.


API Security

The Regent Award API is security by the following methods:

  1. HTTPS
    1. For transport layer security
  2. IP Whitelisting and/or VPN only access
  3. API service credentials.
    1. A SecurityToken object containing a Regent provided ClientId and Token is passed into every API service call


Important SecurityToken Information

A SecurityToken object needs to be passed into every Regent API service method which contains both the API service credentials and the user that the service method should execute as. The ClientId/Token gets you access to call the services.

In some cases it may be appropriate to have one or more system users that would reflect different customer applications. For example, there could be different credentials and/or users for various customer services that is leveraging the Regent Award API:

  1. Student Information System
  2. Document Management System
  3. Satisfactory Academic Progress service

This way there is clear user tracking in the Regent Award system which reflects the customer system creating or modifying data.


(lightbulb) Store ClientId and Token values in application configuration! These may be different between production and test environments. And they may need to be updated at a later date.

(lightbulb) Use a common method to create the SecurityToken in the application code.


SecurityToken fields

  1. Username
    1. String. Provided by Regent.
  2. UserId
    1. Long. Provided by Regent.
  3. DashboardAdmin
    1. Boolean. Always set to true.
  4. ClientId
    1. String. Provided by Regent. 
  5. Token
    1. String. Provided by Regent 


Working with Student Identifiers

Regent Award maintains a unique internal ID for every student record in its system, typically referred to as studentId. Customers supply their own student identifiers in the Student Batch Load process when creating or updating students in Regent. These are referred to as external ID's in Regent Award and four are provided for student records: externalId1, externalId2, externalId3, and externalId4.

The majority of Regent service methods expect to work with Regent Awards internal unique studentId, NOT the customer external identifiers. Therefore, customers need to get Regent's internal student ids prior to interacting with Regent Web Services. 

There are multiple strategies available for customers to ensure they have the studentId for student records.

  1. Individually look up Regent Award studentIds based on customer externalId prior to utilzing service methods for a given student.
  2. Retrieve Regent Award studentId's in bulk by leverage Data Views or Service Methods that return lists of students.

In many cases it would be best practice and recommended for customers to cache or store Regent's student identifiers in their system. This would especially be the case if a customer has large student populations and/or are calling services very frequently. They could be cached as they are looked up one off, or in bulk. Developers should be aware that it is possible for customers to effectively change Regent hosted external identifiers by both service method calls and the Student Batch Load file process. This could happen for a number of reasons and the customer should be aware of their processing scenarios if caching studentIds.

Regent Award Student Identifier Lookup C# Example

long studentid = -1;

string externalId1 = "EXTERNAL_ID_HERE";
GetStudentsRequest getStudentsRequest = new GetStudentsRequest();
getStudentsRequest.SecurityToken = securityToken; // update with your instantiated SecurityToken object

// this method is special in that you can build a dynamic set of filters. Here we want to find student
getStudentsRequest.filter = new Filter
{
	Filters = new List<Filter>
	{
		new Filter {Field = "externalId1", Operator = "eq", Value = externalId1}
	}.ToArray()
};
getStudentsRequest.endRowIndex = 10;

GetStudentsResponse getStudentsResponse = client.getStudentBasicInfoList(getStudentsRequest);

if (!getStudentsResponse.Success)
	throw new ApplicationException(string.Format("Error calling {0}:{1}", "getStudentBasicInfoList", getStudentsResponse.Message));

// expect you'll get 1 and only 1 record. Adjust for your needs.
if (getStudentsResponse.Records.Length != 1)
{
	throw new ApplicationException(string.Format("Expected 1 student record but found {0} records", getStudentsResponse.Records.Length));                
}

studentid = getStudentsResponse.Records[0].Id;
return studentid;



USER MANAGEMENT


A common use of the User and Roles services in Regent Award is to systematically provision user accounts/roles. For example, a customer may utilize the Regent Award services along with an existing enterprise identity management system to A) determine whether to allow access to Regent Award at all and B) map Regent Award roles to roles defined in the customer system and C) ensure user access to Regent Award is removed in termination or position change scenarios.

* The “Password must be reset on next login” checkbox in the Regent Award UI translates to the PasswordExpiresOn field. If PasswordExpiresOn is set prior to the current utc time, the checkbox would be checked. To update an existing user to force a reset of password, get the login record from getLogin method, and then update PasswordExpiresOn property on the login record to the past in UTC time. Example: “.PasswordExpiresOn = DateTime.UtcNow.AddDays(-1);”. Then call the updateLogin method to persist the change to the login record.

Creating a User

Method

UpdateLoginResponse createLogin(UpdateLoginRequest request);

Description

This method is used to create a new user account.
To call this method, you need to construct a UpdateLoginRequest object with the following properties:
public SecurityToken SecurityToken { get; set; }
public Login Record { get; set; }
SecurityToken properties:
public long UserId { get; set; } // required
public bool DashboardAdmin { get; set; } // required
public string Username { get; set; } // required
public string CurrentRole { get; set; } // required
public string Token { get; set; } // required
public string ClientId { get; set; } // optional; used to support
// 3rd-party authentication
Login properties:
public Int64 LoginId { get; set; } // required
public String Username { get; set; } // required; 255 character maximum
public String Password { get; set; } // optional; 255 character maximum
public String PasswordSalt { get; set; } // optional; 255 character maximum
public String Email { get; set; } // required; 128 character maximum
public String FirstName { get; set; } // optional; 35 character maximum
public String LastName { get; set; } // optional; 35 character maximum
public bool IsActive { get; set; } // required
public bool DashboardAdmin { get; set; } // required
public Int32 LockoutAttempts { get; set;} // required
public DateTime? LockoutDate { get; set; } // optional; UTC-based
public DateTime? LastLoginDate { get; set; } // optional; UTC-based
public DateTime PasswordSetDate { get; set; }// optional; UTC-based
public DateTime? PasswordExpiresOn { get; set; }// optional
public Int32 UTCOffset { get; set; } // optional
public String Timezone { get; set; } // optional
public String ExternalId1 { get; set; } // optional; 50 character maximum
public String ExternalId2 { get; set; } // optional; 50 character maximum
public String SingleSignOnCode { get; set; } // optional
public String LoginAuthenticationTypeCode { get; set; } // required:
// Password/SingleSignOn
UpdateLoginResponse has the following properties:
public Login Record { get; set; }// see above
public bool Success { get; set; }
public bool ErrorYN { get; set; }
public bool StaleEntity { get; set; }
public String Message { get; set; }
public int totalCount { get; set; }
public long processingTime { get; set; }
public ValidationResults ValidationResults { get; set; }

ValidationResults properties:
public bool IsValid { get; set; }
public ValidationResult[] Results { get; set; }
ValidationResult properties:
public String Property { get; set; }
public String Message { get; set; }

C# Code Sample


private void CreateUser()
{
RegentEnterpriseServiceClient wsClient = null;
// CAUTION: don't wrap client in using statement:
// http://msdn.microsoft.com/en-us/library/aa355056.aspx
try
{
#region authenticate user – replace with appropriate implementation
SecurityToken securityToken = new SecurityToken()
{
Username = "system",
UserId = -1,
DashboardAdmin = true,
// provided by Regent. These would be config settings
ClientId = "CustomerClientId",
Token = "l23kj5hklj3h4l3kj"
};
#endregion authenticate user
// this would likely be a config setting
string wsUrl = "https://schoolremwsqa.regenteducation.net/RegentEnterpriseWebService.svc";
wsClient = new RegentEnterpriseServiceClient();
wsClient.Endpoint.Address = new System.ServiceModel.EndpointAddress(wsUrl);
// set up request
UpdateLoginRequest createLoginRequest = new UpdateLoginRequest();
createLoginRequest.SecurityToken = securityToken;
createLoginRequest.Record = new Login()
{
Username = "tuser1", // required; 255 chars max
Email = "tuser1@school.edu", // required; 128 chars max
IsActive = true, // required
DashboardAdmin = true, // required
Password = "test", // required; 255 chars max
PasswordSetDate = DateTime.UtcNow, // required
PasswordExpiresOn = null, // optional
FirstName = "Test", // optional; 35 chars max
LastName = "User1" // optional; 35 chars max
};
// make call
UpdateLoginResponse createLoginResponse = wsClient.createLogin(createLoginRequest);
// check for errors
if (createLoginResponse == null)
throw new ApplicationException("No response from web service.");
if (!createLoginResponse.Success)
throw new ApplicationException(createLoginResponse.Message);
// process updateLoginResponse.Record
MessageBox.Show(String.Format("LoginId {0} created.", createLoginResponse.Record.LoginId));
}
catch (Exception ex)
{
if (wsClient != null) wsClient.Abort();
MessageBox.Show(ex.Message);
}
}

Getting User Information

Method

GetLoginResponse getLogin(GetLoginRequest request);

Description

This method is used to get information for an existing user account.
To call this method, you need to construct a GetLoginRequest object with the following properties:
public SecurityToken SecurityToken { get; set; } // see Creating a User
public new long? Id { get; set; }
public string Username { get; set; }
GetLoginResponse has the same properties as UpdateLoginResponse — see Creating a User.

C# Code Sample


private GetLoginResponse GetUserInfo(long userId)
{
RegentEnterpriseServiceClient wsClient = null;
GetLoginResponse getLoginResponse = null;
// CAUTION: don't wrap client in using statement:
// http://msdn.microsoft.com/en-us/library/aa355056.aspx
try
{
#region authenticate user – replace with appropriate implementation
SecurityToken securityToken = new SecurityToken()
{
Username = "system",
UserId = -1,
DashboardAdmin = true,
// provided by Regent. These would be config settings
ClientId = "CustomerClientId",
Token = "l23kj5hklj3h4l3kj"
};
#endregion authenticate user
// this would likely be a config setting
string wsUrl = "https://schoolremwsqa.regenteducation.net/RegentEnterpriseWebService.svc";
wsClient = new RegentEnterpriseServiceClient();
wsClient.Endpoint.Address = new System.ServiceModel.EndpointAddress(wsUrl);
// set up request
GetLoginRequest getLoginRequest = new GetLoginRequest();
getLoginRequest.SecurityToken = securityToken;
getLoginRequest.Id = userId;
// make call
getLoginResponse = wsClient.getLogin(getLoginRequest);
// check for errors
if (getLoginResponse == null)
throw new ApplicationException("No response from web service.");
if (!getLoginResponse.Success)
throw new ApplicationException(getLoginResponse.Message);
}
catch (Exception ex)
{
if (wsClient != null) wsClient.Abort();
throw ex;
}
return getLoginResponse;
}

Updating a User

Method

UpdateLoginResponse updateLogin(UpdateLoginRequest request);

Description

This method is used to update an existing user account.
This method takes the same UpdateLoginRequest object and returns the same UpdateLoginResponse object as createLogin() — see Creating a User. Prior to making updates, the UpdateLoginRequest.Record should be populated using getLogin() to pick up the current property values— see Getting User Information. Once populated, change the properties to be updated.

C# Code Sample


private void UpdateUserName(long userId, string newUserName)
{
RegentEnterpriseServiceClient wsClient = null;
// CAUTION: don't wrap client in using statement:
// http://msdn.microsoft.com/en-us/library/aa355056.aspx
try
{
#region authenticate user – replace with appropriate implementation
SecurityToken securityToken = new SecurityToken()
{
Username = "system",
UserId = -1,
DashboardAdmin = true,
// provided by Regent. These would be config settings
ClientId = "CustomerClientId",
Token = "l23kj5hklj3h4l3kj"
};
#endregion authenticate user
// this would likely be a config setting
string wsUrl = "https://schoolremwsqa.regenteducation.net/RegentEnterpriseWebService.svc";
wsClient = new RegentEnterpriseServiceClient();
wsClient.Endpoint.Address = new System.ServiceModel.EndpointAddress(wsUrl);
// get current user info
GetLoginResponse userInfo = GetUserInfo(userId);
#region perform update
// set up request
UpdateLoginRequest updateLoginRequest = new UpdateLoginRequest();
updateLoginRequest.SecurityToken = securityToken;
updateLoginRequest.Record = userInfo.Record;
// set the values being updated — LoginId and VersionStamp cannot be updated
// CreatedOn shouldn't be updated
updateLoginRequest.Record.Username = newUserName;
// make call
UpdateLoginResponse updateLoginResponse = wsClient.updateLogin(updateLoginRequest);
// check for errors
if (updateLoginResponse == null)
throw new ApplicationException("No response from web service.");
if (!updateLoginResponse.Success)
throw new ApplicationException(updateLoginResponse.Message);
#endregion perform update
// process updateLoginResponse.Record
MessageBox.Show(String.Format("{0} updated.", updateLoginResponse.Record.LoginId));
}
catch (Exception ex)
{
if (wsClient != null) wsClient.Abort();
MessageBox.Show(ex.Message);
}
}

Deleting a User

Method

UpdateLoginResponse deleteLogin(UpdateLoginRequest request);

Description

This method is used to deactivate an existing user account.
This method takes the same UpdateLoginRequest object and returns the same UpdateLoginResponse object as createLogin() — see Creating a User.

C# Code Sample


private void DeleteUser(long userId)
{
RegentEnterpriseServiceClient wsClient = null;
// CAUTION: don't wrap client in using statement:
// http://msdn.microsoft.com/en-us/library/aa355056.aspx
try
{
#region authenticate user – replace with appropriate implementation
SecurityToken securityToken = new SecurityToken()
{
Username = "system",
UserId = -1,
DashboardAdmin = true,
// provided by Regent. These would be config settings
ClientId = "CustomerClientId",
Token = "l23kj5hklj3h4l3kj"
};
#endregion authenticate user
// this would likely be a config setting
string wsUrl = "https://schoolremwsqa.regenteducation.net/RegentEnterpriseWebService.svc";
wsClient = new RegentEnterpriseServiceClient();
wsClient.Endpoint.Address = new System.ServiceModel.EndpointAddress(wsUrl);
// get current user info
GetLoginResponse userInfo = GetUserInfo(userId);
#region perform deletion
// set up request
UpdateLoginRequest deleteLoginRequest = new UpdateLoginRequest();
deleteLoginRequest.SecurityToken = securityToken;
deleteLoginRequest.Record = userInfo.Record;
// make call
UpdateLoginResponse deleteLoginResponse = wsClient.deleteLogin(deleteLoginRequest);
// check for errors
if (deleteLoginResponse == null)
throw new ApplicationException("No response from web service.");
if (!deleteLoginResponse.Success)
throw new ApplicationException(deleteLoginResponse.Message);
#endregion perform deletion
// process updateLoginResponse.Record
MessageBox.Show(String.Format("{0} deleted.", deleteLoginResponse.Record.LoginId));
}
catch (Exception ex)
{
if (wsClient != null) wsClient.Abort();
MessageBox.Show(ex.Message);
}
}

ROLE MANAGEMENT

Getting a List of Roles

Method

GetRoleListResponse getRoleList(GetRoleListRequest request);

Description

This method is used to obtain the roles that have been configured.
To call this method, you need to construct a GetRoleListRequest object with the following properties:
public SecurityToken SecurityToken { get; set; }
public string filterCondition { get; set; }
public string sortColumn { get; set; }
public string sortType { get; set; }
public int startRowIndex { get; set; }
public int endRowIndex { get; set; }
SecurityToken properties:
public long UserId { get; set; } // required
public bool DashboardAdmin { get; set; } // required
public string Username { get; set; } // required
public string CurrentRole { get; set; } // required
public string Token { get; set; } // required
public string ClientId { get; set; } // optional; used to support
// 3rd-party authentication
GetRoleListResponse has the following properties:
public List<RoleListItem> Records { get; set; }
public bool Success { get; set; }
public bool ErrorYN { get; set; }
public bool StaleEntity { get; set; }
public String Message { get; set; }
public int totalCount { get; set; }
public long processingTime { get; set; }
public ValidationResults ValidationResults { get; set; }
RoleListItem properties:
public Int64? RowNum { get; set; }
public Int32? TotalRows { get; set; }
ValidationResults properties:
public bool IsValid { get; set; }
public ValidationResult[] Results { get; set; }
ValidationResult properties:
public String Property { get; set; }
public String Message { get; set; }

C# Code Sample


private GetRoleListResponse GetRoleList()
{
RegentEnterpriseServiceClient wsClient = null;
GetRoleListResponse getRoleListResponse = null;
// CAUTION: don't wrap client in using statement:
// http://msdn.microsoft.com/en-us/library/aa355056.aspx
try
{
#region authenticate user – replace with appropriate implementation
SecurityToken securityToken = new SecurityToken()
{
Username = "system",
UserId = -1,
DashboardAdmin = true,
// provided by Regent. These would be config settings
ClientId = "CustomerClientId",
Token = "l23kj5hklj3h4l3kj"
};
#endregion authenticate user
// this would likely be a config setting
string wsUrl = "https://schoolremwsqa.regenteducation.net/RegentEnterpriseWebService.svc";
wsClient = new RegentEnterpriseServiceClient();
wsClient.Endpoint.Address = new System.ServiceModel.EndpointAddress(wsUrl);
// set up request
GetRoleListRequest getRoleListRequest = new GetRoleListRequest()
{
SecurityToken = securityToken,
filterCondition = "deleted = 0",
sortColumn = "name",
sortType = "desc",
startRowIndex = 0,
endRowIndex = 99999
};
// make call
getRoleListResponse = wsClient.getRoleList(getRoleListRequest);
// check for errors
if (getRoleListResponse == null)
throw new ApplicationException("No response from web service.");
if (!getRoleListResponse.Success)
throw new ApplicationException(getRoleListResponse.Message);
}
catch (Exception ex)
{
if (wsClient != null) wsClient.Abort();
throw ex;
}
return getRoleListResponse;
}

Getting a List of Roles for a Specific User

Method

GetRoleListResponse getRoleListByLogin(GetRoleListRequest request);

Description

This method is used to obtain the roles that have been configured for a specific user.
To call this method, you need to construct a GetRoleListRequest object with the following properties:
public SecurityToken SecurityToken { get; set; }
public long? LoginId { get; set; }
public string filterCondition { get; set; }
public string sortColumn { get; set; }
public string sortType { get; set; }
public int startRowIndex { get; set; }
public int endRowIndex { get; set; }
SecurityToken properties:
public long UserId { get; set; } // required
public bool DashboardAdmin { get; set; } // required
public string Username { get; set; } // required
public string CurrentRole { get; set; } // required
public string Token { get; set; } // required
public string ClientId { get; set; } // optional; used to support
// 3rd-party authentication
The GetLoginRoleResponse object is the same as for getRoleList() — see Get List of Roles.

C# Code Sample


private GetRoleListResponse GetRoleListForUser(long userId)
{
RegentEnterpriseServiceClient wsClient = null;
GetRoleListResponse getRoleListResponse = null;
// CAUTION: don't wrap client in using statement:
// http://msdn.microsoft.com/en-us/library/aa355056.aspx
try
{
#region authenticate user – replace with appropriate implementation
SecurityToken securityToken = new SecurityToken()
{
Username = "system",
UserId = -1,
DashboardAdmin = true,
// provided by Regent. These would be config settings
ClientId = "CustomerClientId",
Token = "l23kj5hklj3h4l3kj"
};
#endregion authenticate user
// this would likely be a config setting
string wsUrl = "https://schoolremwsqa.regenteducation.net/RegentEnterpriseWebService.svc";
wsClient = new RegentEnterpriseServiceClient();
wsClient.Endpoint.Address = new System.ServiceModel.EndpointAddress(wsUrl);
// set up request
GetRoleListRequest getRoleListRequest = new GetRoleListRequest()
{
SecurityToken = securityToken,
LoginId = userId,
filterCondition = "deleted = 0",
sortColumn = "name",
sortType = "desc",
startRowIndex = 0,
endRowIndex = 99999
};
// make call
getRoleListResponse = wsClient.getRoleListByLogin(getRoleListRequest);
// check for errors
if (getRoleListResponse == null)
throw new ApplicationException("No response from web service.");
if (!getRoleListResponse.Success)
throw new ApplicationException(getRoleListResponse.Message);
}
catch (Exception ex)
{
if (wsClient != null) wsClient.Abort();
throw ex;
}
return getRoleListResponse;
}

USER ROLE MANAGEMENT

Updating User role assignments

Method

UpdateLoginRoleListResponse updateLoginRoleList(UpdateLoginRoleListRequest request);

Description

This method is used to assign or remove one or more users from a single role.
Example to be provided.

C# Code Sample


Example to be provided.

Getting User Role Information

Method

GetLoginRoleResponse getLoginRole(GetLoginRoleRequest request);

Description

This method is used to get role information for an existing user role.
To call this method, you need to construct a GetLoginRoleRequest object with the following properties:
public SecurityToken SecurityToken { get; set; } // see Creating a User
public new long? Id { get; set; }
GetLoginRoleResponse has the same properties as UpdateLoginRoleResponse — see Assigning a User to a Role.

C# Code Sample

private GetLoginRoleResponse GetUserRoleInfo(long loginRoleId)
{
RegentEnterpriseServiceClient wsClient = null;
GetLoginRoleResponse getLoginRoleResponse = null;
// CAUTION: don't wrap client in using statement:
// http://msdn.microsoft.com/en-us/library/aa355056.aspx
try
{
#region authenticate user – replace with appropriate implementation
SecurityToken securityToken = new SecurityToken()
{
Username = "system",
UserId = -1,
DashboardAdmin = true,
// provided by Regent. These would be config settings
ClientId = "CustomerClientId",
Token = "l23kj5hklj3h4l3kj"
};
#endregion authenticate user
// this would likely be a config setting
string wsUrl = "https://schoolremwsqa.regenteducation.net/RegentEnterpriseWebService.svc";
wsClient = new RegentEnterpriseServiceClient();
wsClient.Endpoint.Address = new System.ServiceModel.EndpointAddress(wsUrl);
// set up request
GetLoginRoleRequest getLoginRoleRequest = new GetLoginRoleRequest();
getLoginRoleRequest.SecurityToken = securityToken;
getLoginRoleRequest.Id = loginRoleId; // loginRoleId - required
// make call
getLoginRoleResponse = wsClient.getLoginRole(getLoginRoleRequest);
// check for errors
if (getLoginRoleResponse == null)
throw new ApplicationException("No response from web service.");
if (!getLoginRoleResponse.Success)
throw new ApplicationException(getLoginRoleResponse.Message);
}
catch (Exception ex)
{
if (wsClient != null) wsClient.Abort();
throw ex;
}
return getLoginRoleResponse;
}

DOCUMENT MANAGEMENT

Creating a Document

Method

UpdateDocumentRequirementResponse createDocumentRequirement(UpdateDocumentRequirementRequest request);

Description

This method is used to create a new document for a student.
To call this method, you need to construct a UpdateDocumentRequirementRequest object with the following properties:
public SecurityToken SecurityToken { get; set; }
public Login Record { get; set; }
SecurityToken properties:
public long UserId { get; set; } // required
public bool DashboardAdmin { get; set; } // required
public string Username { get; set; } // required
public string CurrentRole { get; set; } // required
public string Token { get; set; } // required
public string ClientId { get; set; } // optional; used to support
// 3rd-party authentication
DocumentRequirement properties:
public Int64 documentRequirementId { get; set; } // required
public Int64 studentId { get; set; } // required
public String documentIdString { get; set; } // required
public String ActivitySourceTypeCode { get; set; } // required; 50 chars max
public String ActivityLogEntryTypeCode { get; set; } // required; 50 chars max
public String documentRequirementStatusName { get; set; }
public Int64 documentId { get; set; }
public String documentName { get; set; } // optional; 35 chars max
public String documentDescription { get; set; }
public String documentUseTypeCode { get; set; } // optional; 50 chars max
public String documentUseTypeName { get; set; }
public DateTime? letterCorrespondenceDate { get; set; }
public DateTime? emailCorrespondenceDate { get; set; }
public DateTime? LastEmailLetterCorrespondenceDate { get; set; }
public DateTime? receivedDate { get; set; }
public DateTime? reviewedDate { get; set; }
public DateTime? createdDate { get; set; }
public String activitySourceName { get; set; } // optional; 50 chars max
public String activityTypeName { get; set; } // optional; 50 chars max
public String documentRequirementStatusCode { get; set; }
public Int64 federalAwardYearId { get; set; }
public Int64 academicYearId { get; set; }
public Int64 paymentPeriodId { get; set; }
public String federalAwardYearName { get; set; }
public String academicYearName { get; set; }
public String paymentPeriodName { get; set; }
public String ScopeName { get; set; }
public String documentMessage { get; set; }
public String message { get; set; } // optional; 256 chars max
public String Notes { get; set; } // optional; 250 chars max
public String documentTemplateFileName { get; set; }
public Boolean hasDocumentFlag { get; set; }
public String fileName { get; set; } // optional; 256 chars max
public String storedFileName { get; set; } // optional; 256 chars max
public Byte[] storedFile { get; set; }
public String fileURL { get; set; }
public String mimeType { get; set; } // optional; 255 chars max
public String documentFileName { get; set; } // optional; 256 chars max
public String documentStoredFileName { get; set; } // optional; 256 chars max
public String documentScopeCode { get; set; } // optional; 50 chars max
public String documentScopeName { get; set; }
public String documentIsirScopeCode { get; set; } // optional; 50 chars max
public String documentIsirScopeName { get; set; }
public Boolean assignedByOfficeUseOnly { get; set; }
public Int32 fileSize { get; set; }
public String DocumentInformation { get; set; }
public String DocumentRequirementExternalId { get; set; }
public String documentExternalId { get; set; }
public String studentExternalId1 { get; set; }
public String studentExternalId2 { get; set; }
public String studentExternalId3 { get; set; }
public String studentExternalId4 { get; set; }
public Int64? assignISIRRecordDataId { get; set; }
public Int64? satisfyISIRRecordDataId { get; set; }
public DateTime? EditLockTimestamp { get; set; }
public Boolean UpdateAttachment { get; set; }
public Boolean assignedByISIR { get; set; }
public string assignedBy { get; set; }
public string typeOfAssignedBy { get; set; }
public string valueOfAssignedBy { get; set; }
public DateTime documentRequirementStatusChangeOnDate { get; set; }
UpdateDocumentRequirementResponse has the following properties:
public DocumentRequirement Record { get; set; } // see above
public bool Success { get; set; }
public bool ErrorYN { get; set; }
public bool StaleEntity { get; set; }
public String Message { get; set; }
public int totalCount { get; set; }
public long processingTime { get; set; }
public ValidationResults ValidationResults { get; set; }
ValidationResults properties:
public bool IsValid { get; set; }
public ValidationResult[] Results { get; set; }
ValidationResult properties:
public String Property { get; set; }
public String Message { get; set; }

C# Code Sample


private void CreateDocumentRequirement()
{
RegentEnterpriseServiceClient wsClient = null;
// CAUTION: don't wrap client in using statement:
// http://msdn.microsoft.com/en-us/library/aa355056.aspx
try
{
#region authenticate user – replace with appropriate implementation
SecurityToken securityToken = new SecurityToken()
{
Username = "system",
UserId = -1,
DashboardAdmin = true,
// provided by Regent. These would be config settings
ClientId = "CustomerClientId",
Token = "l23kj5hklj3h4l3kj"
};
#endregion authenticate user
// this would likely be a config setting
string wsUrl = "https://schoolremwsqa.regenteducation.net/RegentEnterpriseWebService.svc";
wsClient = new RegentEnterpriseServiceClient();
wsClient.Endpoint.Address = new System.ServiceModel.EndpointAddress(wsUrl);
// set up request
UpdateDocumentRequirementRequest createDocumentRequirementRequest = new
UpdateDocumentRequirementRequest();
createDocumentRequirementRequest.SecurityToken = securityToken;
createDocumentRequirementRequest.Record = new DocumentRequirement()
{
documentId = "10960",
studentId = "27049",
ActivitySourceTypeCode = "SYSTEMACTION",
ActivityLogEntryTypeCode = "10960",
documentRequirementStatusCode = "Other",
};
// make call
UpdateDocumentRequirementResponse createDocumentrequirementResponse =
wsClient.createDocumentRequirement(createDocumentRequirementRequest);
// check for errors
if (createDocumentrequirementResponse == null)
throw new ApplicationException("No response from web service.");
if (!createDocumentrequirementResponse.Success)
throw new ApplicationException(createDocumentrequirementResponse.Message);
// process updateDocumentrequirementResponse.Record
MessageBox.Show(String.Format("documentRequirementId {0} created.",
createDocumentrequirementResponse.Record.documentRequirementId));
}
catch (Exception ex)
{
if (wsClient != null) wsClient.Abort();
MessageBox.Show(ex.Message);
}
}

Getting Document Information

Method

GetDocumentRequirementResponse getDocumentRequirement(GetDocumentRequirementRequest request);

Description

This method is used to get document information for an existing document.
To call this method, you need to construct a GetDocumentRequirementRequest object with the following properties:
public SecurityToken SecurityToken { get; set; } // see Creating a Document
public new long? Id { get; set; }
GetDocumentRequirementResponse has the same properties as UpdateDocumentRequirementResponse — see Creating a Document.

C# Code Sample


private GetDocumentRequirementResponse GetDocumentRequirementInfo(long documentRequirementId)
{
RegentEnterpriseServiceClient wsClient = null;
GetDocumentRequirementResponse getDocumentRequirementResponse = null;
// CAUTION: don't wrap client in using statement:
// http://msdn.microsoft.com/en-us/library/aa355056.aspx
try
{
#region authenticate user – replace with appropriate implementation
SecurityToken securityToken = new SecurityToken()
{
Username = "system",
UserId = -1,
DashboardAdmin = true,
// provided by Regent. These would be config settings
ClientId = "CustomerClientId",
Token = "l23kj5hklj3h4l3kj"
};
#endregion authenticate user
// this would likely be a config setting
string wsUrl = "https://schoolremwsqa.regenteducation.net/RegentEnterpriseWebService.svc";
wsClient = new RegentEnterpriseServiceClient();
wsClient.Endpoint.Address = new System.ServiceModel.EndpointAddress(wsUrl);
// set up request
GetDocumentRequirementRequest getDocumentRequirementRequest = new
GetDocumentRequirementRequest ();
getDocumentRequirementRequest.SecurityToken = securityToken;
getDocumentRequirementRequest.Id = documentRequirementId;
// make call
getDocumentRequirementResponse = wsClient.getDocumentRequirement(getDocumentRequirementRequest);
// check for errors
if (getDocumentRequirementResponse == null)
throw new ApplicationException("No response from web service.");
if (!getDocumentRequirementResponse.Success)
throw new ApplicationException(getDocumentRequirementResponse.Message);
}
catch (Exception ex)
{
if (wsClient != null) wsClient.Abort();
throw ex;
}
return getDocumentRequirementResponse;
}

Getting a List of Documents

Method

GetDocumentRequirementListResponse getDocumentRequirementList(GetDocumentRequirementListRequest request);

Description

This method is used to get a list of documents, e.g., for a specified student.
To call this method, you need to construct a GetDocumentRequirementListRequest object with the following properties:
public SecurityToken SecurityToken { get; set; }
public string filterCondition { get; set; }
public string sortColumn { get; set; }
public string sortType { get; set; }
public int startRowIndex { get; set; }
public int endRowIndex { get; set; }
SecurityToken properties:
public long UserId { get; set; } // required
public bool DashboardAdmin { get; set; } // required
public string Username { get; set; } // required
public string CurrentRole { get; set; } // required
public string Token { get; set; } // required
public string ClientId { get; set; } // optional; used to support
// 3rd-party authentication
GetDocumentRequirementListResponse has the following properties:
public List<DocumentRequirement> Records { get; set; }
public bool Success { get; set; }
public bool ErrorYN { get; set; }
public bool StaleEntity { get; set; }
public String Message { get; set; }
public int totalCount { get; set; }
public long processingTime { get; set; }
public ValidationResults ValidationResults { get; set; }
RoleListItem properties:
public Int64? RowNum { get; set; }
public Int32? TotalRows { get; set; }
ValidationResults properties:
public bool IsValid { get; set; }
public ValidationResult[] Results { get; set; }
ValidationResult properties:
public String Property { get; set; }
public String Message { get; set; }

C# Code Sample


private GetDocumentRequirementListResponse GetDocumentRequirementList(long studentId)
{
RegentEnterpriseServiceClient wsClient = null;
GetDocumentRequirementListResponse getDocumentRequirementListResponse = null;
// CAUTION: don't wrap client in using statement:
// http://msdn.microsoft.com/en-us/library/aa355056.aspx
try
{
#region authenticate user – replace with appropriate implementation
SecurityToken securityToken = new SecurityToken()
{
Username = "system",
UserId = -1,
DashboardAdmin = true,
// provided by Regent. These would be config settings
ClientId = "CustomerClientId",
Token = "l23kj5hklj3h4l3kj"
};
#endregion authenticate user
// this would likely be a config setting
string wsUrl = "https://schoolremwsqa.regenteducation.net/RegentEnterpriseWebService.svc";
wsClient = new RegentEnterpriseServiceClient();
wsClient.Endpoint.Address = new System.ServiceModel.EndpointAddress(wsUrl);
// set up request
GetDocumentRequirementListRequest getDocumentRequirementListRequest =
new GetDocumentRequirementListRequest ()
{
SecurityToken = securityToken,
// restrict list to documents for a single student
filterCondition = String.Format("[studentId]={0}", studentId),
sortExpression = "", // optional
startRowIndex = 1,
endRowIndex = 10
};
// make call
getDocumentRequirementListResponse =
wsClient.getDocumentRequirementList(getDocumentRequirementListRequest);
// check for errors
if (getDocumentRequirementListResponse == null)
throw new ApplicationException("No response from web service.");
if (!getDocumentRequirementListResponse.Success)
throw new ApplicationException(getDocumentRequirementListResponse.Message);
}
catch (Exception ex)
{
if (wsClient != null) wsClient.Abort();
throw ex;
}
return getDocumentRequirementListResponse;
}

Updating a Document

Method

UpdateDocumentRequirementResponse updateDocumentRequirement(UpdateDocumentRequirementRequest request);

Description

This method is used to update an existing document.
This method takes the same UpdateDocumentRequirementRequest object and returns the same UpdateDocumentRequirementResponse object as createDocumentRequirement() — see Creating a Document. Prior to making updates, the UpdateDocumentRequirementRequest.Record should be populated using getDocumentRequirement() to pick up the current property values— see Getting Document Information. Once populated, change the properties to be updated.

C# Code Sample


private void UpdateDocumentRequirementNotes(long documentRequirementId, string notes)
{
RegentEnterpriseServiceClient wsClient = null;
// CAUTION: don't wrap client in using statement:
// http://msdn.microsoft.com/en-us/library/aa355056.aspx
try
{
#region authenticate user – replace with appropriate implementation
SecurityToken securityToken = new SecurityToken()
{
Username = "system",
UserId = -1,
DashboardAdmin = true,
// provided by Regent. These would be config settings
ClientId = "CustomerClientId",
Token = "l23kj5hklj3h4l3kj"
};
#endregion authenticate user
// this would likely be a config setting
string wsUrl = "https://schoolremwsqa.regenteducation.net/RegentEnterpriseWebService.svc";
wsClient = new RegentEnterpriseServiceClient();
wsClient.Endpoint.Address = new System.ServiceModel.EndpointAddress(wsUrl);
// get current document info
GetDocumentRequirementResponse documentRequirementInfo =
GetDocumentRequirementInfo(documentRequirementId);
#region perform update
// set up request
UpdateDocumentRequirementRequest updateDocumentRequirementRequest =
new UpdateDocumentRequirementRequest()
{
SecurityToken = securityToken,
Record = documentRequirementInfo.Record
};
// set the values being updated — LoginId and VersionStamp cannot be updated
// CreatedOn shouldn't be updated
updateDocumentRequirementRequest.Record.Notes = notes;
// make call
UpdateDocumentRequirementResponse updateDocumentRequirementResponse =
wsClient.updateDocumentRequirement(updateDocumentRequirementRequest);

// check for errors
if (updateDocumentRequirementResponse == null)
throw new ApplicationException("No response from web service.");
if (!updateDocumentRequirementResponse.Success)
throw new ApplicationException(updateDocumentRequirementResponse.Message);
#endregion perform update
// process updateLoginResponse.Record
MessageBox.Show(String.Format("{0} updated.",
updateDocumentRequirementResponse.Record.documentRequirementId));
}
catch (Exception ex)
{
if (wsClient != null) wsClient.Abort();
MessageBox.Show(ex.Message);
}
}

Deleting a Document

Method

UpdateDocumentRequirementResponse deleteDocumentRequirement(UpdateDocumentRequirementRequest request);

Description

This method is used to delete an existing document.
This method takes the same UpdateDocumentRequirementRequest object and returns the same UpdateDocumentRequirementResponse object as createDocumentRequirement () — see Creating a Document.

C# Code Sample


private void DeleteDocumentRequirement(long documentRequirementId)
{
RegentEnterpriseServiceClient wsClient = null;
// CAUTION: don't wrap client in using statement:
// http://msdn.microsoft.com/en-us/library/aa355056.aspx
try
{
#region authenticate user – replace with appropriate implementation
SecurityToken securityToken = new SecurityToken()
{
Username = "system",
UserId = -1,
DashboardAdmin = true,
// provided by Regent. These would be config settings
ClientId = "CustomerClientId",
Token = "l23kj5hklj3h4l3kj"
};
#endregion authenticate user
// this would likely be a config setting
string wsUrl = "https://schoolremwsqa.regenteducation.net/RegentEnterpriseWebService.svc";
wsClient = new RegentEnterpriseServiceClient();
wsClient.Endpoint.Address = new System.ServiceModel.EndpointAddress(wsUrl);
// get current document info
GetDocumentRequirementResponse documentRequirementInfo =
GetDocumentRequirementInfo(documentRequirementId);
#region perform deletion
// set up request
UpdateDocumentRequirementRequest deleteDocumentRequirementRequest =
new UpdateDocumentRequirementRequest()
{
SecurityToken = securityToken,
Record = documentRequirementInfo.Record
};
// make call
UpdateDocumentRequirementResponse deleteDocumentRequirementResponse =
wsClient.deleteDocumentRequirement(deleteDocumentRequirementRequest);
// check for errors
if (deleteDocumentRequirementResponse == null)
throw new ApplicationException("No response from web service.");
if (!deleteDocumentRequirementResponse.Success)
throw new ApplicationException(deleteDocumentRequirementResponse.Message);
#endregion perform deletion
// process updateLoginResponse.Record
MessageBox.Show(String.Format("{0} deleted.",
deleteDocumentRequirementResponse.Record.documentRequirementId));
}
catch (Exception ex)
{
if (wsClient != null) wsClient.Abort();
MessageBox.Show(ex.Message);
}
}

STUDENT MANAGEMENT

Get External IDs for a Student

Method

GetStudentExternalIdsResponse getStudentExternalIds(GetStudentExternalIdsRequest request);

Description

This method is used to get the external (institution's) IDs associated with a Regent student ID.
To call this method, you need to construct a GetStudentExternalIdsRequest object with the following properties:
public SecurityToken SecurityToken { get; set; }
public StudentExternalIds Record { get; set; }
SecurityToken properties:
public long UserId { get; set; } // required
public bool DashboardAdmin { get; set; } // required
public string Username { get; set; } // required
public string CurrentRole { get; set; } // required
public string Token { get; set; } // required
public string ClientId { get; set; } // optional; used to support
// 3rd-party authentication
StudentExternalIds properties:
public Int64 Id { get; set; }
public Int64 LocationId { get; set; }
public String ExternalId1 { get; set; }
public String ExternalId2 { get; set; }
public String ExternalId3 { get; set; }
public String ExternalId4 { get; set; }
GetStudentExternalIdsResponse has the following properties:
public StudentExternalIds Record { get; set; } // see above
public bool Success { get; set; }
public bool ErrorYN { get; set; }
public bool StaleEntity { get; set; }
public String Message { get; set; }
public int totalCount { get; set; }
public long processingTime { get; set; }
public ValidationResults ValidationResults { get; set; }
ValidationResults properties:
public bool IsValid { get; set; }
public ValidationResult[] Results { get; set; }
ValidationResult properties:
public String Property { get; set; }
public String Message { get; set; }

C# Code Sample


private void GetStudentExternalIds(long studentId)
{
RegentEnterpriseServiceClient wsClient = null;
// CAUTION: don't wrap client in using statement:
// http://msdn.microsoft.com/en-us/library/aa355056.aspx
try
{
#region authenticate user – replace with appropriate implementation
SecurityToken securityToken = new SecurityToken()
{
Username = "system",
UserId = -1,
DashboardAdmin = true,
// provided by Regent. These would be config settings
ClientId = "CustomerClientId",
Token = "l23kj5hklj3h4l3kj"
};
#endregion authenticate user
// this would likely be a config setting
string wsUrl = "https://schoolremwsqa.regenteducation.net/RegentEnterpriseWebService.svc";
wsClient = new RegentEnterpriseServiceClient();
wsClient.Endpoint.Address = new System.ServiceModel.EndpointAddress(wsUrl);
// set up request
GetStudentExternalIdsRequest getStudentExternalIdsRequest = new GetStudentExternalIdsRequest()
{
SecurityToken = securityToken,
Id = studentId
};
// make call
GetStudentExternalIdsResponse getStudentExternalIdsResponse = wsClient.getStudentExternalIds(getStudentExternalIdsRequest);
// check for errors
if (getStudentExternalIdsResponse == null)
throw new ApplicationException("No response from web service.");
if (!getStudentExternalIdsResponse.Success)
throw new ApplicationException(getStudentExternalIdsResponse.Message);
// process updateDocumentrequirementResponse.Record
var record = getStudentExternalIdsResponse.Record;
string msg = String.Format("External IDs for student ID {0}:" + Environment.NewLine +
"\tExternal ID 1: {1}" + Environment.NewLine +
"\tExternal ID 2: {2}" + Environment.NewLine +
"\tExternal ID 3: {3}" + Environment.NewLine +
"\tExternal ID 4: {4}" + Environment.NewLine,
studentId, record.ExternalId1, record.ExternalId2,
record.ExternalId3, record.ExternalId4);
MessageBox.Show(msg);
}
catch (Exception ex)
{
if (wsClient != null) wsClient.Abort();
MessageBox.Show(ex.Message);
}
}

REVISION NOTES

Version 0.5

SecurityToken class:

  • added ClientId field to support 3rd-party authentication

DocumentRequirement class:

  • removed receivedTime field
  • removed receivedTime field
  • added EditLockTimestamp field

Login class:

  • Password field now optional (if 3rd-party authentication is being used)
  • PasswordSetDate now optional
  • added LoginAuthenticationTypeCode field
  • added SingleSignOnCode field
  • added documentation the following fields:*
    • PasswordSalt
    • LockoutAttempts
    • LockoutDate
    • LastLoginDate
    • PasswordExpiresOn
    • UTCOffset
    • Timezone
    • ExternalId1
    • ExternalId2

* The fields were always present, just not documented.

  • No labels