Perform REST Service Request Actions in Deferred Mode

You can use the financialProjectPlans, projectBudgets, or projectForecasts REST service to perform certain actions like the following in a deferred mode using the Process Financial Plan Versions scheduled process:
  • Creating a high-volume financial plan version
  • Creating or updating large number of resources in a high-volume financial plan version

These actions take more time to complete as the entire hierarchy must be updated due to the changes done in a single REST service request. When such actions are performed in a REST integration, the client can choose to process the requests in a deferred mode by deferring the roll-up and plan recalculation to the scheduled process.

In the REST service request, the action to create or update a financial plan version is processed in one of these modes:
  • Online mode - Processing happens as part of the REST request processing and the response is sent back after the processing completes. The financial plan version stays in the Current Working status.
  • Deferred mode - Input payload is validated and the version is created or updated in the Processing status as part of the request processing and rollup processing happens in a deferred mode using the scheduled process. The application groups all the pending deferred requests for processing in a single scheduled process to avoid proliferation of many scheduled process requests. The version status is updated to Current Working after the deferred processing on that version completes. A financial plan version that’s created or updated in the deferred mode can be further updated or edited in the user interface only after its status flips to Current Working.

Note:

The DeferFinancialPlanCreation attribute in the payload determines whether the financial plan version creation happens in real-time or is processed in a deferred mode. Valid values are Y and N. The default value is Y. A value of Y indicates that the version will be created in a deferred mode by the Process Financial Plan Versions scheduled process. A value of N indicates that the version will be created in real time and included in the response of the POST operation.

If you've built a custom user interface, then you should also implement the validation to check for the version status (Current Working versus Processing) and restrict further edits in the custom user interface when the version is in the Processing status. REST services also prevent further updates on a given financial plan version when the version is in the Processing status. You can query the status of the financial plan version using the GET operation with the specific plan version ID and verifying the PlanVersionStatus attribute value in the response payload.

Sample Payloads for Creating or Updating Resources in Deferred Mode Using financialProjectPlans REST Service

You can create or update resources using the financialProjectPlans REST API in deferred mode either in a single action request or a BATCH action request.

Note:

When using the BATCH mode of REST API calls, the system automatically enables deferred processing, even if the DeferFinancialPlanCreation attribute isn't explicitly set to Y. This helps ensure reliable execution of high-volume transactions and prevents potential update conflicts.
Use the batch mode of REST API calls to group multiple updates that must happen on the same financial project plan version. This avoids errors if the deferred processing of a previous REST API call is still under process when you send a subsequent request on the same financial project plan version.

At the same time, integrations can hit timeout errors if thousands of create or update calls are sent in the BATCH action. So, we recommend to build the integration using the BATCH action calls in a staggered mode along with handling the scenarios when the PlanVersionStatus attribute is set to the Processing status when sending a subsequent request on the same financial project plan version.

Following are some sample payloads where the REST client passes upsert-mode:true in the request headers and the DeferProcessing parameter is set to Y to indicate that the request will be processed in the deferred mode.

Here's the sample payload to create resources in a single action request:

{
"PlanVersionId" : 100100140793845,
"DeferProcessing": "Y",
"ResourceAssignments": [
{
"TaskNumber": "4",
"ResourceName": "Heather, Ms. Emily",
"PlanningAmounts": [
{
"PlannedQuantity": 110,
"Currency": "USD"
}
]
}
]
}

Here's the sample payload to create resources in a batch action request:

{
"parts": [
{
"id": "part1",
"path": "/financialProjectPlans",
"operation": "upsert",
"payload": {
"PlanVersionId" : 100100140793845,
"DeferProcessing": "Y",
"ResourceAssignments": [
{
"TaskNumber": "1",
"ResourceName": "Heather, Ms. Emily",
"PlanningAmounts": [
{
"PlannedQuantity": 110,
"Currency": "USD"
}
]
}
]
}
},
{
"id": "part2",
"path": "/financialProjectPlans",
"operation": "upsert",
"payload": {
"PlanVersionId" : 100100140793845,
"DeferProcessing": "N",
"ResourceAssignments": [
{
"TaskNumber": "2",
"ResourceName": "Heather, Ms. Emily",
"PlanningAmounts": [
{
"PlannedQuantity": 120,
"Currency": "USD"
}
]
}
]
}
}
]
}

Here's the sample payload to update resources in a batch action request:

{
"parts": [
{
"id": "part1",
"path": "/financialProjectPlans",
"operation": "upsert",
"payload": {
"PlanVersionId" : 100100140793845,
"DeferProcessing": "Y",
"ResourceAssignments": [
{
"PlanningElementId": 300100185725505,
"PlanningAmounts": [
{
"PlanLineId": 300100185725506,
"PlannedQuantity": 10
}
]
}
]
}
}
,
{
"id": "part2",
"path": "/financialProjectPlans",
"operation": "upsert",
"payload": {
"PlanVersionId" : 100100140793846,
"DeferProcessing": "Y",
"ResourceAssignments": [
{
"PlanningElementId": 300100185725507,
"PlanningAmounts": [
{
"PlanLineId": 300100185725508,
"PlannedQuantity": 20
}
]
}
]
}
}
]
}