Skip to main content

IT Provisioning - Web Service API Security/Access Listing

Receiving Agency Related Guide (RARG)

Summary:
Authorized users can use this Web Service to retrieve current data about students who require computer/network access during an upcoming placement at their sites. In addition to student names and placement locations/dates, the Listing will include student email addresses if the school-issued email address has been released to Receiving Agencies.

Background
With consent, a student's name is released to Receiving Agencies, in general once the placement is Accepted by the site and Confirmed by the Placing Agency (school). The school-issued email address for the student will also be released if:

  • the student has an HSPnet account and enters his/her consent to release their email address to site contacts; or
  • the Placing Agency has enabled the feature to release student email addresses automatically via the Security/Access Listing wizard that is available to Receiving Agencies. To enable this feature, see the Quick Reference Guide for Placing Agencies entitled Release of Student Emails for Computer Access.

An Application Programming Interface (API) specifies how two information systems can exchange data. HSPnet offers a Web Service API to Receiving Agencies that wish to automate the retrieval of data that is available via the Security/Access Listing wizard, as an XML file.

User Authorization
An active user account, at the level of Local Administrator, must be held by a named individual who will access the Web Service or be responsible for its use. Shared user accounts are not permitted as per the National HSPnet Policies. Each user account must include a non-shared email address for secure delivery of passwords and contact or escalation of issues by Help Desk.
Account approval is required from a senior manager of the Receiving Agency with an organizational role that includes student placements and the requested site(s). Typically, this individual is already identified in HSPnet as a Department Contact for the purpose of authorizing new user accounts at the Local Administrator level.
Requests for access should be directed to the Help Desk at support@hspcanada.net. Please include the following information:

  • Name, title and email address for the Department Contact or senior manager who is authorizing access to the Web Service
  • Name of the Web Service to be accessed – e.g. "API-001: Security/Access Listing"
  • Name, title and email address for the individual to have access
  • Sites, Services, Destinations and Disciplines to be included in the XML output file
  • Proposed start date - allow a minimum of 5 working days
  • A request for the password to "never expire" if the login will be automated

Accessing the Web Service
Authorized users will be provided with the URL for their province, web service, and account ID, such as:

https://localservername/HSPnetxx/WebServices/PlacementService.asmx/SecurityAccess?user=YOURUSERID&pw=YOURPASSWORD&RAList=n/a&Start=2020/Jul/01&End=2020/Aug/31

The highlighted variables above must be specified for each request via the web service:

localservername

To be provided by Help Desk for each new web service account

HSPnetxx

YOURUSERID

HSPnet user ID to be sent via automated email when the account is created

YOURPASSWORD

Permanent password to be set by the user upon their first login

2020/Jul/01

First date of the date range to be included

2020/Aug/31

Last date of the date range to be included

Web Service Output
The web service will return an XML file of all HSPnet placements that are active within the specified date range, if a student is assigned AND their name is released to the Receiving Agency. A placement is considered active in the date range if any placement dates overlap as per the diagram.


The conditions for release of student name are:

  • The placement request has a status of Accepted (by Receiving Agency) and Confirmed (by Placing Agency);

  • A student is assigned to the placement by the Placing Agency;

  • The student's consent to release their personal information is not expired;

  • The student's name is released to the Receiving Agency, which occurs:

    • automatically when the placement is Confirmed; or
    • before the placement is Confirmed if student name is released early by the Placing Agency as per the national policies.

The XML file consists of one or more <PlacementSecurityAccess> elements, each of which contains the data fields as defined in Appendix 1. The data categories are:

  • Placing Agency – Agency, faculty or Department, educational Program, and discipline
  • Placement Information – unique reference number For a Group placement (2 or more students) the same reference number would be used for each assigned student., type of placement, and start/end dates for each student
  • Instructor – name and contact information of the individual who supervises students in an instructor-led Group Typically, the instructor leading a Group also requires computer/network access. In Quebec, some educational Programs may ask the Receiving Agency to assign a Site Instructor, who would be an employee of the Site. or who is assigned as a facilitator or contact for individual placements
  • Student – name of the student assigned to the placement space, plus email address if released by the Placing Agency


Here is a sample of the XML output in a browser:

Error Messages
The Web Service can return the following error messages:

Error Message

Cause of error

User ID or password is invalid. You have xx login attempts remaining before this user account is locked out.

Invalid User ID and/or Password

(first 4 failed attempts)

Your account has been disabled. To reactivate your account, contact your HSPnet Local Administrator for your organization or contact support@hspcanada.net

