Metadata upload/download

For the integration or exchange of data with other applications, the import and export of entire models and the creation of reports in various common formats is supported.

Note

In the following examples, the server https://www.myserver.com and the database test as well as the scheme MyModel are used for illustration purposes (e.g. in the path https://www.myserver.com/api/test/schemes/MyModel). The server and the database as well as the scheme must be replaced accordingly in all actual requests. Depending on the configuration, the URL may also have to be extended by the context path (e.g. https://www.myserver.com/dataspot/api/test/schemes/MyModel).

The upload API und download API over HTTP are implemented according to the REST software architecture paradigm.

Metamodel

The metamodel documents all properties and relationships of metadata objects and provides the foundation for the upload/download API. The metamodel is available in the database meta at the following URL:

https://www.myserver.com/web/meta

Note

The database meta can be created in the admin console (https://www.myserver.com/web/admin).

Models

The following models can be uploaded and downloaded:

Business data model
Reference data model
Measures catalog
Data catalog
Quality model
Data domain model
Data model
System catalog
Processing directory
Project directory

Note

In addition to these models, the DX organization (including all persons, groups, etc.) and the tenant can also be imported and exported.

Upload API

The upload API is a programming interface that (analogous to the upload in the user interface) allows metadata to be imported:

The properties depend on the respective model for which metadata is imported.
The metadata to be imported can be provided in various formats.

Functionality

Attention

As of version 3, the option agentId is considered when determining obsolete metadata objects and the option onDelete is also applied to subordinate obsolete metadata objects.

The upload API reconciles the imported metadata with the existing metadata objects. The imported metadata objects are mapped to the existing metadata objects based on their labels. These business keys are used to determine the corresponding metadata objects:

If a metadata object with the label does not exist, it is added.
If a metadata object with the label exists, the relevant properties are updated.
- Only properties that are provided with content are updated.
  - Properties that are not provided remain unchanged.
- If custom properties are configured in the database, these are also imported.
- The new version can be seen in the version history.

Note

Due to the described functionality, it is not possible to rename metadata objects using the upload API. Instead, metadata objects can be renamed either using the metadata REST/API or directly in the user interface.

The upload API supports the modes Add or update only, Reconcile elements, and Reconcile model.

`Add or update only` (`ADD`)

All imported metadata objects are added or updated in the model (see above).
- If the option onInsert is defined, added metadata objects are set to the specified status. If the option onUpdate is defined, updated metadata objects are set to the specified status.
Existing metadata objects, that are not imported in the model, are not changed.

`Reconcile elements` (`REPLACE`)

All imported metadata objects are added or updated in the model (see above).
- If the option onInsert is defined, added metadata objects are set to the specified status. If the option onUpdate is defined, updated metadata objects are set to the specified status.
Existing metadata objects, that are not imported in the model, are considered obsolete (see option agentId), if their superordinate metadata object has been imported.
- Obsolete metadata objects are deleted from the model or, if the option onDelete is defined, set to the specified status.
Existing metadata objects, that are not imported in the model, are not considered obsolete and are not changed, if their superordinate metadata object has not been imported.

Explanation

For each imported metadata object, the subordinate metadata objects are fully reconciled:

All imported subordinate metadata objects are added or updated in the model (see above).
Existing subordinate metadata objects, that have not been imported in the model, are considered obsolete.
- Obsolete subordinate metadata objects are deleted from the model or, if the option onDelete is defined, set to the specified status.

`Reconcile model` (`FULL_LOAD`)

All imported metadata objects are added or updated in the model (see above).
- If the option onInsert is defined, added metadata objects are set to the specified status. If the option onUpdate is defined, updated metadata objects are set to the specified status.
Existing metadata objects, that are not imported in the model, are considered obsolete (see option agentId).
- Obsolete metadata objects are deleted from the model or, if the option onDelete is defined, set to the specified status.

Tooltip

The mode is defined with the option operation as well as with onInsert, onUpdate, and onDelete.

Options

The upload API for a model is available at the following URL:

https://www.myserver.com/api/test/schemes/MyModel/upload

The data is transferred as multipart/form-data. The options are passed as query parameters in the URL.

The HTTP header attribute Content-Disposition defines the parameter name, describing the data and determining the format, as well as the optional parameter filename, containing the original filename of the transferred file.

Content-Type: multipart/form-data
Content-Disposition: form-data; name="import.json"; filename="Datatypes.json"

The file extension of the parameter name in the HTTP header attribute Content-Disposition determines the format of the data.

File extension	Format	Media type
`.xlsx`	XLSX (Microsoft Excel)	`multipart/form-data`
`.zip`	See option `format`	`multipart/form-data`
`.xml`	XML	`multipart/form-data`
`.json`	JSON	`multipart/form-data`
`.ddl`, `.sql`	DDL/SQL	`multipart/form-data`

Note

If the file extension is .zip, the format of the data is defined with the option format. In all other cases, the option format is ignored and the format of the data is determined by the file extension only.

gzip

The data can be transferred compressed with gzip. In this case, the file extension of the parameter name in the HTTP header attribute Content-Disposition must contain the original file extension (.xlsx, .zip, .xml, .json, .ddl, or .sql) followed by the file extension .gz.

Content-Type: multipart/form-data
Content-Disposition: form-data; name="import.json.gz"; filename="Datatypes.json.gz"

After the file has been transferred, it is automatically unpacked and processed. The format of the data is determined by the original file extension (or the option format).

Note

Compression with gzip is only supported if the upload API is called asynchronously.

Option `v`

The option v defines the version of the upload API.

`v`	Version	Description
`2`	Version 2
`3` (default)	Version 3	See options `onDelete` and `agentId`.

/upload?v=3&agentId=SalesProd

Option `format`

The option format defines the format of the data, if the file extension is .zip. Otherwise, the format is determined by the file extension of the parameter name in the HTTP header attribute Content-Disposition.

`format`	File extension	Format	Media type
	`.xlsx`	XLSX (Microsoft Excel)	`multipart/form-data`
`CSV` (default)	`.zip`	CSV (Zipped)	`multipart/form-data`
	`.xml`	XML	`multipart/form-data`
	`.json`	JSON	`multipart/form-data`
	`.ddl`, `.sql`	DDL/SQL	`multipart/form-data`
`XSD`	`.zip`	XSD (Zipped)	`multipart/form-data`
`JSON_SCHEMA`	`.zip`	JSON Schema (Zipped)	`multipart/form-data`

/upload?format=CSV
/upload?format=XSD
/upload?format=JSON_SCHEMA

Note

If the file extension is .zip but the option format is not defined, the data is uploaded as CSV (Zipped) by default.

Option `operation`

The option operation defines whether existing metadata objects, that are not imported in the model, are considered obsolete.

Note

As of version 3, the option agentId is considered when determining obsolete metadata objects.

`operation`	Mode
`ADD` (default)	`Add or update only`
`REPLACE`	`Reconcile elements`
`FULL_LOAD`	`Reconcile model`

/upload?operation=ADD
/upload?operation=REPLACE
/upload?operation=FULL_LOAD

Option `onInsert`

The option onInsert defines whether added metadata objects are set to a specified status.

`onInsert`	Description
	Added metadata objects are set to the initial status of the assigned workflow.
`<STATUS>`	Added metadata objects are set to the status `<STATUS>`.

/upload?operation=REPLACE&onInsert=WORKING

Note

A status that is explicitly specified in the imported data overrides the option onInsert as well as the initial status of the assigned workflow, and is set for the added metadata object.

Option `onUpdate`

The option onUpdate defines whether updated metadata objects are set to a specified status.

`onUpdate`	Description
	Updated metadata objects are not set to a new status.
`<STATUS>`	Updated metadata objects are set to the status `<STATUS>`.

/upload?operation=REPLACE&onUpdate=SUBMITTED

Note

A status that is explicitly specified in the imported data overrides the option onUpdate, and is set for the updated metadata object.

Option `onDelete`

The option onDelete defines whether obsolete metadata objects are deleted or set to a specified status.

Note

As of version 3, the option agentId is considered when determining obsolete metadata objects.

`onDelete`	Description
	Obsolete metadata objects are deleted.
`<STATUS>`	Obsolete metadata objects are set to the status `<STATUS>`.

Attention

In version 2, only the status of the obsolete metadata object is set to <STATUS>. The status of its subordinate metadata objects is not changed.

As of version 3, the status of all its subordinate metadata objects is also set to <STATUS> hierarchically.

/upload?v=3&operation=REPLACE&onDelete=INACTIVE
/upload?operation=FULL_LOAD&onDelete=REJECTED

Option `dryRun`

The option dryRun defines whether the upload is performed as a test run, but without actually changing data. When the test run has completed, the statistics and any existing logs can be queried.

`dryRun`	Description
`true`	Perform test run, without actually changing data.
`false` (default)	Upload data.

/upload?dryRun=true
/upload?operation=REPLACE&dryRun=false
/upload?operation=FULL_LOAD&onDelete=INACTIVE&dryRun=true

Option `agentId`

The option agentId defines the identification of the agent. The agent identification is an arbitrary string that uniquely identifies the software agent calling the upload API. The agent identification allows the origin of imported metadata objects to be traced.

Note

The option agentId is supported as of version 3.

`agentId`	Description
`<ID>`	The agent identification `<ID>` is stored for each imported metadata object, i.e. the agent with the identification `<ID>` takes ownership of the imported metadata objects. The agent identifications of all imported metadata objects are overwritten, even if these metadata objects were previously imported by other agents.
	The agent identification of the imported metadata objects is not changed or deleted.

Note

When manually creating or importing metadata objects in the user interface, no agent identification is set. The agent identification of metadata objects that were previously imported by other agents is therefore not changed or deleted.

When determining obsolete metadata objects (Reconcile elements and Reconcile model), only metadata objects that have the same agent identification as the option agentId (or, if the option agentId is not set, have no agent identification) are taken into account. Existing metadata objects, that are not imported, are only considered obsolete if they were previously imported by the same agent.

Tooltip

The agent identification allows various agents to import metadata objects from different sources (e.g. into the same model or collection) without deleting or deactivating each other's metadata objects.

This prevents an agent from accidentally deleting or deactivating metadata that belongs to another agent or that was created manually in the user interface.

/upload?agentId=SalesProd

Tooltip

If applicable, the identification of the agent is displayed in the status of the imported metadata object.

Option `agentName`

The option agentName defines the name of the agent calling the upload API.

/upload?agentId=SalesProd&agentName=DatabaseConnector

Tooltipp

If applicable, the name of the agent is displayed in the dashboard as the job label.

Option `ignoreUnknownAnnotations`

The option ignoreUnknownAnnotations defines whether imported annotations (customer-specific stereotypes or properties) that are not available in the model are deleted or cause an error message.

`ignoreUnknownAnnotations`	Description
`true`	Imported annotations that are not available in the model are deleted.
`false` (default)	Imported annotations that are not available in the model cause an error message.

/upload?ignoreUnknownAnnotations=true

Tooltip

Stereotypes and properties are typically defined in profiles and assigned to models. The option ignoreUnknownAnnotations allows the import of metadata that contains customer-specific stereotypes or properties, even if the corresponding profile has not yet been assigned to the model. The unknown annotations are deleted.

Language

The HTTP header attribute Accept-Language defines the language of the format XLSX (Microsoft Excel), where the table names and headings can be imported in different languages (e.g. Sammlungen or Collections, Schreibgeschützt or Read-only).

`Accept-Language`	Language
	Server default language
`de`	German
`en`	English

Accept-Language: de
Accept-Language: en

Attention

If the imported file has a different language than the default language of the server, the language must be explicitly specified. Otherwise, the expected table names and headings cannot be detected and assigned correctly, meaning that the metadata will not be imported or possibly will be reconciled incorrectly.

HTTP methods

The HTTP method PUT or POST defines whether the upload API is called synchronously or asynchronously.

HTTP method	Description
`PUT`	The upload API is called synchronously. The request waits until the upload is complete and then returns the statistics or an error message.
`POST`	The upload API is called asynchronously. The request starts a job that runs in the background and performs the upload. When the job has completed, the statistics and any existing logs can be queried.

Usage

For the following examples the open source tool curl is used. Alternatively, any library that can communicate over HTTP is also suitable.

Note

For illustration purposes, the HTTP messages in the examples are simplified or abbreviated.

Note

The upload API requires appropriate login credentials (e.g. <user> and <password>). Depending on the authentication method (Login ID and password, Single sign-on, Same sign-in, OpenID Connect) and used tools (e.g. curl), different mechanisms (e.g. basic authentication, bearer token) may be necessary to provide the credentials.

The user must exist and have administrator privileges.

Upload API (synchronous)

The upload API can be called with the HTTP method PUT to run the upload synchronously. Using the option -F, the content of a file can be transferred as multipart/form-data.

curl -X PUT -u <user>:<password> -F <name>=@<filename> "https://www.myserver.com/api/test/schemes/MyModel/upload"

The request waits until the upload is complete and then returns the statistics or an error message.

Example: Import metadata (synchronous)

curl -X PUT -u jdoe:s3cr3t -F import.xlsx=@MyModel.xlsx "https://www.myserver.com/api/test/schemes/MyModel/upload"
curl -X PUT -u jdoe:s3cr3t -H "Accept-Language: en" -F import.xlsx=@MyModel.xlsx "https://www.myserver.com/api/test/schemes/MyModel/upload"
curl -X PUT -u jdoe:s3cr3t -F import.zip=@MyModel.zip   "https://www.myserver.com/api/test/schemes/MyModel/upload?operation=ADD"
curl -X PUT -u jdoe:s3cr3t -F import.xml=@MyModel.xml   "https://www.myserver.com/api/test/schemes/MyModel/upload?operation=REPLACE&dryRun=true"
curl -X PUT -u jdoe:s3cr3t -F import.json=@MyModel.json "https://www.myserver.com/api/test/schemes/MyModel/upload?operation=FULL_LOAD&onDelete=INACTIVE"

Example: Request and error handling (synchronous)

The upload API is called with the HTTP method PUT to import the model Datatypes synchronously. Using the option -F, the content of the file Datatypes.json is transferred as multipart/form-data with the name import.json.

curl -X PUT -u jdoe:s3cr3t -F import.json=@Datatypes.json "https://www.myserver.com/api/test/schemes/Datatypes/upload"

PUT /api/test/schemes/Datatypes/upload HTTP/1.1
Host: www.myserver.com
Content-Type: multipart/form-data
Content-Disposition: form-data; name="import.json"; filename="Datatypes.json"

Note

The format is automatically set to JSON, based on the file extension .json of the parameter name.

The request performs the complete upload and responds with the statistics:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "level": "DEBUG",
    "message": "1 *Collection* processed."
  },
  {
    "level": "DEBUG",
    "message": "1 *Data domain* processed."
  }
]

