DataLab actions


A DataLab action is a server side job that runs against every Entity a DataLab selection finds. It lets you change, relate, export or delete records in bulk without paging through them yourself.

People configure actions on saved queries in Operator and run them from there. Every action starts a Pending Action, which reports progress and, for exports, the file to download.

This article will cover how to run an action and the settings of each action type. You can read about selections in DataLab queries, and about the actions that compare two selections in DataLab secondary queries.

Running an action

Send a "PrimarySelection" and an "Action", or the whole request as "UserSQL" text. To run several actions one after another under one Pending Action, send them as a list under "Actions". Check what an action will change by running its selection first.

Run a DataLab action

Request body
interface IPostBody {
    // The Entities to act on.
    "PrimarySelection"?: ISelection;
    // A second selection, for the actions that relate two sets of Entities.
    "SecondarySelection"?: ISelection;
    // The action to run. See the sections below.
    "Action"?: IAction;
    // The same request written as DataLab User SQL: an UPDATE, DELETE, INSERT, MERGE or COPY.
    // Send this or the JSON, not both.
    "UserSQL"?: string;
    // Several requests, each with its own PrimarySelection and Action, run in order.
    // Used instead of the fields above.
    "Actions"?: {
        "PrimarySelection": ISelection;
        "SecondarySelection"?: ISelection;
        "Action": IAction;
    }[];
}

interface IAction {
    // Decides the other settings the action reads.
    "ActionType": string;
}
Response
// The response is the Pending Action record that tracks the job.
// See the Pending Action page for the record structure.
Javascript example

A request without a selection, without an action, or with an unknown or incomplete action fails straight away with a 400. Problems found while the job runs are reported on the Pending Action instead. Only "set-attribute", "relationship-map", "relationships-remove", "merge" and "save-secondary-items-count" take a secondary selection; the other actions fail when one is sent. You can read about following a Pending Action in Pending Actions.

Exports finish with a file. For CSV, XLSX and NSX the Pending Action's "Result" is the file's name. For JSON it is a JSON string holding "TempFile.ID", "FileName" and a download "URL". Download the file from the route below.

Download an exported file

Response
// The response is the file itself.
Javascript example

Action: Set attribute

Writes one or more attribute values on every found Entity. Values are parsed by "AttributeType" before they are written, and a blank value clears the attribute. This page covers fixed values; copying values between two selections is on the secondary queries page.

interface ISetAttributeAction {
    "ActionType": "set-attribute";
    // Attribute path segments are separated by a forward slash. Eg: '"address"/"city"'.
    "Path": string;
    // How Value is parsed. "string", "structure" and "geometry" are written as given.
    "AttributeType": "string" | "integer" | "double" | "datetime" | "structure" | "geometry";
    // CONST and USER write Value as it is.
    // Default is CONST.
    "ValueOption"?: "CONST" | "USER";
    // Required. A blank value clears the attribute.
    "Value": string;

    // Writes several attributes in one pass, instead of the single Path, AttributeType, ValueOption and Value above.
    // Each entry carries its own. An empty list is refused.
    "Attributes"?: {
        "Path": string;
        "AttributeType": string;
        "ValueOption"?: string;
        "Value": any;
    }[];
}
{
    "ActionType": "set-attribute",
    "Attributes": [
        { "Path": "\"status\"", "AttributeType": "string", "Value": "Active" },
        { "Path": "\"workflow\"/\"stage\"", "AttributeType": "integer", "Value": "2" }
    ]
}

Action: Tags

Adds, removes or replaces the Tags on every found Entity. Name Tags by ID, by name, or either; a name stands for every Tag carrying it, ignoring case. "set" with no Tags clears them. You can read about Tags in Tags.

interface ITagsAction {
    "ActionType": "layer";
    "Layer": {
        // Required.
        "Operator": "add" | "remove" | "set";
        // Tag IDs. "Layer.ID" is read the same way.
        "OperandA"?: number[];
        // Tag names.
        "Layer.Name"?: string[];
        // IDs or names. A whole number is read as an ID.
        "Layer"?: (number | string)[];
    };
}

Action: Tag mapping

Applies a saved Tag Mapping, which gives each Entity the Tag mapped to its attribute value. Tag Mappings are listed by "GET layerMappings".

interface ITagMappingAction {
    "ActionType": "layer-map";
    // ID of the Tag Mapping.
    "LayerMappingID"?: number;
    // Or its ID or name.
    "LayerMapping"?: string | number;
}

Action: Attach a file

Attaches an existing file to every found Entity. The file is not copied, and an Entity that already has the file under the same Attachment Type has its group updated. You can read about attachments in Entity attachments.

interface IAttachAction {
    // "attach-client-file" and "attach-file" also work.
    "ActionType": "attachclientfile";
    "AttachClientFile": {
        // Required. ID of the file to attach.
        "ClientFile.ID": string;
        // Required unless AttachmentType is given.
        "AttachmentType.ID"?: string;
        // Attachment Type ID or name.
        "AttachmentType"?: string;
        // Optional group within the Attachment Type.
        "Group"?: string;
    };
}

