Skip to main content

IT Provisioning - Web Service API Security/Access Listing

                        1. 
                                <span>[Knowledge Base](index.html)</span>
                            
                                            
                </div>
                # &#10;                                                <span id="title-text">&#10;                            Knowledge Base : IT Provisioning - Web Service API Security/Access Listing&#10;                        </span>&#10;                    
            </div>

            <div id="content" class="view">
                <div class="page-metadata">
                    
    


    

    
    
        Created by <span class="author"> user-b1fcb</span>, last modified by <span class="editor"> Erik Graham</span> on Aug 09, 2021
                    </div>
                <div id="main-content" class="wiki-content group">
                **

Receiving Agency Related Guide (RARG)****Summary:**

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-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-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-access
  • Sites, Services, Destinations and Disciplines to be included in the XML output file-file
  • Proposed start date - allow a minimum of 5 working days-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/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.

Invalide 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 HSPnetID #555 does not overlap with an instructor with HSPnetID #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]

PlcAgencyNameName of the Placing AgencyUniversity of British ColumbiaHelp Desk
PlcAgencyShortNameShort name of the Placing AgencyUBCHelp Desk
DepartmentNameName of the Department (faculty of staffing department)Faculty of NursingUsers
DepartmentShortNameShort name of the DepartmentNursingUsers
ProgramNameName of the educational programBachelor of Science in NursingHelp Desk
ProgramShortNameShort name of the educational programBScNHelp Desk
ProgramEndDateExpected end date of the educational program, for administrative purposes (e.g. termination of computer access)Jun 30/20Users
DisciplineDiscipline of ProgramNursingDBA
SubDisciplineSub-Discipline of ProgramBacc NursingDBA
SubDisciplineShortNameShort name of the sub-discipline of ProgramNurBaccDBA
CourseNameName of the practicum CourseNursing practice - critical careUsers
CourseShortNameShort name of the practicum CourseNURS400Users
PRD_IDUnique reference number of the placement request25378System
PRTypeType of placement
  • Instructor-led Group
  • Preceptorship
Users
PRStartDateStart date of the placementJan 1/20Users
PREndDateEnd date of the placementJan 31/20Users
InstructorLastNameLast name of the instructor assigned by the Placing AgencyTremblayUsers
InstructorFirstNameFirst name of the instructorGabrielaUsers
InstructorMiddleNameMiddle name or initial of the instructorJean ou JUsers
InstructorIDUnique database ID of the Instructor, assigned by HSPnetHSP5242System
InstructorEmailEmail address of the instructorgabriela.tremblay@ubcl.caUsers
InstructorPhonePhone number of the instructor604 555 1234Users
RcvAgencyNameName of the Receiving AgencyProvincial Health Services AuthorityHelp Desk
RcvAgencyShortNameShort name of the Receiving AgencyPHSAHelp Desk
SiteNameName of the receiving siteSunny Hill HospitalUsers
SiteShortNameShort name of the receiving siteSunnyHillUsers
ServiceNameName of the receiving serviceMedicine - inpatientsHelp Desk
ServiceShortNameShort name of the receiving serviceMedicineIPHelp Desk
DestinationNameName of the receiving destination2 SouthUsers
DestinationShortNameShort name of the receiving destination2SouthUsers
DestinationContactNameFirst and last names of the Destination Contact for the disciplineMary WilsonUsers
DestinationContactEmailEmail address of the Destination Contactmarywilson@phsa.caUsers
SupervisorLastNameLast name of the Supervisor assigned by the Receiving AgencyDevalUsers
SupervisorFirstNameFirst name of the SupervisorLenaUsers
SupervisorEmailEmail address of the Supervisorlenadeval@phsa.ca

Users

StudentLastNameLast name of the StudentWongUsers
StudentFirstNameFirst name of the StudentMarianUsers
StudentMiddleNameMiddle name or initial of the StudentJanet or JUsers
StudentID

Unique database ID of the student, issued by HSPnet

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

HSP9247System
StudentRegBody [2]Name of the registration body that issued the student's registration IDRN Association of XXUsers
StudentRegID [2]ID number issued by the student's registration body938572484Users
StudentEmail [3]Primary email address of the Student[1](mailto:24795@umontreal.ca)2345@ubc.caUsers
ProgramYearYear of program3Users
PlacementAtWorkIndicator of whether the placement is at work (student employed by the site)falseUsers

[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 .





## Attachments:
                    <div class="greybox" align="left">
                                                        ![](images/icons/bullet_blue.gif)
                            [worddav68ae31fd646ea2c673f0f78beca2b03a.png](attachments/10782089/10782088.png) (image/png)
                              

                                                        ![](images/icons/bullet_blue.gif)
                            [worddav938233ce15774b2beb0592c7484d2d0b.png](attachments/10782089/10782090.png) (image/png)
                              

                                                        ![](images/icons/bullet_blue.gif)
                            [worddavdd409ac64cac8872b5b08011a9cd6082.png](attachments/10782089/10782091.png) (image/png)
                              

                                                        ![](images/icons/bullet_blue.gif)
                            [1.PNG](attachments/10782089/10782093.png) (image/png)
                              

                                                        ![](images/icons/bullet_blue.gif)
                            [2.PNG](attachments/10782089/10782094.png) (image/png)
                              

                                                        ![](images/icons/bullet_blue.gif)
                            [4.PNG](attachments/10782089/10782105.png) (image/png)
                              

                                                        ![](images/icons/bullet_blue.gif)
                            [5.PNG](attachments/10782089/10782096.png) (image/png)
                              

                                                        ![](images/icons/bullet_blue.gif)
                            [3.PNG](attachments/10782089/10782102.png) (image/png)
                              

                                                        ![](images/icons/bullet_blue.gif)
                            [4.PNG](attachments/10782089/10782095.png) (image/png)
                              

                                                </div>
                </div>
                
             
            </div>             </div> 
        <div id="footer" role="contentinfo">
            <section class="footer-body">
                Document generated by Confluence on Nov 03, 2023 14:28
                <div id="footer-logo">[Atlassian](https://www.atlassian.com/)</div>
            </section>
        </div>
    </div>