Data management package REST API

This article describes the Data management framework's package representational state transfer (REST) application programming interface (API). The package API lets you integrate by using data packages. The REST API can be used with both cloud deployments and on-premises deployments.

Although on-premises support has been added, API names haven't been changed. Therefore, Microsoft can keep a single API set for both cloud deployments and on-premises deployments.

Choosing an integration API

Two APIs support file-based integration scenarios: the Data management framework's package API and the recurring integrations API. Both APIs support both data import scenarios and data export scenarios. The following table describes the main decision points that you should consider when you're trying to decide which API to use.

If you decide that the recurring integrations API meets your requirement better than the Data management framework's package API, see Recurring integrations. The rest of this article discusses the Data management framework's package API.

Authorization

The Data management framework's package API uses OAuth 2.0 to authorize access. The API must be called by using a valid OAuth access token. For more information about OAuth 2.0 and Microsoft Entra ID, see Authorize access to web applications using OAuth 2.0 and Microsoft Entra ID. For on-premises deployments, Active Directory Federation Services (AD FS) is used for authorization.

Import APIs

The following APIs are used to import files (data packages).

GetImportStagingErrorFileUrl

The GetImportStagingErrorFileUrl API is used to get the URL of the error file containing the input records that failed at the source to the staging step of import for a single entity. An empty string is returned if no error file is generated.

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

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

Successful Response:

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

Input parameters

Output parameters

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

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

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 isn't an error file, the API returns an empty string.

Pseudocode example

errorsExist = GenerateImportTargetErrorKeysFile(executionId, entityName)

if (errorsExist)
{
    errorFileUrl = null

    while (errorFileUrl is not a non-empty string)
    {
        errorFileUrl = GetImportTargetErrorKeysFileUrl(executionId, entityName)
        if (errorFileUrl is not a non-empty string)
        {
            wait for some time before retrying
        }
    }
}

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

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

Here's an example of a successful response.

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

Input parameters

Output parameters

GetAzureWriteUrl

The GetAzureWriteUrl API is used to get a writable blob URL. The method includes a shared access signature (SAS) token that is embedded in the URL. You can use this method to upload a data package to the Azure Blob storage container. For on-premises deployments, this API will still return the URL that has been abstracted to local storage.

POST /data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.GetAzureWriteUrl
BODY
{
    "uniqueFileName":"<string>"
}

Here's an example of a successful response.

HTTP/1.1 200 OK
{
    "@odata.context":"https://<baseurl>/data/$metadata#Edm.String",
    "value": "{\"BlobId\":\"{<GUID>}\",\"BlobUrl\":\"https://<baseurl_id>.blob.core.windows.net/dmf/<uniqueFileName>?<SAS Token>\"}"
    }
}

Input parameters

Output parameters

ImportFromPackage

The ImportFromPackage API is used to initiate an import from the data package that is uploaded to the Blob storage that is associated with your implementation. For on-premises deployments, the import will be initiated from the local storage that the file was uploaded previously to.

There's an async version of this API ImportFromPackageAsync. The specifications are the same. It will be required to capture the execution ID returned and the latter call the GetExecutionSummaryStatus API to determine when the execution has completed.

POST /data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.ImportFromPackage
BODY
{
    "packageUrl":"<string>",
    "definitionGroupId":"<string>",
    "executionId":"<string>",
    "execute":<bool>,
    "overwrite":<bool>,
    "legalEntityId":"<string>"
}

Here's an example of a successful response.

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

Input parameters

Output parameters

Export APIs

The following APIs are used to export files (data packages).

ExportToPackagePreview

The ExportToPackagePreview API is used to preview an export of a data package with a large number of records. This API is applicable to both cloud deployments and on-premises deployments.

There's an async version of this API ImportFromPackagePreviewAsync. The specifications are the same. It will be required to capture the execution ID returned and the latter call the GetExecutionSummaryStatus API to determine when the execution has completed.

• The export data project must be created before you call this API. If the project doesn't exist, a call to the API returns an error.
• If change tracking has been turned on, only records that have been created or updated since the last run are exported. (In other words, only the delta is returned.)
• The number of records returned are limited using the count parameter.

POST /data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.ExportToPackagePreview
BODY
{
    "definitionGroupId":"<Data project name>",
    "packageName":"<Name to use for downloaded file.>",
    "executionId":"<Execution Id if it is a rerun>",
    "reExecute":<bool>,
    "legalEntityId":"<Legal entity Id>",
    "count":"<Legal entity Id>"
}

Here's an example of a successful response.

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

Input parameters

Output parameters

ExportToPackage

The ExportToPackage API is used to initiate an export of a data package. This API is applicable to both cloud deployments and on-premises deployments.

There's an async version of this API ExportToPackageAsync. The specifications are the same. It will be required to capture the execution ID returned and the latter call the GetExecutionSummaryStatus API to determine when the execution has completed.

• The export data project must be created before you call this API. If the project doesn't exist, a call to the API returns an error.
• If change tracking has been turned on, only records that have been created or updated since the last run are exported. (In other words, only the delta is returned.)

POST /data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.ExportToPackage
BODY
{
    "definitionGroupId":"<Data project name>",
    "packageName":"<Name to use for downloaded file.>",
    "executionId":"<Execution Id if it is a rerun>",
    "reExecute":<bool>,
    "legalEntityId":"<Legal entity Id>"
}

Here's an example of a successful response.

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

Input parameters

Output parameters

GetExportedPackageUrl

The GetExportedPackageUrl API is used to get the URL of the data package that was exported by a call to ExportToPackage. This API is applicable to both cloud deployments and on-premises deployments.

POST /data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.GetExportedPackageUrl
BODY
{"executionId":"<Execution Id>"}

Here's an example of a successful response.

HTTP/1.1 200 OK
{
    "@odata.context":"https://<baseurl>/data/$metadata#Edm.String",
    "value":{
        "value":"https://<baseurl_id>.blob.core.windows.net/dmf/<uniqueFileName>?<SAS Token>"
    }
}

Input parameters

Output parameters

Status check API

The following APIs are used to check status. They are used during both import flows and export flows.

GetExecutionSummaryStatus

The GetExecutionSummaryStatus API is used for both import jobs and export jobs. It's used to check the status of a data project execution job. This API is applicable to both cloud deployments and on-premises deployments.

POST /data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.GetExecutionSummaryStatus
BODY
{"executionId":"<executionId>"}

Here's an example of a successful response.

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

Input parameters

Output parameters

Getting the list of errors

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

Import and export processes

The following illustration shows how the Data management package methods can be used to import data packages.

The following illustration shows how the Data management package methods can be used to export data packages.

A sample console application that showcases the data import and data export methods is available on GitHub. For more information, go to https://github.com/Microsoft/Dynamics-AX-Integration/tree/master/FileBasedIntegrationSamples/ConsoleAppSamples.