Loome Docs > Loome Portal > Developers > Custom Apps > Upload Assets, Entity Types and Attributes

Upload Assets, Entity Types and Attributes

Overview: Bulk Upload Operations: Assets, Entity Types and Attributes

The Bulk Upload Operations folder contains a comprehensive workflow for programmatically managing custom applications and their assets in Loome Portal. This workflow enables you to define data structures, configure entity types, and bulk upload assets through a structured, sequential process.

Use this workflow when you need to:

Programmatically create or update multiple assets in Loome Portal
Synchronize external data sources with Loome Portal
Automate the management of custom applications and their metadata
Perform bulk operations on Loome Portal assets while maintaining data integrity

This folder implements a sequential 5-step workflow with an optional cancellation endpoint. The requests are designed to be executed in order, as each step builds upon the previous one.

Prerequisites

Before using this workflow, ensure you have:

Authentication: Valid API credentials with appropriate permissions for the Loome Portal API
Portal URL: The base URL of your Loome Portal instance (set as {{PortalUrl}} variable)
Custom App ID: The identifier for your custom application (set as {{CustomAppId}} variable)
Execution ID: Generated during the staging process (set as {{ExecutionId}} variable)
Keep Orphans Setting: Decision on whether to retain assets not present in the staged data (set as {{keepOrphans}} variable - true or false)

Recommended Environment Variables

Set up the following variables in your Postman environment:

PortalUrl - Your Loome Portal base URL
CustomAppId - Your custom application identifier
ExecutionId - Populated automatically during the staging process
keepOrphans - Boolean flag for commit behavior (true or false)

Sequential Workflow Steps

Step 1: Ensure Attributes

Purpose: Define or update the metadata attributes that will be associated with your assets. This step creates the schema for your custom application by defining attributes such as compliance levels, categories, or any custom metadata fields. Attributes can be of various types (List, Boolean, Number, Date, Text, etc.) and can be marked as required.

When to use: Execute this first to establish the attribute schema before defining entity types.

Step 2: Ensure Entity Types

Purpose: Configure the types of entities (assets) that your custom application will manage. Entity types define the structure, appearance, and behavior of your assets in Loome Portal. This includes setting the category, subcategory, icon, available actions, and embedding parameters. The source field is automatically inferred from the custom app’s name. This process is also used to “link” entity types to attributes.

When to use: Execute after ensuring attributes to define what types of assets your application will manage.

Step 3: Stage Assets

Purpose: Upload and prepare your assets for commit without immediately affecting the live Loome Portal data. The staging process allows you to upload multiple assets with their metadata, attributes, actions, and tags. Assets are identified by a unique sourceItemId. This step creates an execution context and returns an ExecutionId that must be used in subsequent steps.

Key behavior: - Assets are held in a staging area and not immediately visible in the Loome Portal - An ExecutionId is generated and should be captured for the next steps - The staging operation is asynchronous and may take time for large datasets

When to use: After defining your schema (attributes and entity types), use this to upload your asset data.

Step 4: Commit Staged Assets

Purpose: Finalize the staged assets and make them live in Loome Portal. This step processes all staged assets and applies them to the Loome Portal. The keepOrphans parameter controls how assets not present in the staged data are handled: - keepOrphans=true: Retains existing assets not in the staged data - keepOrphans=false: Removes existing assets not in the staged data (use with caution)

Key behavior: - Returns a 202 Accepted status with “Commit operation queued” message - The operation is asynchronous and queued for processing - A Location header is provided in the response for status polling

When to use: After successfully staging your assets and verifying the data is correct.

Step 5: Get Execution Status

Purpose: Monitor the progress and completion status of your staging or commit operation. Use this endpoint to poll the status of your execution. The response includes the current status (running, completed, failed) and any error messages if the operation failed or was cancelled.

Key behavior: - Poll this endpoint periodically to check operation progress - Error messages are only populated when status is ‘Failure’ or ‘Cancelled’ - Useful for monitoring long-running operations

When to use: After committing staged assets to monitor the operation until completion.

(Optional) Cancel Execution

Purpose: Abort an in-progress staging or commit operation. If you need to stop an operation before it completes, use this endpoint to cancel the execution identified by the ExecutionId.

Key behavior: - Returns 204 No Content on successful cancellation - Only works on operations that are still in progress - Cannot be undone once executed - Loome will automatically cancel any staging operation that has passed the 24 hour mark, and you will need to start over.

When to use: Only when you need to abort an operation due to errors or incorrect data and you wish to start over.

Best Practices

