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 to buy “External API” Feature category's package or feature for 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 new External Application (if not exist),  for that following steps need to follow

Image showing the External Application list.

Figure 1.1

Image showing the display list of the External Application master.

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.

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

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

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:

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

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 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

Image showing the API Event Selection for External Login.

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

8.2 Getting external token for login

8.2.1 Get external token request

JSON:

Image showing Get external token request in JSON.

XML:

Image showing Get external token request in XML.

Currently required fields for external log-in are as follows.

8.2.2 Get external token response

JSON:

 

Image showing Get external token response in XML.

 

Image showing Get external token response in XML.

 8.3 Validating external token

8.3.1 Validate external token request

JSON:

Image showing external token request validation in JSON.

XML:

Image showing external token request validation in