In case of an error (HTTP status code: 400), the HTTP response contains an error message:

HTTP/1.1 400
Content-Type: application/json

{
  "type": "JobExecutionException",
  "message": "An error has occured while uploading file *import.json*",
  "errors": [
    {
      "error": "DataDomain.inCollection, line: 24: Collection *Persons* was not found!"
    },
    {
      "error": "DataDomain.inCollection, line: 24: *Collection* is mandatory!"
    }
  ]
}

Upload API (asynchronous)

The upload API can be called with the HTTP method POST to run the upload asynchronously. Using the option -F, the content of a file can be transferred as multipart/form-data.

curl -X POST -u <user>:<password> -F <name>=@<filename> "https://www.myserver.com/api/test/schemes/MyModel/upload"

The request starts a job and returns the corresponding job ID. The job runs in the background and performs the upload. The status of the job can be polled with the job ID. When the job has completed, the statistics and any existing logs can be queried.

Example: Import metadata (asynchronous)

curl -X POST -u jdoe:s3cr3t -F import.xlsx=@MyModel.xlsx "https://www.myserver.com/api/test/schemes/MyModel/upload"
curl -X POST -u jdoe:s3cr3t -H "Accept-Language: en" -F import.xlsx=@MyModel.xlsx "https://www.myserver.com/api/test/schemes/MyModel/upload"
curl -X POST -u jdoe:s3cr3t -F import.zip=@MyModel.zip   "https://www.myserver.com/api/test/schemes/MyModel/upload?operation=ADD"
curl -X POST -u jdoe:s3cr3t -F import.xml=@MyModel.xml   "https://www.myserver.com/api/test/schemes/MyModel/upload?operation=REPLACE&dryRun=true"
curl -X POST -u jdoe:s3cr3t -F import.json=@MyModel.json "https://www.myserver.com/api/test/schemes/MyModel/upload&operation=FULL_LOAD&onDelete=INACTIVE"