Execution Order
- Always follow the numbered sequence (1 → 2 → 3 → 4 → 5). You can optionally skip steps 1 and 2, granted that the attributes and entity types that you will be utilizing is already defined in the system.
Data Validation
- Validate your attribute and entity type definitions before staging assets
- Ensure sourceItemId values are unique across all assets
- Verify attribute values match the defined attribute types and options
- Test with a small dataset before performing large bulk uploads
Error Handling
- Always check the execution status after committing
- Implement retry logic for transient failures
- Capture and log error messages from the status endpoint
- Use the cancel endpoint if you detect issues during execution
Performance Considerations
- For large datasets, expect longer processing times during staging and commit
- Poll the status endpoint at reasonable intervals (e.g., every 5-10 seconds)
- Consider breaking very large uploads into smaller batches
‘Keep Orphans’ Decision
- Carefully consider the keepOrphans parameter:
- Use true for incremental updates where you want to preserve existing assets
- Use false only when you want a complete replacement of all assets (destructive operation)
- Test with keepOrphans=true first to avoid accidental data loss

Common Use Cases

Initial Bulk Import: Set up attributes and entity types, then stage and commit all assets
Incremental Updates: Stage only changed assets with keepOrphans=true
Full Synchronization: Stage all current assets with keepOrphans=false to mirror an external system
Schema Updates: Update attributes or entity types, then re-stage affected assets

Troubleshooting

Operation Stuck or Taking Too Long
- Check the execution status endpoint for error messages
- Consider cancelling and retrying with a smaller dataset
- Verify network connectivity and API availability
Commit Failures
- Review error messages from the status endpoint
- Verify all required attributes are provided
- Check that attribute values match defined options for List-type attributes
- Ensure sourceItemId values are unique
Missing Assets After Commit
- Verify keepOrphans was set correctly
- Check that assets were successfully staged before committing
- Review execution status for any error messages

Attributes

The first step is to ensure your attributes.

You can add or update attributes using this endpoint. (Learn how to view existing attributes via the API here.)

Please note that the request must be authenticated and authorized to access this endpoint. You can use this endpoint when you need to modify existing attributes rather than creating new ones.

To add an attribute, you will need to provide the following request parameters in the request body in JSON format:

name (string): The name of the attribute you want to update. This is a required field.
description (string): The description of the attribute.
$type (string): The type of the attribute. This is a required field. Valid values you can choose from are:
- List
- Boolean
- Number
- Date
- Person
- Decimal
- Email
- Group
- Notes
- Text
- URL
isRequired (boolean): A flag indicating whether this attribute is mandatory.
- Set this to true if the attribute is required. Validation on the staging/commit process will trigger if this is true and nothing is set on the asset.
- Set it to false for this attribute to be optional for assets.
options (array): An array of options for a list attribute. Each option should be an object containing:
- name (string): The name of the option.
- style (string): (Optional) The style of the icon.
- color (string): (Optional) The color of the icon.
- children (array): (Optional) An array of child options, if any exist.

For example:

[
  {
    "name": "Compliance Level",
    "$type": "List",
    "isRequired": true,
    "options": [
      {
        "name": "Public"
      }
    ]
  }
]

Ensure attribute

Entity Types

Next, ensure entity types. (You can learn how to view existing entity types via the API here.)

This endpoint allows users to update the entity types associated with a specific custom application identified by CustomAppId. The request expects a JSON payload that defines the properties of the entity type being updated. The Source field of an entity type is automatically inferred from the Custom App’s name.

You can define or update entity types for a custom app by specifying the required fields for request body parameters. The request body should be a JSON array containing objects with the following structure:

type (string): Specifies the type of the entity, e.g., “Custom Dataset”.
category (string): The category under which the entity falls, e.g., “Content”.
subCategory (string): Further classification of the entity, e.g., “Visualisation”.
icon: The fontawesome icon that represents the entity type, this will be displayed throughout Loome Portal where applicable.
- name: The icon from font awesome (Optional)
  - default: fa-database
- style: The style of the icon from font awesome (i.e fa-light, fa-solid) (Optional)
  - default: fa-light
- color: The color of the icon in hex format. (Optional)
  - default: #356769
attributes (array): An array of attributes associated with the entity. This can be empty if no attributes are defined. (This can be an attribute created in this custom app or an existing attribute in Loome.)
actions (array): An array of actions that can be performed on the entity. For example, custom actions with descriptions such as, “View Report”, “View Dataset”. Each action object includes:
- name (string): The name of the action, e.g., “View Dataset”.
- description (string): A brief description of the action.
embeddingUrl (string): (Optional) A URL that provides access to the embedded content.
embeddingParams (array): (Optional) An array of parameters for embedding, where each parameter includes:
- id (string): The identifier for the parameter, e.g., “DatasetId”.
- name (string): The name of the parameter, e.g., “Dataset Id”.
- description (string): A description of the parameter.
- type (string): The data type of the parameter, e.g., “text”.

