KPIs integration through web service

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

cws_integration.png

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.
Note: In order to perform the integration you will need to download the WSDL file, which is available here.

 

 

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.
Note that even unsuccessful importations may import some data.

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.
string Name - name of the player.
string Username - username of the player.
bool Status - user status in application (active/inactive).

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
  1. string username
  2. string password
  3. GameExternalKpiImportRecord[ ] records 
  4. string tenantName
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.
This service is transactional so when it commits x records, they are written to the database.
If one record in x fails all x are ignored, but previous transactions succeed.
The other parameters, username and password are used to authenticate and authorize the service.
Every element in parameter records, must have the Date property in Coordinated Universal Time (UTC). 
If any element in parameter records contains a KPIId or ExternalId invalid or inexistent it is considered as an error and the transaction will fail.
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  
  • Import Service Notification: No records found in incoming message.
  • Import Service Notification: Found error in SendKpiRecords. [0] records imported. (Exception message)
  • Import Service Notification: Found error in SendKpiRecords. [(number of records commited to database)] records imported. Last record imported [Date:(date of last record imported)|ExternalID: (user external id of last record imported)|KpiID: (kpi id of last record imported)]. (Exception message).
  • Import Service Notification: User not authenticated. Username or password incorrect.
  • Import Service Notification: Importation succeeded. [(number of records commited to database)] records imported. Last record imported [Date:(date of last record imported)|ExternalID: (user external id of last record imported)|KpiID: (kpi id of last record imported)].
  • Import Service Notification: User not authorized. Only administrators can import Kpis.
  • Import Service Notification: Found error in SendKpiRecords. (Exception message)
    • Possible Exception message: Found error in SendKpiRecords. Data is malformed on record: [(date)::(external id)::(kpi id)]
  • Import Service Notification: Tenant Name is not valid.

 

 

CheckKpiRecordsByKpiId
Parameters Returns
  1. string username
  2. string password
  3. int kpiId
  4. string tenantName
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).
Only Gamification administrators can perform the request.

Possible Notifications  
  • Import Service Notification: Request successful.
  • Import Service Notification: User not authenticated. Username or password incorrect.
  • Import Service Notification: User not authorized. Only administrators can import KPIs.
  • Import Service Notification: Something went wrong. (Exception message)
  • Import Service Notification: Tenant Name is not valid.

 

 

CheckKpiRecordsByExternalId
Parameters Returns
  1. string username
  2. string password
  3. string externalId
  4. string tenantName
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  
  • Import Service Notification: Request successful.
  • Import Service Notification: User not authenticated. Username or password incorrect.
  • Import Service Notification: User not authorized.
  • Import Service Notification: Something went wrong. (Exception message)
  • Import Service Notification: Tenant Name is not valid.

 

CheckKpiRecordsByKPIIDAndExternalId
Parameters Returns
  1. string username
  2. string password
  3. int kpiId
  4. string externalId
  5. string tenantName
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.
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  
  • Import Service Notification: Request successful.
  • Import Service Notification: User not authenticated. Username or password incorrect.
  • Import Service Notification: User not authorized.
  • Import Service Notification: Something went wrong. (Exception message)
  • Import Service Notification: Tenant Name is not valid.

 

 

CheckPlayers
Parameters Returns
  1. string username
  2. string password
  3. PlayerMode mode
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.
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  
  • Import Service Notification: Request successful.
  • Import Service Notification: User not authenticated. Username or password incorrect.
  • Import Service Notification: User not authorized.
  • Import Service Notification: Something went wrong. (Exception message)
  • Import Service Notification: Tenant Name is not valid.

 

 

CheckKpiRecordsByKpiIdAndDate
Parameters Returns
  1. string username
  2. string password
  3. int kpiId
  4. datetime startDate
  5. datetime endDate
  6. string tenantName
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.
Parameters username and password, respectively are used to authenticate and authorize the service. Only Gamification administrators can perform the request.
Parameter tenantName, is required to access the correct database instance (for Gamification version 2.2 or higher).
Parameters startDate and endDate, restrict the returned KPIs to a time interval. These parameters must in the Coordinated Universal Time (UTC) format (yyyy-mm-ddThh:mm:ss.MMM).

Possible Notifications  
  • Import Service Notification: Request successful.
  • Import Service Notification: User not authenticated. Username or password incorrect.
  • Import Service Notification: User not authorized.Only administrators can import Kpis.
  • Import Service Notification: Something went wrong. (Exception message)
  • Import Service Notification: Tenant Name is not valid.
  • Import Service Notification: EndDate cannot be before StartDate.

 

 

CheckKpiRecordsByExternalIdAndDate
Parameters Returns
  1. string username
  2. string password
  3. string externalId
  4. datetime startDate
  5. datetime endDate
  6. string tenantName
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.
Parameters username and password, respectively are used to authenticate and authorize the service. Only Gamification administrators can perform the request.
Parameter tenantName, is required to access the correct database instance (for Gamification version 2.2 or higher).
Parameters startDate and endDate, restrict the returned KPIs to a time interval. These parameters must in the Coordinated Universal Time (UTC) format (yyyy-mm-ddThh:mm:ss.MMM).

