Obtaining Authority to call an API
Remote applications need specific privileges to call the PersonHub RESTful APIs, as will campus departments such as the Registrar’s office. Follow the steps listed in the Quick Start Guide on the data management site, to register your client application.
Before access permission will be granted, Information Systems must obtain a complete list of APIs which will be used. Typically, access will be granted for a specific series of APIs. Relatively few developer units will be granted access to all available APIs.
Information Required for Application Registration
|Peoplesoft department ID||Peoplesoft department IDs are commonly used to control access to a variety of resources. Every department on campus has a unique, assigned ID. Unit administrators are familiar with this terminology and may be able to identify the appropriate value if needed. As an example, “HC290100” represents “Dean’s Office, College of Medicine”.|
|Unit Name||The organization’s descriptive name. Examples include “Dean’s Office, College of Dentistry” and “Department of Pediatrics, College of Medicine”.|
|Language of the calling application||Knowing something about the nature of your application, will be helpful if troubleshooting assistance is ever required. Common examples of responses to this data item include: COBOL, CICS, SAS, MS Access, Java, etc.|
|RACF ID (Test Region) & RACF ID (Production Region)||RACF Group IDs are used to control access to a variety of resources. Different RACF Groups are associated with test and production regions. Both IDs are required before applications will be allowed to access APIs. An individual’s RACF ID can then be associated with these Group IDs.|
|Calling UFID||The UFID of the individual or organization responsible for initiating API calls will be logged as a component of UF Directory management. Departmental UFID’s are initially being set to equal the full eight character Authority Code value (e.g., College of Medicine Dean’s Office UFID is HC290100). This value is commonly used by, and can be obtained from, each unit’s administrative staff. Upon implementation of the UFID and UF Directory on January 21, 2003, Departmental UFIDs will be randomly assigned values consisting of both alphabetic and numeric characters. UFIDs assigned to people will be restricted to numeric characters (i.e., zero through nine).|
|Specific APIs to be called||At least one valid API (e.g., BAUDD050) must be specified. Some applications will typically need to access several APIs.As an example, if you or your unit isn’t authorized to execute an all encompassing lock down of an individual’s record, a request to access BAUDD061 (Emergency Secure Person) will not be granted.|
APIs are being assigned one of three levels of security which correspond to Self-service, Intermediate and Administrative.
- Self-service: access for all information pertaining to a particular individual is permitted.
- Intermediate: access for all information pertaining to many individuals is permitted with the explicit exclusion of data deemed to be sensitive. At this time, SSN is the only data field so categorized.
- Administrative: access for all information pertaining to many individuals is permitted including sensitive data.
There are a few important concepts to keep in mind when developing client programs.
- SQL operations of a stored procedure are executed within the client’s unit of work. The client application has explicit control over the scope of the unit of work and is responsible for commit or rollback processing.
- Names of the stored procedure and parameters, should be passed through host variables. Input-Only parameters can be passed as constants so long as the value is compatible with the data type of the corresponding stored procedure parameter.
- Host variables must have data types compatible with parameters expected by the stored procedure.
- Host variables in the call are mapped to the parameters in the stored procedure as defined in the SYSROUTINES and SYSPARMS rows.
- Host variables being used as parameters cannot be passed in structures or arrays.
- To reduce network I/O – set the Output Only indicator for all host variables which are not being passed as input to the stored procedure and are only used to receive values returned by the call.