What we’ll cover:
Applicable Roles:
- HR Connect Administrator
Overview
The FAQs addressed below will be updated as needed. This article was updated last on October 17, 2022.
FAQs
1. Does the HR Connect API run on the Cayuse server or a customer server?
The API runs on the Cayuse server. There is no need for you to build a server to support HR Connect.
2. How is the API configured with connection information (such as database name, username, password, etc)?
Cayuse provides API documentation via our Help Center on how to make the API calls and authenticate a username/password. Your Cayuse project team will provide information on Tenant ID and also create account credentials for your HR Connect use.
3. What triggers the API?
As the customer, you will trigger the API by writing and call the API via middleware (if it exists), basic scripts, or Postman.
4. Where does the .csv extract code need to live in order for the API to have access to trigger it and get the desired data?
The .csv file will live locally on your network (for example, on someone's desktop). You will make a call to the Cayuse API, and that call will include uploading the file to the API. You can think of it as an advanced type of email attachment, using HTTPS instead of actual email.
5. What do we need to prep and/or complete prior to sending a file via HR Connect?
- Confirm you are using the latest version of the Admin Bulk Load Data template (.csv file).
- Review the Data Dictionary tab on the Admin Bulk Load Data template for information on:
- Tab specific data types/data values
- Tab specific required field(s) .csv file.
- Required unique data fields
- Review the RawDataValues tab on the Admin Bulk Load Data template for information on tab/column specific data value options.
- Confirm that all column headings match the latest version of the Admin Bulk Load Data template.
- Confirm there are no leading spaces in the column headings.
Please note: For People and Units only, if data was previously passed to a data element and in a subsequent data file, the field will be blank and the data will be deleted. To retain the existing data you must remove the column from the .csv file prior to processing.
6. What is the maximum file size for an HR Connect API request?
HR Connect files are limited to 10 MB. The limit is unlikely to be reached since .csv files are so small.
7. Are URL paths case-sensitive?
Yes. Per the documentation, the API will return a 4xx client error for a URL with an invalid case.
8. What file delimiter should be used and does HR Connect support data with commas?
HR Connect supports .csv files. Commas are allowed if the fields in your .csv file are surrounded by double-quotes.
9. What standard errors could the API encounter?
- 500 error: This is a generic error response, typically meaning the server encountered an unexpected condition preventing it from fulfilling the request. If you receive this error, verify the following:
- You are using a .csv file type and not .txt
- Headings in the .csv file exactly match those in the template.
- You are using the -F syntax (not data-binary) when specifying the path of the .csv file for Peopleand Units.
- 401 Authorization Error: The 401 (Unauthorized) status code indicates that the request has not been applied because it lacks valid authentication credentials from the target resource. If you receive this error, verify the following:
- Are you using the correct Tenant ID and credentials for that tenant? If you are unsure, please confirm with your Cayuse Integration Consultant or Cayuse Project Manager.
- 403 Forbidden Error: The 403 error happens when you do not have permission to access a specific resource, typically a result of not having a valid token to support your HR Connect request. If you receive this error, verify the following:
- Are you using the correct Tenant ID and credentials to that tenant, if you are unsure please confirm with your Cayuse Integration Consultant or Cayuse Project Manager.
- That token has not expired (typically the token is valid for a specific number of hours).
10. How can I avoid the most common errors that people make when using Cayuse HR Connect?
- When making the call to get a bearer token, do not include your environment name in the URL. Everyone must make the call to signin.uat.cayuse.com or signin.app.cayuse.com. The only variables will be the Tenant ID and your username/password.
- When you have received your bearer token, the remaining calls require your environment name in the URL (for example college123.uat.cayuse.com or college123.app.cayuse.com).
- Be sure that the headings in your .csv file are an exact match to template headings. You may use any filename for the .csv.
- Always wait for your current job to finish (completed: true in the Status endpoint) before starting your next upload.
11. Is the Tenant ID the same between the UAT/Training environment and Production?
No, each tenant has a unique Tenant ID and user credentials are unique to the tenant.
12. Can I do initial testing using a Header-only file?
No, you cannot test using header-only files.
13. Can I use international characters and names in the .csv file import?
Yes. International characters and names will import correctly.
14. What does the HR Connect message Job ID time to live = 30 days mean?
You can get the status and get the report for an HR Connect job for up to 30 days after generating it.
15. How does HR Connect work if my institution uses SSO?
Once your tenant is set to use SSO, when you create a new user either through the user interface or through HR Connect, the user does not need to complete account setup. They will not receive an email to set up a password, as their password is managed by your institution's identity provider.
Even though emails won't get sent out for users, we still recommend that you set send_account_activation_emails = false in your HR Connect Person.csv file for your records.
16. What other general information do I need to know about how and where the API runs?
The API is really just a gatekeeper sitting on top of the Cayuse product database. As the customer, you make specific calls to that API (send a .csv, get a report, get a token, etc), and the API responds accordingly.