- 6 Minutes to read
- Print
- DarkLight
- PDF
Transfer Data REST API
- 6 Minutes to read
- Print
- DarkLight
- PDF
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:
- Generate Access ID and Access Key
- Get the list of DLRs
- Transfer the Data
- Data (GL, Translations, Transactions & Transactions V2)
- Entity Hierarchy
- Segment Hierarchy
- Currency Exchange Rates
- User Data Load
- Attribute Hierarchy Load
- Attribute Load
- 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.
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
Key | Value |
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"
}
Key | Value |
dataLoadRuleId | DataLoadId. You can pick the required DLR ID from the DLR list you generated previously. |
dataLoadRuleName | DataLoadRuleName. Provide the name of the DLR related to the DLR ID. |
columnDelimiter | Provide the value for the column separator. For example - , |
rowDelimiter | Provide the row delimiter produced by the system (other than the newline character). For example - | |
payload | Provide 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 AuthSample 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
}
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
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.
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"
}