Please note that the embeddingUrl must be a valid URL pointing to the embedded content. The actions array can contain multiple actions, each with its own name and description.

Ensure entity types

Stage Assets

Stage assets that will be linked to your custom app.

You can stage multiple assets in one operation by providing the following parameters. The request body must be a JSON array containing objects with the following parameters:

name (string): The name of the asset.
group (string): A field to group assets by. (e.g., “IT Governance”).
entityTypeId (integer): The ID representing the type of entity (e.g., 41).
sourceItemId (string): A unique identifier for the source item (e.g., “2025-tech-spend-report-it”). This field should be unique.
actions (array of objects): A list of actions associated with the application. The name of each action should correspond to an action on the entity type. Each action object contains:
- name (string): The name of the action (e.g., “View Report”).
- value (string): The URL or value associated with the action (e.g., “https://your-app.com/reports/v...").
attributes (array of objects): A list of attributes related to the application. Each attribute object contains:
- name (string): The name of the attribute. This field should match the attribute name.
- values (string[], string, int, boolean): The values for the attribute.
  - When providing values for a List, those values should match the options on the attribute.
  - When providing values for a primitive type (i.e String, Number, Boolean), please still use the values property key and the raw value of the attribute.
tags (array of strings): Tags to help organize your assets. Add a new tag or provide a matching value of an existing tag in Loome.

The staging operation will return an execution ID to track the asset(s) when the request has completed successfully. The server will respond with a status code of 200 OK indicating that the request has been successfully processed. The response will be in JSON format and will contain the following fields:

executionId (integer): An identifier for the execution instance (e.g., 1).
status (string): The current status of the execution (may be empty).

Example:

[
    {
        "name": "2025 Sample Report",
        "group": "IT Governance",
        "entityTypeId": <Entity Type Id From EnsureEntityType call>,
        "sourceItemId": "2025-sample-id",
        "actions": [
            {
                "name": "View Report",
                "value": "https://your-app.com/reports/view/2025"
            }
        ],
        "attributes": [
            { "name": "Rating", "values": ["Gold", "Silver"]}
        ],
        "tags": [
            "Annual Report",
            "Sample",
            "2025"
        ]
    }
]

Stage assets

The staged assets are held in a temporary state and will not yet be visible to end users.

Commit Staged Assets

Next, commit the assets staged using the execution ID from the staging operation returned above. This endpoint allows users to commit all assets that are currently staged by calling the staging endpoint by CustomAppId.

The keepOrphans parameter is required and determines how the commit operates.

Specify whether to keep or remove orphaned assets (assets not in the current staged batch):

If True , all assets not present on the staged table but are present in Loome Portal will be retained.
If False , all assets not present on the staged table but are present in Loome Portal will be deleted from Loome Portal. Use false only when you want a complete replacement of all assets (destructive operation).

After it has completed successfully, the server will respond with a status code of ‘202 Accepted’ indicating that the request has been accepted and queued for processing.

A successful response will contain a string with the following text: “Commit operation queued.”

There will also be Location on the Response Headers. This URL should be used to poll for the status of the staging operation.
When the Status is Failure or Cancelled, the response will include error messages specifying what went wrong with the operation.

Commit staged assets

Please note that:

A single request cannot stage more than 5,000 items.
The total number of staged assets cannot exceed 50,000 items.
At 50,000 staged assets, commit that operation of staged assets before then staging additional assets.

Get the Execution Status

Next, get the execution status of these staged assets.

This endpoint retrieves the current status of a specific execution identified by the ExecutionId. This will display the execution status from staging through to commit completion, and can be used to monitor long-running executions.

You will need to provide the request parameter: - ExecutionId (path parameter): The unique identifier for the execution whose status you want to retrieve. This should be a valid ID corresponding to an existing execution.

It will poll the execution status using the execution ID to track the progress of the execution, such as running, completed, failed, or cancelled.

If the operation fails or is cancelled, an error message will display the issue in errorMessages.

Get execution status

Cancel an Execution

You can cancel an execution of an in-progress staging or commit operation by using the execution ID in the Cancel Execution endpoint.

Cancel a specific execution of a custom application identified by the ExecutionId.

Provide the request parameter - ExecutionId (path parameter): The unique identifier of the custom app execution that you wish to cancel.

Cancel execution

Upon a successful cancellation, the API will return a ‘204 No Content’.

Cancelled operations do not affect live assets in the Loome Portal.