Example: Request and error handling (asynchronous)

The upload API is called with the HTTP method POST to import the model Datatypes asynchronously. Using the option -F, the content of the file Datatypes.json is transferred as multipart/form-data with the name import.json.

curl -X POST -u jdoe:s3cr3t -F import.json=@Datatypes.json "https://www.myserver.com/api/test/schemes/Datatypes/upload"

POST /api/test/schemes/Datatypes/upload HTTP/1.1
Host: www.myserver.com
Content-Type: multipart/form-data
Content-Disposition: form-data; name="import.json"; filename="Datatypes.json"

Note

The format is automatically set to JSON, based on the file extension .json of the parameter name.

The request starts a job and responds with the job ID:

HTTP/1.1 200
Content-Type: application/json

{ "id":"e5b5138c-748f-42ec-a1de-26aef7cf835c" }

The status of the job can be polled with the job ID:

curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/statistics"

GET /api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/statistics HTTP/1.1
Host: www.myserver.com

When the job has completed (HTTP status code: 200), the HTTP response contains the job status COMPLETED and the statistics:

HTTP/1.1 200
Content-Type: application/json

{
  "messages": [
    {
      "level": "INFO",
      "message": "*Import import.json* successful (00:00:00)."
    },
    {
      "level": "DEBUG",
      "message": "1 *Collection* processed."
    },
    {
      "level": "DEBUG",
      "message": "1 *Data domain* processed."
    }
  ],
  "status": "COMPLETED"
}

