Transfer Data REST API

The new Transfer Data rest API loads the data into the Planful database from the source database. You should perform the following steps to use the API:

1. Generate Access ID and Access Key
2. Get the list of DLRs
3. Transfer the Data.

Get the list of DLRs

You can use the following syntax to get the complete list of DLRs:

Method

GET

Endpoint Url Syntax

<Provide Application Url>/financemodel/data/rules

Headers

Authentication: Basic Auth

Sample Response

[

{

"DataLoadRuleId": 600003,

"Name": "Account",

"LoadItem": "Segment Hierarchies"

}

]

If you want to get the list of only GL Data DLRs, use the following endpoint url syntax:

<Provide Application Url>/financemodel/data/rules/gl

If you want to get the list of only Transactions Data DLRs, use the following endpoint url syntax:

<Provide Application Url>/financemodel/data/rules/transactions

Transfer the Data

You can transfer the data from the source database to the Planful database in either a single transfer or batches. If the # records are within the permissible limits, you can transfer the data in a single API call. If the # records are beyond the limits, you must make multiple API calls to send the data in batches. 

Single Transfer

You can use either a POST method or a PUT method to transfer the data in a single API call.

Method

POST/PUT

Endpoint Url Syntax

<Provide Application Url>/financemodel/data/transfer

Headers

  Authentication: Basic Auth

Body

{
"DataLoadRuleConfig": {
"dataLoadRuleId": 609012,
"dataLoadRuleName": "REST_FL_Test_2_XLSX",
"rowDelimiter": "|",
"columnDelimiter": ",",
"callbackOptions": {
"httpMethod": "POST",
"url": "https://<application URL>//financemodel/data/CallbackToLog"
}
},
"payload": "1,2\r\n2,3\r\n3,4\r\n4,5\r\n5,6\r\n6,7\r\n7,8\r\n8,9\r\n9,10\r\n10,11\r\n11,12"
}

Response

The response contains a success or a failure message with a GUID for tracking. If the API call is successful, the response code for Sync DLRs is 200 OK, and for Async DLRs, the response code is 202 Accepted.

Sample API Response

Async

HTTP/1.1 202 ACCEPTED {    
"DataLoadRuleId": 600058,    
"ExcecutionId": "35e76b96-83ab-40e1-897e-e8ea5aa4c171",    "ChunksRecieved": 1,    
"RecordsRecieved": 2,   
"RunAsynchronously": true,    
"Attempts": 1,    
"TransferResponse": {       
"TaskId": "85db011b-d582-4dc9-9ffc-322fbb2540a1",        "Success": true,        
"Message": "Task submitted successfully."    
}
}

Sync

HTTP/1.1 200 OK
{    
"DataLoadRuleId": 600058,    
"ExcecutionId": "def9f7b2-4644-4b89-a4da-f0508eed0b4e",    "ChunksRecieved": 1,    
"RecordsRecieved": 2,    
"RunAsynchronously": false,    
"Attempts": 1,    
"TransferResponse": {        
"Success": true,        
"Message": "Data Transferred Successfully."    
}
}

Data Transfer in Batches

Following is the series of API calls you have to make transfer the data in batches:

Request-1

Method

PUT

Endpoint Url Syntax

<Provide Application Url>/financemodel/data/transfer

Headers

 Authorization - Basic Auth

Sample Request Body

{
"DataLoadRuleConfig": {
"dataLoadRuleId": 600058,
"dataLoadRuleName": "REST_FL_Test_2_XLSX",
"rowDelimiter": "|",
"columnDelimiter": ",",
"callbackOptions": {
"httpMethod": "POST",
"url": "https://fpa-infra.planfuldev.com//financemodel/data/CallbackToLog"
}
},
"payload": "01,110|02,210"
}

Response

The response contains a success or a failure message with a GUID for tracking. If the API call is successful, the response code for Sync DLRs is 200 OK, and the response code for submission of Async DLRs request is 202 Accepted.

Sample Response

HTTP/1.1 200 OK

{    
"DataLoadRuleId": 600058,    
"ExcecutionId": "09c8ca47-2ff8-418c-81ce-ede50ae44a91",    "ChunksRecieved": 1,    
"RecordsRecieved": 2,    
"RunAsynchronously": false,    
"Attempts": 1
}

{
"DataLoadRuleConfig": {
"dataLoadRuleId": 600058,
"dataLoadRuleName": "REST_FL_Test_2_XLSX",
"rowDelimiter": "|",
"columnDelimiter": ",",
"callbackOptions": {
"httpMethod": "POST",
"url": "https://fpa-infra.planfuldev.com//financemodel/data/CallbackToLog"
}
},
"payload": "03,310|04,410"
}

HTTP/1.1 200 OK

