| AI Robot API | |||
| Project Developer | Keith Stewart | ||
| Project Owner | GraphCube | ||
| Customer | Multiple Public Organizations | ||
| Technical Writer | Keith Stewart |  |
|
| Versioning | V1.0 JUN 2019, V2.1 FEB 2020 | ||
| Document Name | AIRobotAPI.V.2.1.docx | ||
This document is designed for the following purposes:
- Provide a general overview of the AI Robot API functionality.
- Explain the process for creating and setting up an API account.
- Serve as a technical guide for API use.
- List resources for available help and API technical contacts.
Completion of each task included in the following 5 prerequisites is mandatory for access to the API. Instructions for completing each task are listed in the prerequisites below. Figure #2 provides a overview map of the steps covered in this document.
- EULA Acceptance: All API users are required to read and accept the standard End User License Agreement (EULA). The EULA specifies in detail the rights and restrictions which apply to the use of the software as well as software reverse engineering restrictions and software use liability exemptions. The EULA is in digital form and must be accepted at the time of account setup.
• Task: click the EULA acceptance button when prompted. - Account Credentials: As part of the account registration, you must select a username and create a password (your account credentials) for your account login. You will use your account credentials to access the API dashboard to configure your data management transactions. Data management transactions (retrieving and publishing data) are referred to, in the API, as Data Packages. Your API dashboard is described in the API Access & Use Instructions section following. Username and password complexity requirements are displayed during your account setup.
• Task: follow the onscreen instructions and complete your account setup. - Get API Key: Each registered and approved user will be provided a unique API Key. This key is assigned to your organization and can be used by any registered users within your organization. The purpose of the API key is to identify your organization and to remember your API configuration settings.
• Task: make sure to enter your API key only when prompted by this API; do not share your API key with anyone outside your organization. Your API key is available in your API dashboard. - Encryption Method: This API primary method operates by creating a data package entity which is the collection of all the configuration parameters for a given data management transaction together with your API key and other internal controls. The created data package is then encrypted. This method provides increased security by ensuring that your data package, regardless of your request method(1) , is encrypted and undecipherable to any potential threat vectors. Encryption is provided by the API app automatically.
• Task: acknowledge your acceptance of the encryption standards during the setup prompt. - Rules: This API includes two categories of rules: Category 1 rules include your access to this API, your organization’s access to the API, use of the API dashboard, use of the AI robot, and protection of your username and password. Category 2 rules include performance metrics you are encouraged to adopt with your API in order to minimize the impact on the API network bandwidth.
• Task: acknowledge your acceptance of the access rules and the performance rules during the setup prompt.
(1) API request methods currently include URL requests, get/post requests, and http header requests.
Logging In
The first step in using the API is to login and be authenticated by the API. To login, navigate to the login URL link below and enter your username and password. You may use any device (Desktop, Tablet, Phone) to access your login page.
API Login Link:
https://<api_server_domain>/API/
Login Notes:
- You must always ensure you are using a secure connection (https).
- Your password is case-sensitive, your username is not.
- The <api_server_domain> is merely a place-holder, it will be replaced with the actual link during your account setup process.
- After three unsuccessful login attempts, your account will be temporarily frozen and you will be unable to login. To resolve this account freeze situation, see the Get Help section at the end of this document.
Your API is configured to your specifics using a collection of simple online tools. These tools provide you with the following views and functions:
- Overview of all your API settings and data packages in a convenient dashboard layout.
- View and manage (edit, delete, and create) your account information (contact details, password reset, API key, etc.).
- Drill down view of each of your API packages including run times, schedules, parameters, status messages, and overall metrics. From this detailed view, you can manage the configuration of the API parameters.
- View and manage your package publishing detail; for example, you can add and remove recipients of your package.
Creating your first API Data Package
To create your first API data package, from your Dashboard, click on the Create New Package link and follow the online prompts for creating your package. A sample of key API configuration data elements is displayed in Figure #4.
Each element includes a context-sensitive information icon that explains the item in detail and specifies whether the item is required or optional. For example, the API Robot select list allows you to choose from a list of curated AI dynamics, or you can also create your own AI dynamics and apply those as a custom AI Robot.
Additionally, the Data Source, Parameters, and Publish data elements are links to JSON files that contain the logic for the data element. For example, the Data Source File can link to a JSON parameters file which specifies a complex query condition or stored procedure for multiple tables within a database or across multiple databases. Configuring API parameters and creating custom AI robots are covered in the following sections.
When you have finished creating your API, Click the Blue Save Task button; the app will determine if all your required data elements have been completed and notify you if there are any data elements you need to review. Once the app validates your data, your new API is saved and will run according to your schedule.
API parameters are the essential components in creating an effective data package. Specifically, the parameters you configure will be the primary controlling factors generating and filtering data included in your APO package. At the most rudimentary level, there are a series of required parameters that are consistent across most APIs; these include basic data entities such as your API key, scheduling dates, publishing dynamics, API name, API ownership, API permissions, etc. When you create a new API (See the previous section) and/or modify an existing API, the basic required parameters are specified and are pre-populated for you in the API creation data fields and select lists.
The efficiency and effectiveness of an API data package rely on the initial setup of your key parameters of interest. Setup of these parameters is segregated into three logical areas as follows:
- Data Sources: these include databases, spreadsheets, CSV files, XML files, etc. where information resides that can be included within your data package. When you create an API, generally you will select data elements from these sources which you want to include in your package. When you have completed your selections, your selected data elements are seamlessly written to a JSON file which you will name and then which you can link to your API (Note: this is the data source file in the Creating your First API section above). This process allows you virtually unlimited flexibility in configuring the data and data relationships you want to include in your API and allows you to fine-tune your data sources at any time.
- Parameters: aside from your data sources (which are also types of parameters), there are many configurable API parameters available for you to filter your data package. A real-world example is as follows:
- You have selected in your data sources to include total staff hours worked for a given work task (Example work task: ranger patrol) across all your work units (locations) and including all work sub-tasks.
- You now set the following parameters which will filter your data sources file:
- You set the work parameter to filter and include only sub-tasks for law enforcement interception activities, law enforcement in-court/judicial proceedings, and law enforcement evidence-gathering activities.
- You set your geographic work location filters to sort your data by your predefined regions (Northeast, Mid-Atlantic, Southeast, Mid-West, Mountain, etc.).
- You set your data package to execute every day and record the day and date for each data entity.
- Once you have completed these parameters, save your parameters, and name your saved file. Your saved file is then written to a JSON file available in your API dashboard. You can edit and fine-tune these parameters within your file at any time.
{"workTask": "Ranger Patrol", "workUnit":{"hours" : 1}, "workSubTask": [{"LEinterception": 1,"LEcourtJudicial": 1, "LEevidenceGather": 1}], "workRegion": "northEast"}
- Publish: once you have set your data sources and your parameters, your remaining task is to set up the following retrieval specifics for your data package:
- Set your data package publishing (push) frequency (this is how often you will receive your data, not how often the data is generated; Example: you may generate the data daily, as above, but retrieve the data weekly).
- Specify the day of the week and the hour you wish to receive the data package.
- Specify any additional email addresses you wish to be notified of your data package publish, noting that each email will be provided with a link to retrieve the data package.
Saving your API data package
Once you have completed configuring your API data package using your API dashboard, you should also have saved all three of your core API entities: your Data Sources, your Parameters, and your Publish specifics. Although you can save an API data package without specifying the above three entities, your package is incomplete and will not execute until all entities are completed.
With all the entities completed and your data package saved, your API is now ready to execute and run according to your package specifics. The final step for confirming your saved data package is to click the Test API Data Package link in your API dashboard. This will immediately execute your API and display your data on-screen for your confirmation. Once you have confirmed your data, your API data package is saved and ready to execute. NOTE: for large datasets, only a portion of your data will be presented on-screen; a link to your full data package is provided should you need to confirm all data.
Upon confirmation of your data package as specified above, the API link to your data package is displayed at the bottom of your API window. A sample API data package link looks like the following link:
https://www.graphcube.com/API/api.cfm?package=X3er23dh345hJy0dsd91D9f2asddf335k7
Next to the link, click the Send Link button and the API data package link will be sent to your account email address. NOTE: by default, once you confirm a data package as specified above, a standard email with the API data package link is automatically emailed to your API account email address for your records.
Running your API Package
Running your API data package is extremely simple: to run your API data package, select one of the following three methods:
API Run Method 1:
Click the API link provided in your email. Each time you create a new API data package, or modify your existing data package, you will receive a confirmation email with a link to your API data package.
API Run Method 2:
If you do not have access to your email with your API data package link, login to your API dashboard and click the API you want to run. Your API link is displayed in your dashboard for your selected API. You can either click the link, click the button “Email API Link to Me”, or copy and paste the link into your browser navigation bar to run your API.
API Run Method 3:
The third method for running your API is specifically designed for your development or IT teams. Although there are multiple ways to run the API, the general method includes invoking the API from one of your internal processes. Once you invoke the API, then your internal process can consume and handle the returned data according to your own defined processes. A real-world example (using sample names) follows:
- From your internal application, invoke the API data package URL using PHP through a CURL method. Alternatively. If you are using ColdFusion, invoke the API through a CFHTTP function or a CFHEADER function with API parameters included.
- When the API returns the data package contents in response to your API invocation, first initialize a return variable and then assign the returned data to your initialized variable (Array or structure).
- Determine the length of the variable array/structure and create a parsing condition (generally a loop) through the returned data for each record.
- Process your loop results into your own data source or whatever methods you have designed.
Existing AI Features
This API includes an existing programmed AI robot that automatically performs routine curated tasks assigned to the robot. For example, the robot autonomously gathers and emails task-specific work hours data to individual partner organizations while also filtering the data specifically for each partner.
Additionally, the robot includes autonomous learned intelligence —ALI(2) — to recognize data trends and to predict trends (relative to task-specific work hours and other items) based on work-site geographic data, workforce demographics, seasonal trends, overall socio-economic employment trends, and historical data. Based on user-configured notification frequency ranges, the AI robot notifies (email and/or text message, if configured) the API owner of significant trends.
Creating New AI Features
This API also includes the capability to configure the AI robot based on an expansive and growing set of parameters and conditions. Any existing AI features can be enhanced through parameter management and algorithm modification. Working with the API development and data management team, the robot can be programmed with detailed algorithms to achieve a data curation package that meets your requirements. To explore the possibilities and power of the AI robot, schedule a demonstration with your organization’s API representative.
(2) ALI—Autonomous Learned Intelligence is commonly referred to as Machine Learning; in the case of the AI robot, the learning algorithms are based on multiple factors other than user-input machine learning, therefore, the term ALI is more appropriate in this context as our robot learns from multiple non-machine-centric data pool sources.
Online Help
This API includes context-sensitive help (CSH) for each data element and setting in this system. Help about an item is immediately available by clicking the info icon next to the element and viewing the help bubble. See the example help bubble in figure #5 in this section. In addition, the API also includes comprehensive online help accessible by clicking on the Help Icon at the top of your API dashboard. You can also download and print a PDF version of the online Help file.
Call Center
For this API, GraphCube provides real-time online chat assistance with live tech support agents as well as a toll-free call center telephone number for live tech support voice assistance. Please refer to your API dashboard online Help screens and your SLA for contact numbers and hours of operation.
As part of the API quality control and enhanced ongoing security posture, API users can register to receive online notices for API software updates, software releases, and emergency notices. Registering for these notices is a software best practice for ensuring application integrity. To register, simply click the Notices button in the top menu of your API dashboard. At any time, you can opt-out of the notices by selecting the opt-out option in your API Dashboard notices area.
RELEASE SCHEDULE
JUNE 2019
Fixed bug in generated JSON where certain special characters were not being escaped in the saved data package. The error was limited to Native American tribal names with special characters only.
FEBRUARY 2020
Fixed bug in generated JSON where nested arrays (n+1) were improperly escaped when an array value included parentheses ().