In case of an error, the HTTP response contains the job status FAILED and the statistics:

HTTP/1.1 200
Content-Type: application/json

{
  "messages": [
    {
      "level": "ERROR",
      "message": "*Import import.json* failed (00:00:00)!"
    },
    {
      "level": "ERROR",
      "message": "2 *errors* occured!"
    },
    {
      "level": "DEBUG",
      "message": "1 *Collection* processed."
    }
  ],
  "status": "FAILED"
}

The exact cause of the error can be found in the logs:

curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/logs"

GET /api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/logs HTTP/1.1
Host: www.myserver.com

HTTP/1.1 200
Content-Type: application/json

{
  "totalCount": 2,
  "data": [
    {
      "level": "ERROR",
      "message": "DataDomain.inCollection, line: 24: Collection *Persons* was not found!"
    },
    {
      "level": "ERROR",
      "message": "DataDomain.inCollection, line: 24: *Collection* is mandatory!"
    }
  ]
}

Download API

The download API is a programming interface that (analogous to the download in the user interface) allows metadata to be exported and reports to be generated:

The properties depend on the respective model for which metadata is exported.
The metadata to be exported can be provided in various formats.

Functionality

The download API reads all metadata objects of a model and exports them according to the following rules:

Only properties that have content are exported.
- Empty properties are not exported.
If custom properties are configured in the database, these are also exported.

