The Web Service importation, as the Excel importation, is completely remote, and the administrators do not have to be granted access to the machine running the Gamification database. When doing a KPI integration via WebService you have a set of Data and Methods that are available for you to use in the KPI integration.
To complete the importation of KPIs through a web service you will need:
- Access via HTTPs
This web service coexists in the same machine as the application and is used to update the Gamification database, as the Excel file. This approach implies that the client uses a software to call the web service using the data structure described in the figure:
This article also provides a sample to help you with the subject, and the possible outcomes of such integration.
Note: This approach implies that the client needs a secondary application performing the Web Service calls to Gamification. The database and the application do not need to co exist in the same machine.
Data
The available data parameters that you can use, are:
| Name | Properties |
| GameExternalKpiImportRecord |
DateTime Date - record date. Sensible to the millisecond. Must be in UTC. string ExternalId - user Identification in business. int KpiId - Key Performance Indicator Id in Gamification. double Value - value associated with the Key Performance Indicator for the given date. int? NumberOfEvents - optional field used to perform weighted averages. |
| SendKpiRecordResult |
bool Success - true when importing was successful. false when importing was unsuccessful. string Notification - informative message about the importing process. |
| CheckKpiRecordResult |
bool Success - true when importing was successful. false when importing was unsuccessful. string Notification - informative message about the importing process. GameExternalKpiImportRecord[ ] Records - array of records with the result of the request. |
| Player |
string ExternalId - user Identification in business. |
| PlayerResult |
bool Success - true for successful requests. false for unsuccessful requests. string Notification - informative message about the request. Player[ ] Players - array of records with the result of the request. |
| PlayerMode (enum) | 1 All, 2 Active, 3 Inactive |
Methods
The available methods that you can use during KPI integration, are:
| SendKpiRecords | |
| Parameters | Returns |
|
SendKpiRecordResult |
| Description | |
|
SendKpiRecords imports parameters records, to the database specified in the web service web.config file. The importing is executed in transactions of x records where x is the variable recordspertransaction, also set in the web service web.config. |
|
| Possible Notifications | |
|
|
| CheckKpiRecordsByKpiId | |
| Parameters | Returns |
|
CheckKpiRecordResult |
| Description | |
|
CheckKpiRecordByKpiId returns a structure, CheckKpiRecordResult, containing a success flag, a notification and an array of GameExternalKpiImportRecord based on parameter kpiId. The array has a size configurable in web.config under the variable numberofkpisreturnedfromcheck. The other parameters, username and password are used to authenticate and authorize the service. Parameter tenantName, is required to access the correct database instance (for Gamification version 2.2 or higher). |
|
| Possible Notifications | |
|
|
| CheckKpiRecordsByExternalId | |
| Parameters | Returns |
|
CheckKpiRecordResult |
| Description | |
| CheckKpiRecordByKpiExternalId returns a structure, CheckKpiRecordResult, containing a success flag, a notification and an array of GameExternalKpiImportRecord based on parameter externalId. The array has a size configurable in web.config under the variable numberofkpisreturnedfromcheck. The other parameters, username and password are used to authenticate and authorize the service. Parameter tenantName, is required to access the correct database instance (for Gamification version 2.2 or higher). Only Gamification administrators can perform the request. |
|
| Possible Notifications | |
|
|
| CheckKpiRecordsByKPIIDAndExternalId | |
| Parameters | Returns |
|
CheckKpiRecordResult |
| Description | |
|
CheckKpiRecordsByKPIIdAndExternalId returns a structure, CheckKpiRecordResult, containing a success flag, a notification and an array of GameExternalKpiImportRecord based on the combination of parameter kpiId and parameter externalId. The array has a size configurable in web.config under the variable numberofkpisreturnedfromcheck. Parameters username and password, respectively are used to authenticate and authorize the service. |
|
| Possible Notifications | |
|
|
| CheckPlayers | |
| Parameters | Returns |
|
PlayerResult |
| Description | |
|
CheckPlayers returns a structure, PlayerResult, containing a success flag, a notification and an array of Player, filtered by mode, an enum of type PlayerMode, where All means all players, Active the active players and Inactive the inactive players, respectively. Parameters username and password, respectively are used to authenticate and authorize the service. |
|
| Possible Notifications | |
|
|
| CheckKpiRecordsByKpiIdAndDate | |
| Parameters | Returns |
|
CheckKpiRecordResult |
| Description | |
|
CheckKpiRecordsByKpiIdAndDate returns a structure, CheckKpiRecordResult, containing a success flag, a notification and an array of GameExternalKpiImportRecord based on parameter, kpiId. The array has a size configurable in web.config under the variable numberofkpisreturnedfromcheck. |
|
| Possible Notifications | |
|
|
| CheckKpiRecordsByExternalIdAndDate | |
| Parameters | Returns |
|
CheckKpiRecordResult |
| Description | |
|
CheckKpiRecordsByExternalIdAndDate returns a structure, CheckKpiRecordResult, containing a success flag, a notification and an array of GameExternalKpiImportRecord based on parameter, externalId. The array has a size configurable in web.config under the variable numberofkpisreturnedfromcheck. |
|
| Possible Notifications | |
|
|
| CheckKpiRecordsByKPIIdAndExternalIdAndDate | |
| Parameters | Returns |
|
CheckKpiRecordResult |
| Description | |
|
CheckKpiRecordsByKpiIdAndExternalIdAndDate returns a structure, CheckKpiRecordResult, containing a success flag, a notification and an array of GameExternalKpiImportRecord based on the combination of parameters, kpiId and externalId. The array has a size configurable in web.config under the variable numberofkpisreturnedfromcheck. |
|
| Possible Notifications | |
|
|
| DeleteKpiRecordsByKpiIdAndDate | |
| Parameters | Returns |
|
CheckKpiRecordResult |
| Description | |
|
DeleteKpiRecordsByKpiIdAndDate returns a structure, CheckKpiRecordResult, containing a success flag and a notification. |
|
| Possible Notifications | |
|
|
| DeleteKpiRecordsByExternalIdAndDate | |
| Parameters | Returns |
|
CheckKpiRecordResult |
| Description | |
|
DeleteKpiRecordsByExternalIdAndDate returns a structure, CheckKpiRecordResult, containing a success flag and a notification. |
|
| Possible Notifications | |
|
|
| DeleteKpiRecordsByKPIIdAndExternalIdAndDate | |
| Parameters | Returns |
|
CheckKpiRecordResult |
| Description | |
|
DeleteKpiRecordsByKpiIdAndExternalIdAndDate returns a structure, CheckKpiRecordResult, containing a success flag and a notification. |
|
| Possible Notifications | |
|
|
SOAP request Sample
Here, you have a sample on how to perform a SOAP request through the WebService:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/"
xmlns:gam="http://schemas.datacontract.org/2004/07/GamificationKPIImportationWebService">
<soapenv:Header/>
<soapenv:Body>
<tem:SendKpiRecords>
<tem:username>adminCollabUsername</tem:username>
<tem:password>adminCollabPassword</tem:password>
<tem:records>
<!--Zero or more repetitions:-->
<gam:GameExternalKPIImportRecord>
<gam:Date>2012-03-03T09:00:00</gam:Date>
<gam:ExternalId>1</gam:ExternalId>
<gam:KpiId>1</gam:KpiId>
<gam:Value>1</gam:Value>
<!--Optional:-->
<gam:NumberOfEvents>3</gam:NumberOfEvents>
</gam:GameExternalKPIImportRecord>
</tem:records>
</tem:SendKpiRecords>
</soapenv:Body>
</soapenv:Envelope>
Integration Sample
Here, you have a sample on how to do the KPI integration through WebService:
static void Main(string[] args)
{
try
{
Console.WriteLine("--------------Starting service--------------");
MyService.ImportServiceClient client = new MyService.ImportServiceClient();
List list = new List(); list.Add( new MyService.GameExternalKPIImportRecord { Date = DateTime.Now, ExternalId = 259, KpiId = 1, Value = 4, NumberOfEvents = null });
list.Add( new MyService.GameExternalKPIImportRecord { Date = DateTime.UtcNow, ExternalId = 5131, KpiId = 1, Value = 12, NumberOfEvents = null });
list.Add(new MyService.GameExternalKPIImportRecord { Date = DateTime.UtcNow, ExternalId = 259, KpiId = 2, Value = 3.4, NumberOfEvents = null });
list.Add(new MyService.GameExternalKPIImportRecord { Date = DateTime.UtcNow, ExternalId = 5131, KpiId = 2, Value = 5, NumberOfEvents = null });
list.Add(new MyService.GameExternalKPIImportRecord { Date = DateTime.UtcNow, ExternalId = 259, KpiId = 3, Value = 6.1, NumberOfEvents = 3 });
list.Add(new MyService.GameExternalKPIImportRecord { Date = DateTime.UtcNow, ExternalId = 5131, KpiId = 3, Value = 7, NumberOfEvents = 3 });
MyService.SendKpiRecordResult result = client.SendKpiRecords("admin", "qqqqq", list.ToArray());
Console.WriteLine("--------------Finshed service--------------");
Console.WriteLine(string.Format("Result: [{0}]. Notification: [{1}].", result.Success, result.Notification));
Console.WriteLine();
}
catch (Exception e)
{
Console.WriteLine("Something went wrong: " + e);
}
Console.Read();
}
Possible outcomes
When you import KPIs to Gamification through a WebService, you can have the following outcomes:
| Success | Notification message | Description |
| True |
"Import Service Notification: Importation succeeded. <<Nº of imported KPIs>> records imported. Last record imported [Date:<<Date of the last imported KPI>>|ExternalID:<<Agent External ID of the last imported KPI>>|KpiID:<<Type ID of the last imported KPI>>]" |
Indicates that the KPI importation was done successfully, showing the number and ID of the imported KPIs. |
| False | "Import Service Notification: User not authenticated. Username or password incorrect." | Indicates that the KPI integration failed due to invalid credentials. |
| False | "Import Service Notification: User not authorized. Only administrators can import Kpis." | Indicates that the KPI integration failed due to lack of permissions by the user. |
| False | "Import Service Notification: No records found in incoming message" | Indicates that there was not data to import. |
| False | "Import Service Notification: Found error in SendKpiRecords. [0] records imported Exception [<<Exception description>>]" | Indicates that the KPIs were not imported due to an error in the first KPI chunk. |
| False | "Import Service Notification: Found error in SendKpiRecords. [<<Nº of imported KPIs>>] records imported. Last record imported [Date:<<Date of the last imported KPI>>|ExternalID:<<Agent External ID of the last imported KPI>>|KpiID:<<Type ID of the last imported KPI>>]. Exception[<<Exception description>>]" |
Indicates that the KPI integration was partially successful. For example:
If the integration fails in the KPI ID 1300, you will receive this notification message, but since the integration is done by chunks the last imported KPI ID will be 1000 and not 1300. |
| False | "Import Service Notification: Found error in SendKpiRecords. Exception [<<Exception description>>]” | Indicates that the KPIs integration failed due to an error before the KPI chunks importation. |
Note: A KPI chunk is a conglomerate of KPIs and an entity in itself. If any issue happens in a KPI during the integration of a chunk, the entire chunk will be discarded.
Note: If you have already imported KPIs and are importing another KPI chunk, the parameter Nº of imported KPIs will only show the amount of new KPIs. For example, you have a chunk of 1000 KPIs but only 150 are new or not imported before. When the operation is completed the parameter Nº of imported KPIs will be 150 and the remaining will be updated but no output will be generated.