Possible Notifications  
  • Import Service Notification: Request successful.
  • Import Service Notification: User not authenticated. Username or password incorrect.
  • Import Service Notification: User not authorized.Only administrators can import Kpis.
  • Import Service Notification: Something went wrong. (Exception message)
  • Import Service Notification: Tenant Name is not valid.
  • Import Service Notification: EndDate cannot be before StartDate.

 

 

CheckKpiRecordsByKPIIdAndExternalIdAndDate
Parameters Returns
  1. string username
  2. string password
  3. int kpiId
  4. string externalId
  5. datetime startDate
  6. datetime endDate
  7. string tenantName
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.
Parameters username and password, respectively are used to authenticate and authorize the service. Only Gamification administrators can perform the request.
Parameter tenantName, is required to access the correct database instance (for Gamification version 2.2 or higher).
Parameters startDate and endDate, restrict the returned KPIs to a time interval. These parameters must in the Coordinated Universal Time (UTC) format (yyyy-mm-ddThh:mm:ss.MMM).

Possible Notifications  
  • Import Service Notification: Request successful.
  • Import Service Notification: User not authenticated. Username or password incorrect.
  • Import Service Notification: User not authorized.Only administrators can import Kpis.
  • Import Service Notification: Something went wrong. (Exception message)
  • Import Service Notification: Tenant Name is not valid.
  • Import Service Notification: EndDate cannot be before StartDate.

 

 

DeleteKpiRecordsByKpiIdAndDate
Parameters Returns
  1. string username
  2. string password
  3. int kpiId
  4. datetime startDate
  5. datetime endDate
  6. string tenantName
CheckKpiRecordResult
Description

DeleteKpiRecordsByKpiIdAndDate returns a structure, CheckKpiRecordResult, containing a success flag and a notification.
Parameters username and password, respectively are used to authenticate and authorize the service. Only Gamification administrators can perform the request.
Parameter kpiId, restricts the scope of deletion to only the KPIs with that particular IDs.
Parameter tenantName, is required to access the correct database instance (for Gamification version 2.2 or higher).
Parameters startDate and endDate, restrict the returned KPIs to a time interval. These parameters must in the Coordinated Universal Time (UTC) format (yyyy-mm-ddThh:mm:ss.MMM).

Possible Notifications  
  • Import Service Notification: Request successful.
  • Import Service Notification: User not authenticated. Username or password incorrect.
  • Import Service Notification: User not authorized.Only administrators can import Kpis.
  • Import Service Notification: Something went wrong. (Exception message)
  • Import Service Notification: Tenant Name is not valid.
  • Import Service Notification: EndDate cannot be before StartDate.

 

 

DeleteKpiRecordsByExternalIdAndDate
Parameters Returns
  1. string username
  2. string password
  3. sting externalId
  4. datetime startDate
  5. datetime endDate
  6. string tenantName
CheckKpiRecordResult
Description

DeleteKpiRecordsByExternalIdAndDate returns a structure, CheckKpiRecordResult, containing a success flag and a notification.
Parameters username and password, respectively are used to authenticate and authorize the service. Only Gamification administrators can perform the request.
Parameter externalId, restricts the scope of deletion to only the KPIs with that particular ExternalIDs.
Parameter tenantName, is required to access the correct database instance (for Gamification version 2.2 or higher).
Parameters startDate and endDate, restrict the returned KPIs to a time interval. These parameters must in the Coordinated Universal Time (UTC) format (yyyy-mm-ddThh:mm:ss.MMM).

Possible Notifications  
  • Import Service Notification: Request successful.
  • Import Service Notification: User not authenticated. Username or password incorrect.
  • Import Service Notification: User not authorized.Only administrators can import Kpis.
  • Import Service Notification: Something went wrong. (Exception message)
  • Import Service Notification: Tenant Name is not valid.
  • Import Service Notification: EndDate cannot be before StartDate.

 

 

DeleteKpiRecordsByKPIIdAndExternalIdAndDate
Parameters Returns
  1. string username
  2. string password
  3. int kpiId
  4. sting externalId
  5. datetime startDate
  6. datetime endDate
  7. string tenantName
CheckKpiRecordResult
Description

DeleteKpiRecordsByKpiIdAndExternalIdAndDate returns a structure, CheckKpiRecordResult, containing a success flag and a notification.
Parameters username and password, respectively are used to authenticate and authorize the service. Only Gamification administrators can perform the request.
Parameters kpiId and externalId, restrict the scope of deletion to only the KPIs with that particular KpiIDs and ExternalIDs.
Parameter tenantName, is required to access the correct database instance (for Gamification version 2.2 or higher).
Parameters startDate and endDate, restrict the returned KPIs to a time interval. These parameters must in the Coordinated Universal Time (UTC) format (yyyy-mm-ddThh:mm:ss.MMM).

Possible Notifications  
  • Import Service Notification: Request successful.
  • Import Service Notification: User not authenticated. Username or password incorrect.
  • Import Service Notification: User not authorized.Only administrators can import Kpis.
  • Import Service Notification: Something went wrong. (Exception message)
  • Import Service Notification: Tenant Name is not valid.
  • Import Service Notification: EndDate cannot be before StartDate.

 

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:

You have two chunks of KPIs:

  • One chunk of 1000 KPIs with IDs between 1 and 1000 and
  • A second chunk of 1000 KPIs with IDs between 1001 and 2000.

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.

 

Have more questions? Submit a request