Options

The download API for a model is available at the following URL:

https://www.myserver.com/api/test/schemes/MyModel/download

The options are passed as query parameters in the URL.

Option `format`

The option format defines the format of the data.

`format`	File extension	Format	Media type
`XLSX`	`.xlsx`	XLSX (Microsoft Excel)	`application/x-xls`
`CSV`	`.zip`	CSV (Zipped)	`text/csv+zip`
`XML`	`.xml`	XML	`application/xml`
`JSON`	`.json`	JSON	`application/json`
`SQL`	`.sql`	DDL/SQL	`application/sql`

/download?format=JSON
/download?format=XLSX
/download?format=SQL&targetDatabase=SQLServer

Note

The download in the format XLSX (Microsoft Excel) may not exceed 65,536 rows.

Note

For the format SQL the option targetDatabase must also be defined.

Note

As of release 4.2, metadata is exported with /download and the option format.

The following paths for exporting metadata are still supported, but are considered deprecated:

/download.zip
/download.json
/download.xlsx
/download.xml
/download.sql

Option `xsl`

The option xsl defines the generated report.

`xsl`	Name	Media type
`DataModel_xmi.xsl`	UML Export	`application/vnd.xmi+xml`
`DataQualityReport_pdf.xsl`	Data Quality Report	`application/pdf`
`Impact_pdf.xsl`	Impact Report	`application/pdf`
`Lineage_pdf.xsl`	Lineage Report	`application/pdf`
`MappingReport_csv.xsl`	Mapping Report	`text/csv`
`MappingReport_pdf.xsl`	Mapping Report	`application/pdf`
`Metadata_pdf.xsl`	Metadata Report	`application/pdf`
`Organization_pdf.xsl`	Organization Report	`application/pdf`
`ProcessingRecords_pdf.xsl`	GDPR Processing Records	`application/pdf`
`ProjectReport_pdf.xsl`	Project Report	`application/pdf`
`ReferenceValues_csv.xsl`	Reference values Export	`text/csv`
`SearchReport_csv.xsl`	Search Result Report	`text/csv`
`SearchReport_pdf.xsl`	Search Result Report	`application/pdf`
`Statistics_csv.xsl`	Collection Statistics	`text/csv`
`Statistics_pdf.xsl`	Collection Statistics	`application/pdf`
`TicketReport_csv.xsl`	Ticket Report	`text/csv`
`TicketReport_pdf.xsl`	Ticket Report	`application/pdf`

