Export entities

Use the Export Entities API to export entities.

This API filters and exports all business objects, uploads a CSV file or JSON file to the storage, and sends a link to the exported data (if post processing is enabled and the partSize parameter wasn’t specified) or a link to the Export Console UI page (in the opposite cases). All the attributes of the entities are exported including the hidden attributes.

By default, all attributes of entities are exported including the hidden attributes.

Note: Details about AWS S3, Google Cloud Services (GCS), or an Azure Blob Storage destination file for export are explained. For more information, see Storing Export Results.

Request

Standard endpoint:

POST {ExportServiceURL}/export/{{tenant}}/entities

See Table 1: Parameters to find out the list of parameters.

Table 1. Parameters
Parameters Name Required Details
Headers Authorization Yes Information about authentication access token in the format of Bearer accessToken (see details in Authentication API ).
Content-Type Yes Must be Content-Type:application/json.
Custom S3/GCS/Azure Destination No A custom S3/GCS/Azure destination, where export results must be saved. For more information, see Store export results.
Body   No JSON object including parameters for filtering the exported entities.
Query dateFormat No This parameter denotes the format of date and time attribute values (CSV and JSON export formats support this parameter). The possible values are timestamp and readable. The default value is timestamp.
fileFormat No The possible values are csv and json. This parameter defines what output format must be used for export. The default value is csv. Export to json is more efficient compared to export to csv.
distributed No This parameter is applied only for Export Version 1. If set to be true, then the export task is divided based on parts. Parts execute in parallel on different nodes. If not specified, one task is created.
taskPartsCount No This parameter is applied only for Export Version 1 and denotes the number of distributed task parts. If not specified, auto-calculated distributed settings are used.
partSize No This parameter indicates human readable part size and is applied only when skipPostprocessing=false. The service splits the result files depending on this setting. For more information, see Export Data into Multiple Files.
skipPostprocessing No During data extraction, the Export Service generates many small partial files of the export results. If this parameter is enabled, then the Export Service returns links to these files as results and the partSize parameter is ignored. Otherwise, the Export Service combines the partial files into one or several files depending on the partSize parameter and returns the links to the combined files as results. The default value is false for Export Version 1 and true for Export Version 2.
name No This parameter indicates the name of the export task displayed in the task status. The name is also used by the Export UI. For more information, see Naming an Export Job.
email No This parameter indicates the comma-separated list of custom email addresses to which the notification is sent after the export is completed. If the parameter isn’t specified, the Export Service notifies the Reltio user who submitted the export request.
select No This parameter accepts a list of entity fields to be exported. If not specified, then all fields are present in export. For example, select=type,attributes.FirstName,attributes.Address.City,createdTime.
filter No This parameter enables you to filter entities by a condition. Format for filter query parameter: filter=({Condition Type}[AND/OR {Condition Type}]*). For more information, see Filtering Entities.
options No This is a comma-separated list of different options. The available options are as follows:
  • searchByOv: This option is disabled by default and is used to search only by attributes with ov=true.
activeness No This parameter determines how the Export Service must process the active and expired objects. The possible values are as follows:
  • ALL: This option enables the exporting of active and expired objects. This is the default value.
  • ACTIVE: This option only enables the exporting of active objects.
  • NOT_ACTIVE: This option only enables the exporting of expired objects.
exploded No This parameter is only applicable for CSV export. If the parameter equals true, then all attribute values for the same attribute must be within one column (more than one row for one entity). In other words, if the parameter equals to true, then each entity is shown as a set of CSV lines, where the set is a cartesian product of the entity's attributes. There’s a restriction to explode up to 100K rows per one entity. The default value is false.

For more information, see Exploded format in CSV entities export.

headersStyle No This parameter defines how the Export Service must name the CSV columns for the attribute values. This parameter is only applicable for CSV export. The possible values are as follows:
  • name - Attribute names are used for CSV column names.
  • label - Attribute labels are used for CSV column names.

The default value is name.

For more information, see The Headers Style Query Parameter in CSV Entities or Relations Export File

