Before you Begin
Besides the basic information of district name, vendor name, following information is required.
- GURU > System > Vendors - Name, Client ID, and Secret - also make a note of Application Type - Is this a service account or web application?
- If user is related to it (Application Type = Service Account), user name and the role (from GURU > Security > Roles) that this user belongs to.
- If a problem is based on a certain resource, obtain which resource is returning an error or having a problem, error code if displayed, whole schema if needed.
Tips
Try all or some combination of troubleshooting below. If you are unsuccessful with these methods, report what was tried in a support ticket to narrow down the cause.
GURU Vendor Account 101
-
Web Application - Accessed by web browsers over a network.
This means, it allows vendor's application to call the eSD GURU API on behalf of an individual end user. This scenario is also known as "three-legged OAuth".
Only requires Client ID and Client Secret to log onto GURU API site (front-end) -
Service Account - Calls eSD GURU API on behalf of the vendor's application instead of an end-user.
This means, you need server-to-server interactions such as those between a web application and an eSchoolData service. A service account, which belongs to vendor's application instead of to an individual end user, allowing to call the eSD GURU API on behalf of the service account or an individual end user. Typically, an application uses a service account when it needs to access all data.
Requires Client ID, Client Secret, Username, and Password to log onto GURU API site (front-end).
Difference between URI and URL
-
URI - Uniform Resource Identifier
URI identifies. It's like your name. It does not tell you where you live or any other information. URIs are a standard for identifying documents using a short string of numbers, letters, and symbols.
Ref: https://tools.ietf.org/html/rfc3986 -
URL - Uniform Resource Locator
URL locates. It's like your physical address. It tells you where you can be found. Contains information about how to fetch a resource from its location. URL is a part of URI, and always starts with http or https.
Model and Model Schema (found under each resource)
- Model: Model displays how each resource is structured. It'll display what each line means and what type of value is expected (such as integer/string) with each. Some fields are optional.
- Model Schema: Model Schema displays how each resource may look like in real life.
HTTP Status Code Matrix for GURU API
HTTP Status Code can differ from one resource to another. API Explorer (front-end) describes the reason for each of the status code under Response Messages section in each resource. Refer to Response Messages section for a resource in question to see what it means. Below is the general status code and what it might mean.
| HTTP Status Code | Reason | What it means |
|---|---|---|
| 200 (OK) | The request has succeeded. | The request you sent has been received and process is continuing. |
| 400 | Bad Request | Your request could not be understood by our server due to malformed syntax. Or your request simply cannot be found. |
| 401 | You're not authorized to view addresses. | You don't have permission to view the page. Usually requires username/password |
| 403 | Insufficient resource permissions | You have an access to the page/resource. The server understood your request but is refusing to fulfill the request because you do not have appropriate API resource permissions. |
| 404 | Cannot be found | The server has not found anything matching your request. It can be a page or resource. It may be available in the future. Common code, it's usually very vague. |
| 500 | An error has occurred on the server | Internal Server Error. The server encountered an unexpected condition which prevented it from fulfilling your request. |
| 503 | The server is temporarily unavailable | The server is currently unable to handle your request due to a temporary overloading or maintenance of the server. |
Troubleshooting Matrix
| Symptom | What it means | Why it happens | How to troubleshoot | Remedies |
|---|---|---|---|---|
| Invalid Client ID or secret | Vendor is unable to log on using provided Client ID and Secret. |
This may happen due to the following: Cut and pasted Client ID and Secret causing missing characters or including extra space New Client Secret generated is not saved. |
Have a vendor send Client ID and Secret they're using. Go to GURU API website to confirm the error still exits. Compare above info with what's in GURU under GURU > System > Configuration > Vendors > Action button for the vendor > Edit (Secret will not be displayed) Confirm that all characters of Client ID and Secret are copied properly. |
Reset Client Secret by clicking on Reset Secret button available from GURU > System > Configuration > Vendors > Action button for the vendor > Edit. Once generated, click NEXT button at the bottom of screen until SAVED. Unless newly generated secret is saved, the system will keep returning error. Re-try login with existing Client ID and newly generated Secret. Recreate Vendor altogether, make note of Client ID and Secret generated. Try logging onto API website to confirm the account is active. |
| Invalid username and password (Service Account) | Username and/or password is/are incorrect. | Typically, this happens when a user does not have an access to API or does not exist at all. |
Try logging on to API site using ONLY ClientID and Secret. (this will determine if the problem resides in Vendor setup or the user) GURU > Security > Users - confirm the account exist with the same username used during initial login. GURU > Security > Roles - confirm a user belongs to a role. GURU > Security > Roles > Action button > API Permissions - confirm the Role the user belongs to have permissions to API resources. |
If no account exists, create a user in Main App. Then log on to GURU as an admin to assign a role, then confirm that the role has permissions needed for API. Go to API site and log on to confirm, with Client ID and Secret. If error returns, try resetting Client Secret from above section - Invalid client ID or secret and see what happens. Contact Support if it is not successful. |
| Resource I'd like to use is not listed/cannot be accessed. | API Resource(s) in question cannot be called and/or is not listed when loggoing onto API site. | This happens when you don't have the permission to access the resouce(s). |
Web Application Account GURU > System > Configuration > Vendors > Action button > Edit. 2nd tab lists all available API Resources. Find the resource in question to make sure there is a green checkmark next to it. Service Account - will need to do both below for troubleshooting. GURU > System > Configuration > Vendors > Action button > Edit. 2nd tab lists all available API Resources. Find the resource in question to make sure there is a green checkmark next to it. GURU > Security > Roles > Action button > API Permissions. Find the Resources in question and make sure there is a green checkmark next to it. |
GURU > System > Configuration > Vendors > Action button > Edit. 2nd tab lists all available API Resources. Find the resource in question, click on the red X to make it a green checkmark. Repeat for all resources requested. Click OK to save. Log onto GURU API site > API Explorer to find the resouce(s) you just activated. For Service account, additional step below is necessary. |
| Vendor logo does not display when adding a Vendor Link to Link widget in GURU | The vendor's logo displays empty or broken when a link is added to GURU > Link Widget. |
3 possible reasons: URI to the logo is incorrect Logo is moved from URI entered in the API account. Programmatic error. |
From a vendor, obtain where the vendor logo is located Open new browser, paste the URL obtained from vendor to see if the logo comes up. Log onto API site using vendor credentials. Click on the Vendor Account name at the upper right corner of API site > My Account. Under Logo URI, confirm the URI is the same as the one you obtained. |
If a vendor-provided URL does not return their logo in the browser, contact a vendor and see if it can be fixed. Log onto API site using vendor credentials. Click on the Vendor Account name at the upper right corner of API site > My Account. Under Logo URI, paste the URL. Click Save Changes. Log onto GURU and see the logo displays under Link widget. If still broken/no logo, open a new ticket. For more info on URI/URL, see above section on Difference between URI and URL |
| Receiving 401 code (through API or API Explorer in front-end) | You're not authorized to view addresses. | This happens when the credential used do not have enough permission to access the page. |
GURU > Security > Users - username exists. GURU > System > Configuration > Vendors - vendor exists. GURU > Security > Roles - confirm that a user in question belongs to the Role that has an access to API site/page/resource. |
If a user does not exits, create a user in Main App. If a vendor does not exists, create a new vendor from GURU > System > Configuration > Vendors - make note of ClientID and Secret to try logging in upon completion. If Service Account, confirm user and vendor exist, and try logging in. |
| Receiving 403 code (through API or API Explorer in front-end) | Insufficient resource permissions | You don't have enough API resource permissions to use a resource in question. |
Web Application Account GURU > System > Configuration > Vendors > Action button > Edit. 2nd tab lists all available API Resources. Find the resource in question to make sure there is a green checkmark next to it. Service Account - will need to do both below for troubleshooting. GURU > System > Configuration > Vendors > Action button > Edit. 2nd tab lists all available API Resources. Find the resource in question to make sure there is a green checkmark next to it. GURU > Security > Roles > Action button > API Permissions. Find the Resources in question and make sure there is a green checkmark next to it. GURU > Security > Users - confirm that a user in question is in fact included in the role. |
GURU > System > Configuration > Vendors > Action button > Edit. 2nd tab lists all available API Resources. Find the resource in question, click on the red X to make it a green checkmark. Repeat for all resources requested. Click OK to save. Log onto GURU API site > API Explorer to find the resouce(s) you just activated. For Service account, additional step below is necessary. |
| Receiving 500 code (through API or API Explorer in front-end) | An error has occurred on the server. | Internal Server Error. The server encountered an unexpected condition which prevented it from fulfilling your request. |
Make a note of resource in question. Take screenshot. Confirm if the same thing is happening elsewhere. Contact IT team to make sure the server is up and running. Confirm there is no job/script/build happening at the same time to cause this problem. |
|
| Receiving 503 code (through API or API Explorer in front-end) | The server is temporarily unavailable | The server is currently unable to handle your request due to a temporary overloading or maintenance of the server. | Contact support | |
| Unable to find ___id number in Main App | ID number used in API resources does not match with what's found in Main App | "ID" used in API resource is NOT an ID number in Main App. | Contact support | |
| Try It Out: Returns error when parameter is used. |
Generally, returning error due to the following: Entered integer in string field. Entered string in integer field. Did not follow the format specified. Or you didn't enter any value where it says "(required)" |
Take a look at Parameters section and read description, parameter type and data type. Does your entry match with what is requested? |
Retry again after all information is confirmed and your entry is correct. Contact support if it is not successful. |