Tooltip

Additional, customer-specific reports in the format .xsl (XSLT) can be uploaded and edited on the tenant page. Customer-specific reports can be generated with the download API.

/download?xsl=Metadata_pdf.xsl
/download?xsl=Statistics_csv.xsl

Note

The generated report may not exceed 100 MB.

Note

As of release 4.2, reports are generated with /download and the option xsl.

The following path for generating reports is still supported, but is considered deprecated:

/MyModel.xml?xsl=<report>

Option `v`

The option v defines the version of the download API.

`v`	Version
`2`	Version 2
`3` (default)	Version 3

/download?v=3&format=JSON

Option `targetDatabase`

The option targetDatabase defines the target database and the specific SQL syntax when downloading with the option format=SQL.

`targetDatabase`	Database
`PostgreSQL`	PostgreSQL
`Oracle`	Oracle
`SQLServer`	Microsoft SQL Server
`MySQL`	MySQL

/download?format=SQL&targetDatabase=PostgreSQL
/download?format=SQL&targetDatabase=Oracle

Option `language`

The option language defines the language of the format XLSX (Microsoft Excel), where the table names and headings can be exported in different languages (e.g. Sammlungen or Collections, Schreibgeschützt or Read-only).

`language`	Language
	Server default language
`de`	German
`en`	English

/download?language=de
/download?language=en

Note

Alternatively, the language can be defined in the HTTP header attribute Accept-Language, but will be overridden by the option language, if present.

Accept-Language: de
Accept-Language: en

Option `publicOnly`

The option publicOnly defines whether only published metadata or all metadata is exported.

`publicOnly`	Description
`true`	Only published metadata is exported.
`false` (default)	All metadata is exported.

/download?publicOnly=true

Note

Alternatively, the HTTP header attribute Accept-PublicOnly can be defined, but will be overridden by the option publicOnly, if present.

Accept-PublicOnly: true

Option `version`

The option version defines a point in time in the history, exporting the metadata in the state at the selected point in time.

`version`	Description
	The metadata is exported in the most recent state.
Timestamp (Epoch) in millseconds	The metadata is exported in the state at the selected point in time.

/download?version=1698676897000

Note

Alternatively, the timestamp can be defined in the HTTP header attribute Accept-Version, but will be overridden by the option version, if present.

Accept-Version: 1698676897000

HTTP methods

The HTTP method GET or POST defines whether the download API is called synchronously or asynchronously.

HTTP method	Description
`GET`	The download API is called synchronously. The request waits until the download is complete and then returns the exported metadata or the generated report or an error message.
`POST`	The download API is called asynchronously. The request starts a job that runs in the background and performs the download. When the job has completed, the exported metadata or the generated report can be downloaded and the statistics and any existing logs can be queried.

Usage