Action: Data Transform

Runs a saved Data Transform over every found Entity. The mapping output is merged into each Entity, and the transform's "DestinationDataSchema" is added to the Data Schema of each Entity Type it changes. You can read about Data Transform records in Data Transforms.

interface IDataTransformAction {
    "ActionType": "data-transform";
    // ID of the Data Transform.
    "DataTransformID"?: number;
    // Or its ID or name.
    "DataTransform"?: string | number;
}

Action: Generate descriptions

Writes an AI generated description to "Bruce/Description" on every found Entity, replacing an earlier generated one. Descriptions come from the installation's vision service and read each Entity's attributes and best LOD thumbnail. It has no settings.

interface IGenDescriptionAction {
    "ActionType": "gen-description";
}

Action: Entity Type mapping

Moves the found Entities to other Entity Types. There are three ways to choose the new type, tried in this order: one target type for all, a new type per value of an attribute, or a list mapping attribute values to types. Each move can apply a Data Mapping, which you can read about in Data Mapping.

interface IEntityTypeMappingAction {
    // "entity-type-mapping" also works.
    "ActionType": "entitytype-mapping";
    "EntityTypeMapping": {
        // Required. The Entity Type the found Entities are moved from.
        "SourceEntityTypeID": string;

        // One target type for every Entity.
        "Target.EntityType.ID"?: string;
        "Target.EntityType.DataMapping"?: IDataMapping;

        // Or a type per value of this attribute, found by name or created beside the source type.
        "SortAttrPath"?: string;
        // Type name for Entities without the attribute.
        // Default is "ITEM".
        "DefaultAttrValue"?: string;

        // Or a list of values to types. Entities whose value is not listed stay where they are.
        "Source.Attribute.Path"?: string;
        "AttributesMapping"?: {
            "AttributeValue": string;
            // An existing type.
            "EntityTypeID"?: string;
            // Or a type to create with this name.
            "NewEntityTypeName"?: string;
            "DataMapping"?: IDataMapping;
            // Rebuilds the type's Data Schema from the moved Entities.
            "UpdateDataSchema"?: boolean;
        }[];
        // Parent of types created from NewEntityTypeName.
        // Default is the source type's parent.
        "Target.ParentEntityTypeID"?: string;

        // Rebuilds the target type's Data Schema, or the sorted types' schemas, from the moved Entities.
        // Default is false.
        "UpdateDataSchema"?: boolean;
    };
}

Action: Remove duplicates

Groups the found Entities by a key attribute, compared without regard to case, and keeps the first of each group. The others are merged into it and deleted. The job stops if more than 10 Entities share a key, since that suggests the key is not unique enough.

interface IDedupeAction {
    "ActionType": "dedupe";
    "Dedupe": {
        // Required. Attribute whose value identifies duplicates.
        "KeyAttributePath": string;
        // Orders each group so the first is kept.
        // Default is the Entity ID.
        "SortByAttributePath"?: string;
    };
}

Action: Delete Entities

Deletes every found Entity. Count the selection first.

interface IDeleteAction {
    "ActionType": "delete";
}

Action: Delete relations

Deletes the relations of one Relation Type where a found Entity is the Principal. With a secondary selection it deletes only the relations between each primary Entity and its secondary matches, as the secondary queries page describes. You can read about relations in Entity relations.

interface IRelationsRemoveAction {
    "ActionType": "relationships-remove";
    // Required.
    "RelationType.ID": string;
}

Action: Export CSV and XLSX

Writes the found Entities to a CSV or Excel file. Without "ColumnSettings", the columns are the ID and every typed attribute in the Data Schema of "EntityTypeID". Without "EntityTypeID", the schemas of the Entity Types in the first page of matches are merged.

interface IExportTableAction {
    "ActionType": "export-csv" | "export-xlsx";
    // Entity Type whose Data Schema shapes the columns.
    "EntityTypeID"?: string;
    // Related data to load before writing.
    // Comma separated. Eg: "Source,EntityType".
    "Expand"?: string;
    // Explicit columns, in output order.
    "ColumnSettings"?: {
        "Columns": {
            // Attribute path for the column's values. "Bruce/ID" gives the Entity ID.
            "AttributePath": string;
            // Header text.
            "ColumnTitle": string;
        }[];
    };
}

Action: Export JSON

Writes the found Entities, and the related records named in "Expand", to JSON files zipped together.

interface IExportJsonAction {
    "ActionType": "export-json";
    // Related records to include.
    // Comma separated. Eg: "EntityType,LOD,Source,Relation,Attachment".
    "Expand"?: string;
    // Scenario ID or key, to export that Scenario's version of each Entity.
    "Scenario"?: string | number;
}

Action: Export NSX

Writes the found Entities, and the records they depend on, to a Nextspace exchange file for moving records between accounts.

interface IExportNsxAction {
    "ActionType": "export-nsx";
    // Entity Type the file is named after.
    "EntityTypeID"?: string;
}