{   
"DataLoadRuleId": 600058,    
"ExcecutionId": "09c8ca47-2ff8-418c-81ce-ede50ae44a91",    "ChunksRecieved": 2,    
"RecordsRecieved": 4,    
"RunAsynchronously": false,    
"Attempts": 1
}

IsLoadComapleted - True

{
"DataLoadRuleConfig": {
"dataLoadRuleId": 600058,
"dataLoadRuleName": "REST_FL_Test_2_XLSX",
"rowDelimiter": "|",
"columnDelimiter": ",",
"callbackOptions": {
"httpMethod": "POST",
"url": "https://fpa-infra.planfuldev.com//financemodel/data/CallbackToLog"
}
},
"payload": "05,11|06,12"
}

{
"DataLoadRuleConfig": {
"dataLoadRuleId": 600058,
"dataLoadRuleName": "REST_FL_Test_2_XLSX",
"columnDelimiter": ",",
"callbackOptions": {
"httpMethod": "POST",
"url": "https://fpa-infra.planfuldev.com//financemodel/data/CallbackToLog"
}
},
"payload": null
}

HTTP/1.1 200 OK 
{    
"DataLoadRuleId": 600058,    
"ExcecutionId": "09c8ca47-2ff8-418c-81ce-ede50ae44a91",    "ChunksRecieved": 3,    
"RecordsRecieved": 6,    
"RunAsynchronously": false,    
"Attempts": 1,    
"TransferResponse": {        
"Success": true,        
"Message": "Data Transferred Successfully."    
}
}

Platform: Reset Data Load with Transfer API

From this release, if needed you can now reset any ongoing data load, and start a fresh one. Add the following Header to the Transfer Data API call along with the fresh payload.

ResetDataLoad

Passing the value of DataLoadExecutionId is optional at the moment and it’s recommended to keep the ResetDataLoad parameter value empty. You can reset the ongoing data load only if you have started it.

You can even send the IsLoadCompleted header as True if this is the only chunk you want to load while resetting the previous execution.

Platform: Retry a Failed Data Load with Transfer API

From this release, you can now retry a failed data load. If any data load fails for any reason, and you wish to retry the failed data load after fixing the issue, run the API again and the API will retry the data transfer.

This is more useful when you are loading the data in chunks. You can send the execution ID (this is optional) of the failed DLR, and payload as NULL to retry the transfer. This avoids starting the process from the beginning if any DLR fails. However, there are some conditions the DLR has to meet if you want to retry the data load:

• The DLR should not have any other execution since a failed data load.
• You can retry executing the DLR within 8 hours of a failed data load.

GetDataLoadStatus API

When you initiate a DLR execution through REST API, the API will return an Execution ID in the response. You can now use that Execution ID to know the status of a DLR execution. Following is the GetDataLoadStatus API endpoint:

GET /<application URL>/financemodel/data/GetDataLoadStatus?ExecutionId=<Exec Guid>

Sample Response Body :

{    
"ExecutionId": "bdc0a259-7348-44a3-89b8-f380bdae2dc7",
"ChunksRecieved": 1,    
"RecordsRecieved": 11,    
"LastBatchRecievedDateTimeUtc": "2022-07-15T12:37:05.84",
"LoadCompletedDateTimeUtc": "2022-07-15T12:37:05.867",
"TransferStartedDateTimeUtc": "2022-07-15T12:37:05.9", 
"TransferCompletedDateTimeUtc": "2022-07-15T12:37:14.917",
"Attempts": 1,    
"ExecutionStatus": "Processed"
}

This API now fetches information about both Sync and Async API execution types and is available in the API response. The API can return any of the following execution statuses:

• Uploading
• Uploaded
• Processing
• Processed
• Failed
• Abandoned

Get Running Data Load Status API

You can use the GetRuningDataLoadStatus API to know if there is any execution going on for any DLR. This API just required the DLR name as the query string parameter and it retrieves detailed information about the execution. If there is no active DLR execution, then the API will return a “404 Not Found” message.

Rest API Endpoint - GET /<application URL>/financemodel/data/GetRuningDataLoadStatus?dlrName=<>

Sample Response if there is no ongoing DLR execution:

HTTP/1.1 404 Not Found

Requested data not found. No data load in progress for this DLR 'S - Rest WS GL'

Sample Response if there is any ongoing DLR execution:

{    
"ExecutionId": "ce8ba642-8f6f-4041-a706-fa602eced7c7",
"ChunksRecieved": 1,
"RecordsRecieved": 11,
"LastBatchRecievedDateTimeUtc": "2022-07-21T21:54:15.157",
"LoadCompletedDateTimeUtc": "2022-07-21T21:54:15.21",
"TransferStartedDateTimeUtc": "2022-07-21T21:54:15.26",
"Attempts": 1,
"ExecutionStatus": "Processing"
}