For the following examples the open source tool curl is used. Alternatively, any library that can communicate over HTTP is also suitable.

Note

For illustration purposes, the HTTP messages in the examples are simplified or abbreviated.

Note

The user must be authorized.

Download API (synchronous)

The download API can be called with the HTTP method GET and the option format to export metadata synchronously.

curl -X GET -u <user>:<password> "https://www.myserver.com/api/test/schemes/MyModel/download?format=<format>"

The download API can be called with the HTTP method GET and the option xsl to generate a report synchronously.

curl -X GET -u <user>:<password> "https://www.myserver.com/api/test/schemes/MyModel/download?xsl=<report>"

The request waits until the download is complete and then returns the exported metadata or the generated report or an error message.

Note

For binary formats (.xlsx, .zip, .pdf), it is recommended to store the response in a file using the option -o, rather than output to the console.

Example: Export metadata or generate report (synchronous)

curl -X GET -u jdoe:s3cr3t -o MyModel.xlsx "https://www.myserver.com/api/test/schemes/MyModel/download?format=XLSX"
curl -X GET -u jdoe:s3cr3t -H "Accept-Language: en" "https://www.myserver.com/api/test/schemes/MyModel/download?format=XLSX"
curl -X GET -u jdoe:s3cr3t -o MyModel.zip "https://www.myserver.com/api/test/schemes/MyModel/download?format=CSV"
curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=XML"
curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=JSON"
curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=SQL&targetDatabase=PostgreSQL"

curl -X GET -u jdoe:s3cr3t -o Metadata.pdf "https://www.myserver.com/api/test/schemes/MyModel/download?xsl=Metadata_pdf.xsl"
curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?xsl=ReferenceValues_csv.xsl"

Example: Request and error handling (synchronous)

The download API is called with the HTTP method GET and the option format=XLSX to export the model Datatypes synchronously. Using the option -o, the response is stored in the file Datatypes.xlsx.

curl -X GET -u jdoe:s3cr3t -o Datatypes.xlsx "https://www.myserver.com/api/test/schemes/Datatypes/download?format=XLSX"

GET /api/test/schemes/Datatypes/download?format=XLSX HTTP/1.1
Host: www.myserver.com

The request performs the complete download and responds with the exported metadata:

HTTP/1.1 200
Content-Type: application/x-xls
Content-Disposition: filename="Datatypes.xlsx"

In case of an error (HTTP status code: 400), the HTTP response contains an error message:

HTTP/1.1 400
Content-Type: application/json

{
  "message": "The generated Microsoft Excel file contains too many rows (max. 65,536). Please enter filter criteria or choose a different export format!"
}

Download API (asynchronous)

The download API can be called with the HTTP method POST and the option format to export metadata asynchronously.

curl -X POST -u <user>:<password> "https://www.myserver.com/api/test/schemes/MyModel/download?format=<format>"

The download API can be called with the HTTP method POST and the option xsl to generate a report asynchronously.

curl -X POST -u <user>:<password> "https://www.myserver.com/api/test/schemes/MyModel/download?xsl=<report>"

The request starts a job and returns the corresponding job ID. The job runs in the background and performs the download. The status of the job can be polled with the job ID. When the job has completed, the exported metadata can be downloaded and the statistics and any existing logs can be queried.

Note

For binary formats (.xlsx, .zip, .pdf), it is recommended to store the response in a file using the option -o, rather than output to the console.

Example: Export metadata or generate report (asynchronous)

curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=XLSX"
curl -X POST -u jdoe:s3cr3t -H "Accept-Language: en" "https://www.myserver.com/api/test/schemes/MyModel/download?format=XLSX"
curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=CSV"
curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=XML"
curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=JSON"
curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=SQL&targetDatabase=PostgreSQL"

curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?xsl=Metadata_pdf.xsl"
curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?xsl=ReferenceValues_csv.xsl"

Example: Request and error handling (asynchronous)

The download API is called with the HTTP method POST and the option format=XLSX to export the model Datatypes asynchronously.

curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/Datatypes/download?format=XLSX"

POST /api/test/schemes/Datatypes/download?format=XLSX HTTP/1.1
Host: www.myserver.com

