IT Provisioning - Web Service API Security/Access Listing
1.
<span>[Knowledge Base](index.html)</span>
</div>
# <span id="title-text"> Knowledge Base : IT Provisioning - Web Service API Security/Access Listing </span>
</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:**
Background
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.
Accessing the Web Service
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]
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
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 .
<div class="greybox" align="left">

[worddav68ae31fd646ea2c673f0f78beca2b03a.png](attachments/10782089/10782088.png) (image/png)

[worddav938233ce15774b2beb0592c7484d2d0b.png](attachments/10782089/10782090.png) (image/png)

[worddavdd409ac64cac8872b5b08011a9cd6082.png](attachments/10782089/10782091.png) (image/png)

[1.PNG](attachments/10782089/10782093.png) (image/png)

[2.PNG](attachments/10782089/10782094.png) (image/png)

[4.PNG](attachments/10782089/10782105.png) (image/png)

[5.PNG](attachments/10782089/10782096.png) (image/png)

[3.PNG](attachments/10782089/10782102.png) (image/png)

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


