Upload Entities

Python script for the uploading of a list of entities to the Riffyn Library using the API.  Entities can be of any of the following Riffyn types (resources, resource types, properties types, or units), but each type of entity list must be uploaded separately.

Description

This script takes an Excel or CSV file as input (format & examples defined below), parses the data in the file, and assigns the authenticated user as the owner of the entities.

Entities supported for upload:

  • Resource types
  • Resources
  • Property Types
  • Units

Excel columns are order-sensitive. Specific header keywords are required for the first column. Labels are case-sensitive.

 

Prerequisites

  • .csv or .xlsx file located in a folder named 'csv'
  • Python package from the Riffyn SDK
  • Login credentials for authenticated user

 

Setup

  1. Install the python package from the Riffyn SDK
  2. Install via Setuptools.
  3. Run this command in the command line at the root of your folder:
    python setup.py install --user (or sudo python setup.py install to install the package for all users)

 

Configuration

The script should be updated before use to point to the API service of your Riffyn instance.

At the top of the UploadEntities.py file, set the 'host' variable to the address of your library (host="https://api.riffyn.com"). If you use Riffyn's multi-tenant cloud the service is: api.riffyn.com.

If your company has it's own VPC it will be in the format: api.yourcompany.riffyn.com

 

Format for .xlsx & .csv Files

The columns must be in a specific order for the script to parse the data correctly.

Column 1 must have a header name of the entity being added to the library (‘Resource Name’, ‘Unit Name’, ‘Resource Type Name’, or ‘Property Type Name’). These headers are case-sensitive. Please refer to the charts for exact name and format. The filename of the .xlsx or .csv file cannot contain spaces.

1) Resource Types File

In the Resource Types file, the first column header must be named 'Resource Type Name' and the values listed underneath should contain the name of the new Resource Type to be added. Each resource type to be added also requires a parent name to be specified (which is also a resource type name). The script will look for the parent information in the column following 'Resource Type Name'. The parent must already exist in the Riffyn library in order to upload the new Resource Type. Note the parent itself can also be uploaded in the same file, provided it is uploaded before the child Resource Type (i.e., it is listed in a row above the child row in the file).

File Format: - see example ResourceTypes.xlsx at the bottom of this article.

Resource Type Name

Resource Type Name of Parent

Name of 1st new Resource Type

Name of the parent Resource Type for the 1st new Resource Type

Name of 2nd new Resource Type

Name of the parent Resource Type for the 2nd new Resource Type

 

2) Resources File

In the Resources file, the first column header must be named 'Resource Name' and the values listed underneath should contain the name of the new Resources to be added. Each resource to be added also requires an ID of the Resource Type to be specified (which is also a resource type name). The script will look for the Resource Type ID in the column following 'Resource Name'.

File Format: - see example Resources.xlsx at the bottom of this article.

Resource Name

ResourceTypeId

Name of 1st new Resource

ID of the Resource Type for the 1st new resource

Name of 2nd new Resource

ID of the Resource Type for the 2nd new resource

  

3) Property Type File

In the Property Type file, the first column header must be named 'Property Type Name' and the values listed underneath should contain the name of the new Property Type to be added. Each Property Type to be added also requires information detailing:

  • Units (header "hasUnits") - if the property has units, with values of "true" or "false".
  • Fixed (header "immutable") - if the property is fixed or variable, with values of "true" or "false".
  • Type (header "valueType") - type of values the property will hold, with values of "float", "integer",  "image", "character" or  "datetime"

File Format: - see example PropertyTypes.xlsx at the bottom of this article.

Property Type Name

hasUnits

immutable

valueType

Name of 1st new Property Type

true / false

true / false

float / integer / image / character / datetime

Name of 2nd new Property Type

true / false

true / false

float / integer / image / character / datetime

 

4) Units File

In the Units file, the first column header must be named 'Unit Name' and the values listed underneath should contain the name of the new Unit to be added. Each Unit to be added also requires a description.

File Format: - see example Units.xlsx at the bottom of this article. 

Unit Name

Unit Description

Name of 1st new unit

Description of 1st new unit

Name of 2nd new unit

Description of 2nd new unit

 

Running the script 

In the command line run:

python uploader.py name_of_file.xlsx

The script will prompt to enter login credentials for Riffyn.

The credentials will be masked when typed.

  • username: name@domain.com
  • password: your password

The script will indicate if the login has been successful before proceeding.

 

Script Functionality Details

Once the script starts executing, it will extract the information from each row of the Excel file and print the data to the terminal to allow the data to be reviewed.

Simultaneously, it will query to the library to see if any of the entities already exist in the library. If any pre-existing entities are found, an alert will occur.

The script will also generate a new file containing only the entities that are missing from the library. The generated file will be named "not_in_database.csv" and will be located in the csv folder.

This file can subsequently be used to upload only the missing entities.

A prompt will occur to allow execution to continue or abort. If aborted, the upload can be restarted (possibly using the generated file "not_in_database.csv"). If continue, the script will ignore pre-existing entities and upload all the data in the file, thus creating duplicates.

If uploading is successful, it will print the IDs of the added entity in the terminal for lookup using the Riffyn user interface.

If there is a failure, it will provide a log of the errors in the script output.

 

Expected Results

The script will add each entity to the library with its associated attributes. In the terminal it will print the name of the entity as it is uploaded with the associated attributes and the generated database id.

If you need assistance please contact Riffyn at support@riffyn.com.

 

Script Logic Overview

  • login
  • convert xlsx to csv file conversion
  • read file
  • check for existing entities in the database
  • Prompt the user to choose whether to continue with upload of all the data or to upload only the missing entities
  • upload of resources types to the database (some resource types may be necessary to upload the coming resources)
  • upload of resources
  • upload of units
  • upload of property types
  • feedback on upload

 

Downloads

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request