D365 Finance and operation

Here we have part 4 for REST API Error handling blog, In this blog I am going to try to cover all possible error handling API which Microsoft provide OOB and custom.

Here we have list of API endpoints which we can use to get complete error details in your integration patterns.

1. GetExecutionSummaryStatus 
2. GetExecutionErrors
3. GetImportStagingErrorFileUrl
4. GenerateImportTargetErrorKeysFile
5. GetImportTargetErrorKeysFileUrl
6. Kartik_getExecptionDetails

This overview diagram can help which endpoint can be used based on your design.

You can find complete request and response in standard Microsoft document, here i am going to cover additional details which is missing on standard document.

1. GetExecutionSummaryStatus 

This API should be called after triggering any import and export package API. This API will help you to identify status of your execution job.

In your integration pattern this API endpoint call should be on First stage to identify to status before calling any additional API to find out error details.

Output

HTTP/1.1 200 OK
{
“@odata.context”:”https:///data/$metadata#Edm.String”,
“value”:””
}

Output parameters

2. GetExecutionErrors

Second API should be called to find tage 1 API return status not Succeeded (Failed,PartialSucessded,NotRun,Unknown,cancelled)

GetExecutionErrors can be used to get the list of errors in a job execution. The API takes the Execution ID as the parameter and returns a set of error messages in a JSON list.

POST /data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.GetExecutionErrors BODY {“executionId”:”<executionId>”}

Execution error API return error from highlighted control from following screenshot.

3. GetImportStagingErrorFileUrl

The API :GetImportStagingErrorFileUrl can be called directly with below parameters in http request body:

And it will return the file url for the error log in F&O below:

(it returns blank error file url if there is no error file available in F&O, for ex below: the button: View error file is greyed out, which indicated there is no error file)

If you are able to see the error file for the failed import execution in F&O,  this API is able to get that file.

Note: I was able to generate this file with composite entity.

GetImportStagingErrorFileUrl – The source code first validates the execution Id  for completed import. The it returns data from field errorFilePath of table\DMFStagingLog.

Likewise, GetExecutionErrors gets the information from tables\  DMFDefinitionGroupExecution and DMFStagingValidationLog.

In test run, I found that there is no data in DMFStagingValidationLog so method returned blank which is correct as per the logic.

4. GenerateImportTargetErrorKeysFile

The GenerateImportTargetErrorKeysFile API is used to generate an error file containing the keys of the import records that failed at the staging to target step of import for a single entity.

If this API returns true, then use the GetImportTargetErrorKeysFileUrl API to get the URL of the generated error keys file.

POST /data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.GenerateImportTargetErrorKeysFile

JSONCopy

Body

{
	"executionId":"<string>",
	"entityName":"<string>"
}

Successful Response:

HTTP/1.1 200 OK
{
	"@odata.context":"https://<baseurl>/data/$metadata#Edm.Boolean",
	"value": <errorsExist>
}

Input parameters

Output parameters

5. GetImportTargetErrorKeysFileUrl  

The GetImportTargetErrorKeysFileUrl API is used to get the URL of the error file that contains the keys of the import records that failed at the staging-to-target step of import for a single entity.

If the error file is available, this API returns the URL. If the error file is still being generated, or if there is no error file, the API returns an empty string.

 Important

Before you call this API, call the GenerateImportTargetErrorKeysFile API to generate the error file. If the GenerateImportTargetErrorKeysFile API returns true, call this API in a loop until it returns a non-empty string. If the GenerateImportTargetErrorKeysFile API returns false, this API will always return an empty string, because there are no errors.

Input

POST /data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.GetImportTargetErrorKeysFileUrl Body { “executionId”:”<string>”, “entityName”:”<string>” }

Sample error file from

Exported error file will have primary key records.

6. Kartik_getExecptionDetails

We verified that few different scenarios and that the error comes in data validation before inserting into the staging table. Therefore, GetImportStagingErrorFileUrl will not give us the result we need. Here is error message:

An OLE DB record is available.  Source: “Microsoft SQL Server Native Client 11.0”  Hresult: 0x80004005  Description: “The statement has been terminated.”.

An OLE DB record is available.  Source: “Microsoft SQL Server Native Client 11.0”  Hresult: 0x80004005  Description: “Violation of PRIMARY KEY constraint ‘I_8131STAGINGIDX’. Cannot insert duplicate key in object ‘dbo.CUSTCUSTOMERGROUPENTITYSTAGING’. The duplicate key value is (5637144576, ImportCustomerGroup,

We have tried below methods which don’t give us the expected result:

• DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.GetExecutionErrors
• DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.GetImportStagingErrorFileUrl
• DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.GetImportTargetErrorKeysFileUrl

from telemetry log and found in this case; exception was logged in table DMFDEFINITIONGROUPEXECUTIONPROGRESS field ERRORXML.  

Here is detailed error:

Sample code to build new DMF endpoint.

[SysODataActionAttribute(“MCSGETErrorDetails”, false)]
public static DMFErrorXml MCSGETErrorDetails(DMFExecutionId _DMFExecutionId)
{
DMFDEFINITIONGROUPEXECUTIONPROGRESS DMFDEFINITIONGROUPEXECUTIONPROGRESS;
select firstonly ErrorXml from DMFDEFINITIONGROUPEXECUTIONPROGRESS
where DMFDEFINITIONGROUPEXECUTIONPROGRESS.ExecutionId == _DMFExecutionId;
return DMFDEFINITIONGROUPEXECUTIONPROGRESS.ErrorXml;
}