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

1. User must buy “External API” Feature category's package/feature to use external API.

1. User's Associated role is associated with following GyrusFunctions for use API functionality
   

1.       Manage External Application Master

Now you need to create a new External Application (if not existing already),  for that follow these steps:

Image showing how to navigate to External Application settings.

Figure 1.1

Image showing the display list of the External Application master.

Figure 1.2

As per figure 1.2,  this is the display list of External Application page. This list displays all types of External Application, like General, Etc. The Admin can Create, Update and Delete External application from this page.

Create:- For creating a new External application, click on the Add (Plus) button. Then redirect to new creation of External Application page.

Update:- For updating an external application's record, hover over the Action Button ('...') next to the name of external application name and click "Edit" to edit external application page.

Delete:- To delete a record, select any record using the check box and click on Delete (Trash) button.

Image showing the API configuration under Configuration/Advanced

Figure 1.3

Image showing API Event Selection

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:

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.api.gyrusaim.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

                        2.1.2 JSON request structure

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 applied on most of the list method (Please check with documentation first before applying filter to any method)

The above 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 the below success response from the API.

Json:

Image showing a success response in JSON.

 Xml:

Image showing a success response in XML.

2.4 Error response structure

In case of any error occurred during process of request you will get error response from the API. Refer to section 5.0 for HTTP status code with GyrusAim status codes. Here is an example.

Json:

Image showing JSON error response structure.

Xml:

Image showing XML error response structure.

3.0 Authentication Process in API

When a user makes a request to the GyruaAim API, it will first validate the token information (Client key and Client Secret). If the 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.

6.0 Employee

6.1 Employee Request Data Structure

Json:

6.2 Employee response fields list

6.3 Employee response example

JSON:

­7.0 Employee Insert

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

7.3 Employee update request data structure

The request data structure for update as follows.

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 the flag or set it 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 the flag or set it 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 the flag or set it 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 the flag or set it to false, then it adds new organizations within existing organizations.

Also, if we do not pass the above flag parameters, then they are considered to be set to false.

<?xml version="1.0" encoding="utf-8"?>

<Root>

      <startDate>mm/dd/yyyy</startDate>

      <endDate>mm/dd/yyyy</endDate>

      <Token>

            <ClientKey>Your-ClientKey</ClientKey>

            <ClientSecret>Your-ClientSecret</ClientSecret>

      </Token>

      <Paging>

            <PageIndex>0</PageIndex>

            <PageSize>10</PageSize>

      </Paging>

</Root>

{

      "assessments" : [

            {

                  "employeeNumber":"A001",

                  "assessmentName":"MyAssessment",

                  "dateCompleted":"mm/dd/yyyy",

                  "isPassed":"true",

                  "score":"70",

                  "notes":"My Notes"

            }

      ]

}

<Assessments>

      <Assessment>

            <EmployeeNumber>A001</EmployeeNumber>

            <AssessmentName>MyAssessment</AssessmentName>

            <DateCompleted>mm/dd/yyyy</DateCompleted>

            <IsPassed>True</IsPassed>

            <Score>70</Score>

            <Notes>My Notes</Notes>

      </Assessment>

</Assessments>

9.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).

9.1 Enable External log-in

Image showing the API Event Selection for External Login.

     

 

Image showing where to enable/disable the "Is CORS Enable" setting.

9.2 Getting external token for login

9.2.1 Get external token request

JSON:

Image showing Get external token request in JSON.

XML:

Image showing Get external token request in XML.

9.2.2 Get external token response

 

Image showing Get external token response in XML.

 

Image showing Get external token response in XML.

 9.3 Validating external token

9.3.1 Validate external token request

JSON:

Image showing external token request validation in JSON.

XML:

Image showing external token request validation in

10.0 Employee Delete 

10.1 Employee Delete Request Data Structure

Image showing how to enable the Delete Employee Permission.

              With one delete request, a maximum 10 Employee records are allowed to be deleted.

Json:

10.2 Employee delete response fields list

10.3 Employee Delete response example

End of the document