The request starts a job and responds with the job ID:

HTTP/1.1 200
Content-Type: application/json

{ "id":"e5b5138c-748f-42ec-a1de-26aef7cf835c" }

The status of the job can be polled with the job ID:

curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/statistics"

GET /api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/statistics HTTP/1.1
Host: www.myserver.com

When the job has completed (HTTP status code: 200), the HTTP response contains the job status COMPLETED and the statistics:

HTTP/1.1 200
Content-Type: application/json

{
  "messages": [
    {
      "level": "INFO",
      "message": "*Create Datatypes.xlsx* successful (00:00:00)."
    },
    {
      "level": "INFO",
      "message": "10 rows exported."
    }
  ],
  "status": "COMPLETED"
}

In case of an error, the HTTP response contains the job status FAILED and the statistics:

HTTP/1.1 200
Content-Type: application/json

{
  "messages": [
    {
      "level": "ERROR",
      "message": "*Create Datatypes.xlsx* failed (00:00:02)!"
    },
    {
      "level": "ERROR",
      "message": "1 *error* occured!"
    }
  ],
  "status": "FAILED"
}

The exact cause of the error can be found in the logs:

curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/logs"

GET /api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/logs HTTP/1.1
Host: www.myserver.com

HTTP/1.1 200
Content-Type: application/json

{
  "totalCount": 1,
  "data": [
    {
      "level": "ERROR",
      "message": "The generated Microsoft Excel file contains too many rows (max. 65,536). Please enter filter criteria or choose a different export format!"
    }
  ]
}

When the job has completed successfully, the exported metadata can be downloaded. Using the option -o, the response is stored in the file Datatypes.xlsx.

curl -X GET -u jdoe:s3cr3t -o "Datatypes.xlsx" "https://www.myserver.com/api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/download"

GET /api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/download HTTP/1.1
Host: www.myserver.com

HTTP/1.1 200
Content-Type: application/x-xls
Content-Disposition: filename="Datatypes.xlsx"

Metamodel​

Models​

Upload API​

Functionality​

Add or update only (ADD)​

Reconcile elements (REPLACE)​

Reconcile model (FULL_LOAD)​

Options​

gzip​

Option v​

Option format​

Option operation​

Option onInsert​

Option onUpdate​

Option onDelete​

Option dryRun​

Option agentId​

Option agentName​

Option ignoreUnknownAnnotations​

Language​

HTTP methods​

Usage​

Upload API (synchronous)​

Example: Import metadata (synchronous)​

Example: Request and error handling (synchronous)​

Upload API (asynchronous)​

Example: Import metadata (asynchronous)​

Example: Request and error handling (asynchronous)​

Download API​

Functionality​

Options​

Option format​

Option xsl​

Option v​

Option targetDatabase​

Option language​

Option publicOnly​

Option version​

HTTP methods​

Usage​

Download API (synchronous)​

Example: Export metadata or generate report (synchronous)​

Example: Request and error handling (synchronous)​

Download API (asynchronous)​

Example: Export metadata or generate report (asynchronous)​

Example: Request and error handling (asynchronous)​

Metamodel

Models

Upload API

Functionality

`Add or update only` (`ADD`)

`Reconcile elements` (`REPLACE`)

`Reconcile model` (`FULL_LOAD`)

Options

gzip

Option `v`

Option `format`

Option `operation`

Option `onInsert`

Option `onUpdate`

Option `onDelete`

Option `dryRun`

Option `agentId`

Option `agentName`

Option `ignoreUnknownAnnotations`

Language

HTTP methods

Usage

Upload API (synchronous)

Example: Import metadata (synchronous)

Example: Request and error handling (synchronous)

Upload API (asynchronous)

Example: Import metadata (asynchronous)

Example: Request and error handling (asynchronous)

Download API

Functionality

Options

Option `format`

Option `xsl`

Option `v`

Option `targetDatabase`

Option `language`

Option `publicOnly`

Option `version`

HTTP methods

Usage

Download API (synchronous)

Example: Export metadata or generate report (synchronous)

Example: Request and error handling (synchronous)

Download API (asynchronous)

Example: Export metadata or generate report (asynchronous)

Example: Request and error handling (asynchronous)