KB693 | v16 | Version 16x API Documentation
Summary
1.0 Implementation summary for GyrusAim
GyrusAim provides a layer to customers which is responsible for interacting and dealing with incoming requests. Since HTTP is stateless, the GyrusAim API will verify and authenticate this request and respond back with the requested data if available. If the request is not verified or authenticated then the API will respond accordingly with a specific error code, message and description (troubleshooting description and not a stack trace). The error code is sent according to HTTP standards and/or it can be customized per GyrusAim's application standards.
GyrusAim verifies and authenticates the incoming request using an API key and secret (or token) combination. For example, if a company wants to create their own mobile application and wants to access their GyrusAim data, the GyrusAim user who has administrative rights will enable the API for the system, and create an encrypted API key and secret, or token, combination. The administrator will give this encrypted API key and secret (or token) combination to the related person/developer who will use this to access the data from the GyrusAim API. This API key combination must be kept secret to prevent unauthorized access. The API key combination must be included in HTTP(S) while making a request. The GyrusAim API will respond accordingly with the applicable data and status codes. Data can be JSON or XML depending upon the requested type.
Now time to used API
functionality, for that below some point need to cover
- User must to buy “External API” Feature category's package or feature for use external API.
- User's
Associated role is associated with following GyrusFunctions for use API
functionality
1. Manage External Application Master
Now you need to create new External Application (if not
exist), for that following steps need to
follow
Figure 1.1
Figure 1.2
As per figure 1.2 display list of External Application master. In this list display all types of External Application like General. GTIMS Etc.. User can Create, Update and delete External application from this page.
Create:- For create new External application, click on the Add button. Then redirect to new creation of External Application page.
Update:- For update external application record, click on the name of external application name then its redirect to edit external application page.
Delete:- For delete record, select any record and click on delete button.
Figure
1.3
Figure 1.4
Above figure 1.3 and 1.4 to Create or update page of External Application. Here you can add new application with accurate data like application name, domain name, application type and so on and save it. Below are the fields you need to enter as per your requirement:
|
Column Name |
Remark |
|
Name |
Unique Name of the application |
|
Domain Name |
Requests will be allowed from this given domain name. Otherwise request will be reject with 400 http status code. For example, gyrus.com, xyz.com etc... Note: domain name with sub domain name will be treated separated. E.g. abc.com and xy.abc.com will be treated as different. |
|
APP Type |
Application Type. · General (Default for API) · GTIMS (Customized) For example, General, GTIMS, LMS1, LMS2 etc... |
|
Max Allowed Requests Per Hour |
Maximum allowed request to GyrusAim API per hour. (-1 for unlimited) |
|
Push URL |
Push URL on which GyrusAim will push the data or status. (Optional) (Only POST request will be pushed. Your URL must be able to handle the posted data.) |
|
Is CORS enable |
To enable/disable CORS (Cross-Origin Resource Sharing) functionality. Refer section 10.0 . Click here for view more information regarding CORS. |
|
ParameterFieldKey1-6 |
Parameter key which needs to be push.(Optional) |
|
ParmeterFieldValue1-6 |
Parameter value which needs to be push.(Optional) |
|
Client Key |
Client key will be used as identity record. This will be generated after application in created. This is must required in every request made to GyrusAim API. (This should be kept secret) |
|
Client Secret |
Client Secret will act as token for above client key. This always need to be above mentioned client key. This will be generated after application in created. This is must required in every request made to GyrusAim API. This should be kept secret too) |
|
Token Valid From |
Generated token will be valid from. |
|
Token Valid UpTo |
Generated token will be valid upto. (Token will be expired after this date) |
Default value:-
· Valid From – Current Date
· valid up to – After 1 year from current date.
Now here you can see the API Event Selection, (See figure 1.4) which used for external application wise API events that decided by user and only such events are manage by particular external application. For example, if application associated with GET_EMPLOYEE, then GyrusAim provides employee detail when the request will be made to the GyrusAim API. Now after filling the required field values, click on save. After save, you can see that client key and client secret is generated. At this stage you are ready to make a call to the GyrusAim API.
2.0 Calling the API
GyrusAim will create a clean URL for making a request. The API link will be generic, such as www.<YourDomain>.com/api. Users can call the API with the request types GET, POST or DELETE.
2.1 Request structure
2.1.1 XML request structure
|
<?xml version="1.0" encoding="utf-8"?>
|
2.1.2 JSON request
structure
|
{ "token": { "clientkey": "D5756FE1C4E2", "clientsecret": "idES0ERwv73Q" } } |
2.2
Filter Structure
Filters are useful when you want to set criteria for data you are getting in
the response. This will help to get specific data you want. Filters can be
apply on most of the list method (Please check with documentation first
before applying filter to any method)
|
<?xml version="1.0" encoding="utf-8"?> |
|
{ "filters":{ "classCode":"class001" }, "token": { "clientkey": "D5756FE1C4E2", "clientsecret": "idES0ERwv73Q/P3xEeZKlY" } } |
Above mention filter structure is an example of class filter which is applied to /Class/List method. Here you can see that classCode filter is applied with value of “class001”. In the response you will get only a record which is having class code “class001”.
2.3 Success response structure
In case of insert/update/delete of entity through API, if record is inserted, updated or deleted successfully you will get below success response from API.
Json:
Xml:
2.4 Error response structure
In case of any error occurred during process of request you will get error response from API. Refer to section 5.0 for HTTP status code with GyrusAim status codes. Here is an example.
Json:
Xml:
3.0 Authentication Process in API
When user make request GyruaAim API, it will first validate the token information (Client key and Client Secret). If token is not verified then HTTP status code 400 will be received with other GyrusAim status information. (See upcoming section 5.0 for related HTTP status code as well as other GyrusAim status information and messages).
4.0 Authorization Process in API
After successful authentication, as mentioned above, in same request, the GyrusAim API checks for authorization. GyrusAim checks that give token is authorized for get/insert/update for specific entity or not based on configuration made during Application creation process. If it is not authorized then HTTP status code 403 will be received with other GyrusAim status information.
Note: Authentication process means to validate each request which is made to API. Do not mix it with oAuth process which is used in log-in process.
5.0 GyrusAim Api Status & Messages
The possible list of HTTP status codes and others GyrusAim status code that GyrusAPI return in response to request are as follows. GyrusAim status code helps you to figure out the possible solution in case of any error or requirement. You can use this code along with HTTP status code.
|
HTTP Status code |
GyrusAim Status code |
GyrusAim Status |
Message |
Description |
|
200 |
7000 |
ok |
success |
|
|
400 |
7001 |
failed |
failed |
|
|
401 |
7002 |
forbidden |
UnAuthorized |
Unauthorize request. Make sure your client key and client secret is valid |
|
401 |
7003 |
permissionDenied |
permissionDenied |
Permission denied. Make sure you have sufficient privileges |
|
400 |
7004 |
maxRequestLimitReached |
maxRequestLimitReached |
Max request limit is reached for this api. Try after sometime or contact your API administrator |
|
400 |
7005 |
apiExpired |
apiExpired |
API expired. Contact your API administrator |
|
400 |
7006 |
invalidDomainName |
invalidDomainName |
The domain from which you are trying to make request is not matched or invalid. Domain name should be same as configured in GyrusAim. |
|
400 |
7007 |
invalidToken |
invalidToken |
Token verification failed. Make sure you passed the correct client key and client secret |
|
500 |
7008 |
unHandledException |
unHandledException |
An unhandled exception is occurred. Please contact system administrator. |
|
400 |
7010 |
fieldRequired |
fieldRequired |
One or more fields are required. See errors for more details |
|
400 |
7011 |
missingApplicationConfiguration |
missingApplicationConfiguration |
Make sure your application is configured properly in GyrusAim |
|
400 |
7012 |
invalidRequestStructure |
invalidRequestStructure |
Check your posted xml or json request structure |
|
400 |
7013 |
businessLogicError |
businessLogicError |
Business logic error occurred. See error for more details |
6.0 Employee
|
Request Information |
|||||||||||||||||||||||||||||||||||||||||
|
URL |
|||||||||||||||||||||||||||||||||||||||||
|
Request Type |
POST |
||||||||||||||||||||||||||||||||||||||||
|
Content Type |
application/json or application/xml |
||||||||||||||||||||||||||||||||||||||||
|
Token Required |
Yes |
||||||||||||||||||||||||||||||||||||||||
|
Description |
To get list of employees |
||||||||||||||||||||||||||||||||||||||||
|
Filter |
Employee filters can be used |
||||||||||||||||||||||||||||||||||||||||
|
|
|
||||||||||||||||||||||||||||||||||||||||
6.1 Employee Request Data Structure
Json:
{
"filters": {
},
"paging": {
"pageIndex": 0,
"pageSize": 10
},
"token": {
"clientKey": "E258DFB34ED6",
"clientSecret":"A0qmts7UqWobsTUGOJUFbJAY94oB904agBNb6TNJLgWBIFDmLbkefydg0bIHnx3SeZwKHka5cm02U/Ee"
}
}
6.2 Employee response fields list
|
In JSON |
In XML |
Notes |
|
employeeNumber |
EmployeeNumber |
Required for insert/update |
|
firstName |
firstName |
Required for insert |
|
middleName |
MiddleName |
|
|
lastName |
LastName |
Required for insert |
|
|
|
Required for insert |
|
title |
Title |
|
|
address1 |
Address1 |
|
|
address2 |
Address2 |
|
|
city |
City |
|
|
state |
State |
|
|
postalCode |
PostalCode |
|
|
country |
Country |
|
|
notes |
Notes |
|
|
employeeStatus |
EmployeeStatus |
|
|
userName |
UserName |
|
|
supervisors |
Supervisors |
Array of supervisor codes |
|
organizationCode |
OrganizationCode |
|
|
hireDate |
HireDate |
|
|
expirationDate |
ExpirationDate |
|
|
prefix |
Prefix |
|
|
suffix |
Suffix |
|
|
nationalReference |
NationalReference |
|
|
termDate |
TermDate |
|
|
restartDate |
RestartDate |
|
6.3 Employee response example
JSON:
{
"employees": [
{
"employeeNumber": "sample string 1",
"firstName": "sample string 2",
"lastName": "sample string 3",
"hireDate": "sample string 4",
"expirationDate": "sample string 5",
"email": "sample string 6",
"prefix": "sample string 7",
"suffix": "sample string 8",
"title": "sample string 9",
"middleName": "sample string 10",
"nationalReference": "sample string 11",
"termDate": "sample string 12",
"restartDate": "sample string 13",
"address1": "sample string 14",
"address2": "sample string 15",
"city": "sample string 16",
"state": "sample string 17",
"postalCode": "sample string 18",
"country": "sample string 19",
"employeeStatus": "sample string 21",
"userName": "sample string 22",
"supervisors": {
"supervisor": [
{
"employeeNumber": "sample string 1"
},
{
"employeeNumber": "sample string 1"
}
]
},
"organizationCode": "sample string 23",
"password": "sample string 24",
"windowsUserName": "sample string 25",
"gyrusUserRoleAssociationList": [
{
"role_id": 1,
"userID": 2,
"role_name": "sample string 3"
},
{
"role_id": 1,
"userID": 2,
"role_name": "sample string 3"
}
],
"gyrusUserJobAssociationList": [
{
"IsPrimary": true,
"JobName": "sample string 2",
"JobCode": "sample string 3",
},
{
"IsPrimary": false,
"JobName": "sample string 2",
"JobCode": "sample string 3",
}
]
]
}
7.0 Employee Insert
|
Request Information |
|
|
URL |
|
|
Request Type |
POST |
|
Content Type |
application/json or application/xml |
|
Token Required |
Yes |
|
Description |
To insert employee |
|
Filter |
NA |
7.1 Employee insert request data structure
The request data structure for insert as follows:
JSON:
{ "employee": [ { "employeeNumber": "sample string 1", "firstName": "sample string 2", "lastName": "sample string 3", "hireDate": "sample string 4", "expirationDate": "sample string 5", "email": "sample string 6", "prefix": "sample string 7", "suffix": "sample string 8", "title": "sample string 9", "middleName": "sample string 10", "nationalReference": "sample string 11", "termDate": "sample string 12", "restartDate": "sample string 13", "address1": "sample string 14", "address2": "sample string 15", "city": "sample string 16", "state": "sample string 17", "postalCode": "sample string 18", "country": "sample string 19", "employeeStatus": "sample string 21", "userName": "sample string 22", "supervisors": { "supervisor": [ { "employeeNumber": "sample string 1" }, { "employeeNumber": "sample string 1" } ] }, "organizationCode": "sample string 23", "password": "sample string 24", "DeleteExistingRoles": true, "DeletedGyrusUserRoleId": "sample string 26" }, { "employeeNumber": "sample string 1", "firstName": "sample string 2", "lastName": "sample string 3", "hireDate": "sample string 4", "expirationDate": "sample string 5", "email": "sample string 6", "prefix": "sample string 7", "suffix": "sample string 8", "title": "sample string 9", "middleName": "sample string 10", "nationalReference": "sample string 11", "termDate": "sample string 12", "restartDate": "sample string 13", "address1": "sample string 14", "address2": "sample string 15", "city": "sample string 16", "state": "sample string 17", "postalCode": "sample string 18", "country": "sample string 19", "employeeStatus": "sample string 21", "userName": "sample string 22", "supervisors": { "supervisor": [ { "employeeNumber": "sample string 1" }, { "employeeNumber": "sample string 1" } ] }, "organizationCode": "sample string 23", "password": "sample string 24", "DeleteExistingRoles": true, "DeletedGyrusUserRoleId": "sample string 26" } ], "token": { "clientKey": "sample string 1", "clientSecret": "sample string 2" }}Response Information
7.2 Employee Update
|
Request Information |
|
|
URL |
|
|
Request Type |
POST |
|
Content Type |
application/json or application/xml |
|
Token Required |
Yes |
|
Description |
To update employee |
|
Filter |
NA |
7.3 Employee update request data structure
The request data structure for update as follow.
JSON:
{"employee" :{"employeeNumber" : "Emp0029","firstName" : "Emp0029","lastName": "0029","expirationDate":"12/31/9999 12:00:00 AM","hireDate": "1/10/2022 12:00:00 AM","email": "emp29@test.net","title": "SE29","middleName":"E","userName":"e0029","DeleteExistingRoles":true,"IsDeleteExistingJobs":true,"IsDeleteExistingSupervisors":true,"IsDeleteExistingOrganization":true,"supervisors" :{ "supervisor" : [ {"employeeNumber":"10001"} ]},"gyrusUserRoleAssociationList":[ { "role_name":"Student" }],"gyrusUserJobAssociationList":[ { "IsPrimary":false, "JobName":"AdminSK", "JobCode":"AdminSK" }],"organizationcode" : "CM ORG12"}, "token": { "clientKey": "sample string 1", "clientSecret": "sample string 2" } }
NOTE:
DeleteExistingRoles flag – If the user wants to replace roles, then we can set this flag to true, it removes existing roles and assigns new roles. Also, when we do not provide flags or flag set to false then it adds new roles with existing roles.
IsDeleteExistingJobs flag - If the user wants to replace jobs, then we can set this flag to true, it removes existing jobs and assigns new jobs. Also, when we do not provide flags or set flags to false, then it adds new jobs with existing jobs.
IsDeleteExistingSupervisors flag - If the user wants to replace supervisors, then we can set this flag to true, it removes existing supervisors and assigns new supervisors. Also, when we do not provide flags or set flags to false then it adds new supervisors with existing supervisors.
IsDeleteExistingOrganization flag - If the user wants to replace organizations, then we can set this flag to true, it removes the existing organization and assigns a new organization. Also, when we do not provide flags or set flags to false then it adds new organization with existing organization.
Also, if we do not pass the above flag parameters, then it considered as false.
8.0 External Log-in using API
GyrusAim API provides external log-in functionality which is useful while you want to log-in into the GyrusAim directly from any another website. To implement the external log-in functionality you must have prior knowledge of java script and Jquery. (Find the external log-in sample example with this document).
8.1 Enable External log-in
"http:// gyrus.com/auth/externallogin?externaltoken=<Your external token>".
8.2 Getting external token for login
|
Request Information |
|
|
URL |
|
|
Request Type |
POST |
|
Content Type |
application/json or application/xml |
|
Token Required |
Yes |
|
Description |
To get the token which used for external log-in. 24 hours validity |
|
Filter |
NA |
8.2.1 Get external token request
JSON:
XML:
Currently required fields for external log-in are as follows.
|
Must required fields |
Description |
|
EmployeeNumber |
Unique identification of employee |
|
FirstName |
First name of the employee |
|
LastName |
Last name of the employee |
|
Username |
User name of the employee |
|
|
Email address of the employee. (You should need to pass 'NA' in case of user dose not have email address values in GyrusAim.) |
8.2.2 Get external token response
JSON:
8.3 Validating
external token
|
Request Information |
|
|
URL |
|
|
Request Type |
POST |
|
Content Type |
application/json or application/xml |
|
Token Required |
Yes |
|
Description |
To validate external log-in token |
|
Filter |
NA |
8.3.1 Validate external token request
JSON:
XML:
Related Articles
KB694 | v17 | Version 17x API Documentation
Summary The purpose of this document is to give guidelines about the development of GyrusAim REST (Representational State Transfer) API. Please note that this is for advanced users with technical knowledge of REST APIs. Note: Exposed field(s) from ...KB503 | v16 | End-User Interface: Dashboard
Summary With version 16.5.0.8 you will experience the new layout of the Dashboard. The section below lists the learning features and serves as links to more detailed documentation for that given feature. We have also indicated its' new location in ...KB709 | v17 | Adding Assessments to Training
This article is for v17.x of the GyrusAim LMS application. Summary Assessments can be added to any type of training, or they can be freestanding. This KB details how to add an assessment to a training. Attaching an Assessment to a Training To add an ...KB676 | v16 | Annual License Unlock
Summary This KB details how to use the About Product page to get an Extend License code and upload the key file for your annual license unlock in GyrusAim version 16 for self-hosted customers. License Key/Code Note: Update License is a separate task ...KB678 | v17 | How to Archive Users
Summary This KB serves to inform users on how to archive an account. Archiving users is considered preferable to deleting them since it retains their history while still hiding them from sight for all other purposes. Users can be archived even when ...