Invalid User ID and/or Password

(5th and subsequent failed attempts)

Access Denied

User ID is not authorized to access the Web Service

Important Information about HSPnet ID for Students and Instructors 

The HSPnet ID number is a unique identifier that is tracked in HSPnet for people in the role of Student or Staff (instructor).  Local systems that use these numbers must differentiate between the two roles in order to avoid duplicates – e.g. to ensure that a student with HSPnet ID #555 does not overlap with an instructor with HSPnet ID #555.  We recommend use of a prefix (e.g. “S” or “E”) to differentiate between students and instructors (educators), respectively.

Entity Name

Definition

Example(s)

Edit Rights [1]
PlcAgencyName Name of the Placing Agency University of British Columbia Help Desk
PlcAgencyShortName Short name of the Placing Agency UBC Help Desk
DepartmentName Name of the Department (faculty of staffing department) Faculty of Nursing Users
DepartmentShortName Short name of the Department Nursing Users
ProgramName Name of the educational program Bachelor of Science in Nursing Help Desk
ProgramShortName Short name of the educational program BScN Help Desk
ProgramEndDate Expected end date of the educational program, for administrative purposes (e.g. termination of computer access) Jun 30/20 Users
Discipline Discipline of Program Nursing DBA
SubDiscipline Sub-Discipline of Program Bacc Nursing DBA
SubDisciplineShortName Short name of the sub-discipline of Program NurBacc DBA
CourseName Name of the practicum Course Nursing practice - critical care Users
CourseShortName Short name of the practicum Course NURS400 Users
PRD_ID Unique reference number of the placement request 25378 System
PRType Type of placement
  • Instructor-led Group
  • Preceptorship
 Users
PRStartDate Start date of the placement Jan 1/20 Users
PREndDate End date of the placement Jan 31/20 Users
InstructorLastName Last name of the instructor assigned by the Placing Agency Tremblay Users
InstructorFirstName First name of the instructor Gabriela Users
InstructorMiddleName Middle name or initial of the instructor Jean ou J Users
InstructorID Unique database ID of the Instructor, assigned by HSPnet HSP5242 System
InstructorEmail Email address of the instructor gabriela.tremblay@ubcl.ca Users
InstructorPhone Phone number of the instructor 604 555 1234 Users
RcvAgencyName Name of the Receiving Agency Provincial Health Services Authority Help Desk
RcvAgencyShortName Short name of the Receiving Agency PHSA Help Desk
SiteName Name of the receiving site Sunny Hill Hospital Users
SiteShortName Short name of the receiving site SunnyHill Users
ServiceName Name of the receiving service Medicine - inpatients Help Desk
ServiceShortName Short name of the receiving service MedicineIP Help Desk
DestinationName Name of the receiving destination 2 South Users
DestinationShortName Short name of the receiving destination 2South Users
DestinationContactName First and last names of the Destination Contact for the discipline Mary Wilson Users
DestinationContactEmail Email address of the Destination Contact marywilson@phsa.ca Users
SupervisorLastName Last name of the Supervisor assigned by the Receiving Agency Deval Users
SupervisorFirstName First name of the Supervisor Lena Users
SupervisorEmail Email address of the Supervisor lenadeval@phsa.ca

Users
StudentLastName Last name of the Student Wong Users
StudentFirstName First name of the Student Marian Users
StudentMiddleName Middle name or initial of the Student Janet or J Users
StudentID

Unique database ID of the student, issued by HSPnet

NOTE this is not the student number issued by the Placing Agency

 HSP9247 System
StudentRegBody [2] Name of the registration body that issued the student's registration ID RN Association of XX Users
StudentRegID [2] ID number issued by the student's registration body 938572484 Users
StudentEmail [3] Primary email address of the Student [1](mailto:24795@umontreal.ca)2345@ubc.ca Users
ProgramYear Year of program 3 Users
PlacementAtWork Indicator of whether the placement is at work (student employed by the site) false Users

[1] indicates whether the column values can be modified by:

  • Users - subject to change at any time
  • Help Desk - changes are less frequent and in accordance with national data standards
  • DBA - changes are rare and users of the web service would be consulted and/or notified in advance
  • System - automatically assigned by the database and non-modifiable

[2] This data will be non-blank only if the Placing Agency has enabled the feature to release Registration ID

[3] This data will be non-blank only if the Placing Agency has enabled the feature to release email address; if not released the data value will be "WITHHELD"

Getting Help 
For questions or assistance with using this web service, please contact support@hspcanada.net .






Back to top