Push data to Blue using API functions

To import data sources into Blue, the following API calls are required to push all types of data :

• GetDataSourceList()
• GetDataBlockInformation()
• RegisterImport()
• PushObjectDataV2()
• PrepareDataToFinalizeImportV2()
• FinalizeImport()
• CancelImport()

Overview of Web Service Methods in Blue

1. GetDataSourceList() - Retrieves the ID of the data source where data will be stored.
2. GetDataBlockInformation() - Retrieves the block name from the specified data source.
3. RegisterImport() - Starts the import process and returns a transaction ID.
4. PushObjectDataV2() - Creates and pushes the data into the data source.
5. PrepareDataToFinalizeImportV2() - Prepares and validates the data before finalizing the import.
6. FinalizeImport() - Completes the import process.
7. CancelImport() - Cancels the current import. It can be executed anytime before calling FinalizeImport().

Web Service Endpoints

API structure follows this format:

• Endpoint: https://BlueApplicationURL.com/BlueApplicationNameWS/BlueWebService.svc
• WSDL: https://BlueApplicationURL.com/BlueApplicationNameWS/BlueWebService.svc?wsdl

These URLs are for reference only. Please contact your Blue administrator or the Explorance support team for the correct endpoints.

Prerequisites for Python

Ensure the requests library is installed in your Python environment:

pip install requests

Example: Pushing a Relational Data Source

If Blue cannot directly connect to the database, APIs can serve as a standalone intermediary to extract and push data. The following C# sample code assumes a service reference with the name srvRefImport has been added into the project. The srvRefImport Class refers to BlueWebService.svc endpoint.
Error handling and verification can be added for web service responses. Let's first create an API Key function, to call it as many times as needed.

C# sample code:

public static string ApiKey()
{
   string APIkey = "00000000-0000-0000-0000-000000000000";
   return APIkey;
}

Python Sample code:

api_key = "00000000-0000-0000-0000-000000000000"

1. GetDataSourceList()

The GetDataSourceList() function must be called to retrieve the ID of the "CourseStudents" data source. This ID is returned in the SourceID parameter (e.g., "Data4").

2. GetDataBlockInformation()

This step gets the name(s) of the block(s) associated with the specified data source.

3. RegisterImport()

This function initiates an import transaction. It requires the ID of the "CourseStudents" data source to be passed as a parameter.

4. PushObjectDataV2(), PrepareDataToFinalizeImportV2(), and FinalizeImport()

Once the transaction has started, the PushObjectDataV2() function is used to push data into the system.

Import Status Messages

Each function returns status messages indicating the current state of the import process:

• RegisterImport()
  • Status -4: This status is returned immediately after the function is executed.
• PushObjectDataV2()
  • Status -3: Indicates that the import was manually cancelled (e.g., by calling CancelImport()).
  • Status -2: Indicates that the import was automatically cancelled by the API or failed after calling FinalizeImport().
  • Status 0–99: Indicates that the data push is in progress. The import must be finalized using FinalizeImport() for the status to become 100.

If the import is not completed, finalized, or cancelled, no subsequent pushes will be accepted.

Recommendations

GetCurrentImportingDataSourceProcess - This function retrieves the current progress status of an ongoing import and determines whether CancelImport() should be called.
It accepts the following four parameters:

• API Key (required)
• String (output message)
• Int (output progress status)
• Long (output transaction ID)

Upon execution, the function returns the current TransactionID, which can be used with CancelImport() if the data push needs to be interrupted. Cancelling will terminate the entire import.

The progressStatus value indicates how far along the import is (e.g., 50%).

• If progressStatus < 0 (e.g., -1, -2, or -3): The transaction has already been cancelled or flushed. No further action is needed.
• If progressStatus > 0 (e.g., 1–99): If the import fails, CancelImport() should be called to reset the process and generate a new transaction ID.

Error Messages

The web service methods generate messages that indicate whether or not they are successful. Specifically, each web function returns two strings, called Message and APIKeyHeader:

• When the web function is successful, the Message will be “Success”.
• When the web function is unsuccessful, Message will contain an error message.
• When the API key is valid, APIKeyHeader will be “Valid API_KEY“.
• When the API key is invalid, APIKeyHeader will be “Invalid API_KEY”.

The following table lists the possible messages (including error messages) that the web functions can generate:

List of Warnings

Row {0}: Indicates the specific entry where the problem occurs.

SOAP samples

The samples of each of the functions that are described in this document are given below.