Transfer Data REST API
  • 6 Minutes to read
  • Dark
    Light
  • PDF

Transfer Data REST API

  • Dark
    Light
  • PDF

Article summary

We have upgraded our Structured Planning REST API documentation. Visit our new API portal for an enriched documentation experience.

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
Note
Load Items supported via REST APIs are as follows:
  1. Data (GL, Translations, Transactions & Transactions V2)
  2. Entity Hierarchy
  3. Segment Hierarchy
  4. Currency Exchange Rates
  5. User Data Load
  6. Attribute Hierarchy Load
  7. Attribute Load
  8. Workforce Planning

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. 

Note
The data transfer honors the limits set for web services data loads. The default data transfer limit is set to 10,000 records for each request. Similarly, if the size of the request is more than 1 MB, the API returns the error message as 413 (entity too large).

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

KeyValue
IsLoadCompleted (applicable only for PUT Method)True

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"
}

 

KeyValue
dataLoadRuleIdDataLoadId. You can pick the required DLR ID from the DLR list you generated previously.
dataLoadRuleNameDataLoadRuleName. Provide the name of the DLR related to the DLR ID.
columnDelimiterProvide the value for the column separator. For example - ,
rowDelimiterProvide the row delimiter produced by the system (other than the newline character). For example - |
payloadProvide the number of rows and columns from where the data will be transferred.

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

 Authentication: Basic Auth

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
}

Request 2

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": "03,310|04,410"
}

Sample Response

HTTP/1.1 200 OK

{   
"DataLoadRuleId": 600058,    
"ExcecutionId": "09c8ca47-2ff8-418c-81ce-ede50ae44a91",    "ChunksRecieved": 2,    
"RecordsRecieved": 4,    
"RunAsynchronously": false,    
"Attempts": 1
}
Note
Send this request multiple times to send the complete data.

Last Request

The request for the last batch of data must have the following parameters;

Method

PUT

Endpoint Url Syntax

<Provide Application Url>/financemodel/data/transfer

Headers

Authorization - Basic Auth

IsLoadComapleted - True

Sample 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": "05,11|06,12"
}

You can also send the last request without the IsLoadComplated header and add a Null value for the payload. Following is the sample request 

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

Sample Response

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.
Note
You can retry a failed DLR execution only five times. The number of retries attempted to execute a DLR is available in the API response as the Attempts parameter.

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"
}

Was this article helpful?