Custom S3/GCS/Azure Destination No A custom S3/GCS/Azure destination, where export results must be saved. For more information, see Store export results.
filenameTemplate No This parameter enables you to specify a file name template, which generates resultant output file names when the configured exported version is V2. For more information, see Naming Output Files.
sendHidden No This parameter enables you to include or exclude hidden attributes to the exported result. By default, the value of the parameter is set to be True. If the value of the parameter is set to be False, the export file won't include hidden attributes of entities. For more information, see Generate pivoted view of crosswalks.
anchorAttribute No

This parameter is only applicable for CSV export.

The parameter specifies an anchor attribute, and precedes all the other attributes. Only a single OV value for that attribute will be present on a CSV line for an entity. If it's used with slicedByCrosswalks, the value is put on each CSV line no matter which crosswalk that value belongs to. This option is not affected by the select parameter. For more information, see topic Generate pivoted view of crosswalks.
slicedByCrosswalks No

This parameter is only applicable for CSV export.

If the value of the parameter is set to be true, the objects are sliced by crosswalks. Each set of attribute values are placed on a separate CSV line that represents a crosswalk these attributes belong to. You can’t use the option with the exploded option. For more information, see topic Generate pivoted view of crosswalks.

See Table 2: Body Parameters to find the parameter and the corresponding values and value types.

Table 2. Body parameters
Parameter Required Value Value type
ovOnly No The possible values are true or false. If not specified or the value is true, then only ov=true attributes are exported. Boolean
includeType No This parameter indicates a JSON array of entity types. If specified, only entities that belong to the specified types or extend those types are exported. JSON array
updateTimeFilter No This parameter indicates a JSON object with an update time range. The format is "updateTimeFilter": {"since": 1394726957000, "to" : 1394726959000}. Either only one constraint is enabled or both of them are enabled. JSON object
groupBy No This parameter indicates a list of Attribute Group Specifications that enable grouping of Complex Attributes. It’s only applicable for a CSV export. To know more about grouping nested and reference attributes (complex attributes) by one or several of the subattributes, see Group Nested and Reference Attributes. JSON object
headerFormat No This parameter specifies how the Export Service must name the CSV header columns and is only applicable for CSV export. The possible values are:
  • DEFAULT
  • CONSISTENT
For more information, see Parameters for CSV Headers in the Entities or Relations Export File
String
filter No This parameter enables you to filter entities by a condition.

The format for filter parameter is: filter=({Condition Type}[AND/OR {Condition Type}]*). For more information, see Filtering Entities.

Note: The query filter parameter has priority and overrides the body filter parameter.
String
sliceFilter No This parameter is only applicable for CSV export format. You can use the parameter in combination with the slicedByCrosswalks query parameter. This parameter provides an ability to filter the individual slices generated by the slicedByCrosswalks parameter.

The sourceSystems property is available for filtering by source type in sliceFilter parameter.

The structure of sliceFilter parameter is the same as for regular filter parameter.

For more information, see topic Generate pivoted view of crosswalks.

Example:

not equals(sourceSystems, 'ReltioCleanser')
String

Group nested and reference attributes by anchor attributes

Grouping of Complex Attributes enables you to group nested and reference attributes (complex attributes) by one or several of the subattributes (called anchor attributes). For more information, see Group Nested and Reference Attributes.

Result of an export request

The response format is always a JSON object showing the result of the export operation. For more information, see Result of an Export Request.

Example

Request

Request filtered to export entities updated since 1394726957000 and with type that extends HCP or Location.

POST {ExportServiceURL}/export/{{tenant}}/entities
Headers
Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512
Content-Type: application/json
Body
{
  "ovOnly" : true,
    "updateTimeFilter": {
        "since": 1394726957000
    },
    "includeType": [
        "configuration/entityTypes/HCP",
        "configuration/entityTypes/Location"
    ]
}
Response
{
    "exportType": "ENTITIES",
    "version": "v2",
    "status": "scheduled",
    "details": "Export job has been scheduled. Result will be sent to your email: user@example.com",
    "taskIds": [
        "831272d6-1685-49cc-a98c-c8965d04bc0d"
    ]
}