Import and export APIs

  • 10 minutes

Developers can import and export APIs between finance and operations apps and on-premises deployments. Keep in mind that there are some key differences with these processes for on-premises and cloud deployments:

  • For on-premises deployments, support is added for the Data management package REST API even though API names aren't changed. This way, Microsoft can keep a single API set for both cloud deployments and on-premises deployments.
  • The Data management framework API package uses OAuth 2.0 (Open Authorization Protocol) to authorize access. You must call the API by using a valid OAuth access token.
  • For on-premises deployments, authorization is managed with Active Directory Federation Services (AD FS).
  • When you use the Client Credentials Grant flow, the approved client IDs and the user security mapping that the API enforces are maintained on the Microsoft Entra applications page (System administration > Setup > Microsoft Entra applications). For on-premises deployments, this list must contain a valid client ID from AD FS, and you must append /namespaces/AXSF to the base URL when a connection is made.
  • Recurring integration APIs aren't supported for on-premises deployments.

Importing APIs

To start the data package import process, the ImportFromPackage API is used to initiate an import from a data package. The data package is uploaded to the Blob storage that is associated with the finance and operations apps implementation. To get a writable blob URL for that upload, first call the GetAzureWriteUrl API, which returns a URL that has an embedded shared access signature (SAS) token. The SAS token is valid only during an expiry time window.

For on-premises deployments, the import is initiated from the local storage file that was uploaded previously.

The following code is an example that is used to initiate the import process.

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

The following list describes the various code elements:

  • ImportFromPackage is initiating the import.
  • packageurl is a unique file name that is used to track Blob IDs. You can include a globally unique identifier (GUID) to help guarantee a unique file name.
  • definitionGroupID is a string that represents the name of the data project for the import.
  • executionId is the ID to use for the job. If an empty ID is assigned, a new execution ID is created automatically.
  • execute is a Boolean. If the parameter is set to True, the target step runs.
  • overwrite is also a Boolean that must be set to False when a composite entity is used in a package, if not, then this should be set to True.
  • legalentityId is the legal entity for the import.

If the import is successfully finished, you receive a JSON success response that contains the execution ID of the import.

An asynchronous version of this API, ImportFromPackageAsync, is also available and has the same specifications. Capture the execution ID that it returns, and then call the GetExecutionSummaryStatus API to determine when the execution is finished.

Note

ImportFromPackage uses a batch to perform the import. Use the parallel processing rules in Data management to perform parallel imports. Don't call ImportFromPackage in parallel threads, because the call fails.

Exporting APIs

The export for APIs is similar to the import. The difference is that the ExportToPackage API is used to initiate the export. This is applicable for both cloud and on-premises deployments. You must create the export data project before you call this API. If the project doesn't exist, the call returns an error. If change tracking is turned on, only the records that are created or updated since the last run are exported.

The following is an example of code that is used to initiate the export process.

POST
/data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.ExportToPackage
BODY
{
	"definitionGroupId":"<string>",
	"packageName":"<string>",
	"executionId":"<string>",
	"reExecute":<bool>,
	"legalEntityId":"<string>"
}

The following list describes the various code elements:

  • ExportToPackage - Initiates the export.
  • definitionGroupId - Data project Id.
  • packageName - Name to use for downloaded file.
  • executionId - Execution Id if it's a rerun.
  • reExecute - A Boolean. If the parameter is set to True, the target step reruns.
  • legalentityId - The legal entity for the export.

If the export is finished successfully, you receive a JSON success response that contains the execution ID of the export. To download the exported data package, call the GetExportedPackageUrl API with that execution ID. The API returns a blob URL that has an embedded SAS token.

An asynchronous version of this API, ExportToPackageAsync, is also available and has the same specifications. To preview an export of a data package that has a large number of records, use the ExportToPackagePreview API, which adds a count parameter that limits the number of records that are returned.

For more information