Skip to content
No description, website, or topics provided.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
csv
json
oman
scripts
.env
.gitignore
Pipfile
Pipfile.lock
README.md

README.md

bluecats-python-oman-cli

A BlueCats object management platform command line program for Loop in Python.

Table of Contents

Getting Started

This section will outline what to do after pulling the repo, before running any of the loop tools. See mman section for notes on how to use loop tools after installation.

Prerequisites

  • python (3.6)
  • pip (for python 3.6)
  • pipenv (for python 3.6)

To check the version of python or pip use the --version flag

python --version

If you have pip for 3.6 and python 3.6 installed, but --version is returning 2.7, then you also have version 2.7 of python/pip installed on your system. In this case you can use python3 and pip3 in place of python and pip for all commands.

python3 --version

To install pipenv after you have python and pip

pip install --user pipenv

On some systems, this may bomb due to permission errors. To grant administrator privileges and continue

sudo -H pip install --user pipenv

Installing

Navigate to the base directory and run the following

pipenv install --three

If hash issue are present, An error occurred while installing and --hash files show up, try running:

sudo pipenv install --three --skip-lock

Recommended: add this alias to your bashrc so that further commands can be shortened (the rest of this readme will assume you have defined this alias).

  1. Open your ~/.bash_profile file with your favorite terminal editor (i.e. nano ~/.bash_profile)

  2. Add this to pull in everything from your bashrc to your bash_profile.

    	if [ -f ~/.bashrc ]; then
    		source ~/.bashrc
    	fi
    
    
  3. Save

  4. Open your ~/.bashrc file with your favorite terminal editor (i.e. nano ~/.bashrc)

  5. Add a line with the alias (i.e. alias oman="pipenv run python3 ~/oman/oman.py"). Make sure you copy the entire path so you do not get path issues.

  6. Save the file

  7. Restart your shell

Updating

To update packages run this command in the directory

pipenv update

If pipenv update hangs, run this command instead

pipenv lock --clear

Running OMAN

Pull up the terminal and type 'dman' and press enter:

oman

If dman is working properly, you will see all of the possible commands that dman is capable of:

oman command line response


	```
	Usage: 
	    oman login (--email= --password=)
	    oman createUsers (--fileName=)
	    oman list (groups | objectTypes | logTypes | [verbose] schema [--selection= --forSelectionType=])
	    oman objectData (format | view) (--forSelectionType= --fileName=) [--groupID=]
	    oman (dmanAPIFill | editCSV --formatList=) (--fileName=)
	    oman fileCompare (--fileName=) (--compare=) (--fileName2=)
	    oman eventsQuery (--forSelectionType= --eventType= --fileName=) [--fileCheck=] [--groupID=]
	    oman search (--fileName=)
	    oman (create | edit | delete | for) objects [--objectLink=] (--fileName=)

	  ```
  

It will be a really long output from the terminal, it has been truncated for the readibility of this document.

OMAN Setup and Syntax

Symbols

These commands are seperated by symbols.

Symbols Explanation Example
[ ] Brackets around words means its optional. [optional parameter]
( ) Parentheses around words means its required. (required parameter)
< > Angle brackets around words means its an argument. <argument>
| The Bar bewtween parameters means its an or. this | that

OMAN Commands

Below are the list of OMAN commands

Command Explanation
login creates a login configuration file
list lists types of objectTypes and logTypes
query queries all groups and their IDS OR queries a resource (objects or logs) and can store them in a file
schema lists all of the resource (objects or logs)
templateType allows you to create a file (json or csv) to create new objects, edit current objects, or delete current objects
createEventID selects a file (JSON or CSV) and can fill out the eventID based on Beacon Serial Number and what eventID is specified (bcid, eddystone, ibeacon, or bluetooth)
editCSV edits a CSV file's values based on a Dictionary
objects allows you to create, edit, delete or modify both objects or objectLinks

login

The login command will create a authorization configuration file: "JSON/auth.json"

writesites options

  
	oman login (--email= --password=)

   

The first part of the command to type in the terminal is oman login.

  • oman login
    • Both your Loop email and password is required.
      • --email=<email> AND --password=<password>
login request

	  
	  oman login --email= --password=
		
  
login response

  	
	 Loop API Login :
	 
 		created file JSON/auth.json

  

createusers

Creates users based on a JSON a given JSON file,

createUsers

  	
		oman createUsers (--fileName=)  
   

The first part of the command to type in the terminal is oman login.

create users request

	[
		{
		"firstName": {firstName},
		"lastName": {lastName},
		"email": {email},
		"password": {password},
		"groupID": {groupID}
		},
		{
		"firstName": {firstName},
		"lastName": {lastName},
		"email": {email},
		"password": {password},
		"groupID": {groupID}
		}
	]	
		
  

list

Lists and prints groups, objectTypes, logTypes or the schema to your terminal. This allows you to determine the names of the groups, objectTypes, logTypes and schema available to you and what objectTypes you can create, edit, and delete.

list

  	
	oman create (groups | objectTypes | logTypes | [verbose] schema [--selection= --forSelectionType=])    
   

The first part of the command to type in the terminal is oman login.

  • oman list
    • PICK ONE required to objectTypes or logTypes:
      • groups OR objectTypes OR logTypes OR schema
list request

	
  		oman list objectTypes
		
  
list response

 
  		[
		    "bcdEquipment",
		    "bcdParcel",
		    "bcdPerson",
		    "bcdVehicle",
		    "Device",
		    "Place"
		]
  	
  

schema

Prints the available fields with their expected types for a specific resource (groups OR objects or logs) based on the specified resource type (i.e. bcdEquipment for objects or x_battlog for logs). This will pull down all the available fields for the resource that was queried and print to a terminal. If the optional parameter verbose, the schema will print a much more descriptive and verbose explanation of each field. If the optional argument --fileName=<fileName> is put, the output will print to a file (JSON or CSV) rather than the terminal.

List Schema has its own due to the complications

list options

  	
	oman [verbose] schema (--selection= --forSelectionType=)
    
   

The first part of the command to type in the terminal is oman and optional verbose and then schema with the specified selection with selectionType.

  • oman
    • Optional verbose
      • verbose
      • Required selection with selectionType
        • schema --selection=<selection> --forSelectionType=<selectionType>
list request

	oman query --selection=objects --forSelectionType=bcdPerson 

schema response

	 {
	    "batterySoC": "int",
	    "batterySoCObservedAt": "datetime",
	    "groupID": "string editable  required ",
	    "id": "string",
	    "lat": "decimal",
	    "long": "decimal",
	    "mostRecentPlace": "string",
	    "mrPlaceChangedAt": "datetime",
	    "name": "string editable  required ",
	    "objectType": "bcdPerson",
	    "onsite": "bool",
	    "onsiteChangedAt": "datetime",
	    "place": "string",
	    "placeChangedAt": "datetime",
	    "positionObservedAt": "datetime",
	    "serialNumber": "string editable ",
	    "temp": "int",
	    "tempObservedAt": "datetime"
	}

  
schema verbose request

oman verbose schema --selection=objects --forSelectionType=bcdPerson 

schema verbose response

  
		[
		    {
		        "displayName": "ID",
		        "editable": false,
		        "length": 32,
		        "name": "id",
		        "required": false,
		        "type": "string"
		    },
		    {
		        "displayName": "Group ID",
		        "editable": true,
		        "length": 32,
		        "link": "groups",
		        "name": "groupID",
		        "required": true,
		        "type": "string"
		    },
		    {
		        "displayName": "Object Type",
		        "editable": false,
		        "length": 100,
		        "name": "objectType",
		        "populated": true,
		        "required": true,
		        "type": "string"
		    },
		    {
		        "displayName": "Name",
		        "editable": true,
		        "length": 100,
		        "name": "name",
		        "required": true,
		        "type": "string"
		    },
		    {
		        "displayName": "Serial Number",
		        "editable": true,
		        "length": 100,
		        "name": "serialNumber",
		        "required": false,
		        "type": "string"
		    },
		    {
		        "displayName": "Battery %",
		        "editable": false,
		        "name": "batterySoC",
		        "required": false,
		        "timeCol": "batterySoCObservedAt",
		        "type": "int"
		    },
		    {
		        "displayName": "Observed At",
		        "editable": false,
		        "name": "batterySoCObservedAt",
		        "required": false,
		        "type": "datetime"
		    },
		    {
		        "displayName": "Temp",
		        "editable": false,
		        "length": 10,
		        "name": "temp",
		        "required": false,
		        "timeCol": "tempObservedAt",
		        "type": "int"
		    },
		    {
		        "displayName": "Observed At",
		        "editable": false,
		        "name": "tempObservedAt",
		        "required": false,
		        "type": "datetime"
		    },
		    {
		        "displayName": "Place",
		        "editable": false,
		        "length": 32,
		        "link": "Place",
		        "name": "place",
		        "required": false,
		        "timeCol": "placeChangedAt",
		        "type": "string"
		    },
		    {
		        "displayName": "Place Changed At",
		        "editable": false,
		        "name": "placeChangedAt",
		        "required": false,
		        "type": "datetime"
		    },
		    {
		        "displayName": "Most Recent Place",
		        "editable": false,
		        "length": 32,
		        "link": "Place",
		        "name": "mostRecentPlace",
		        "required": false,
		        "timeCol": "mrPlaceChangedAt",
		        "type": "string"
		    },
		    {
		        "displayName": "Most Recent Place Changed At",
		        "editable": false,
		        "name": "mrPlaceChangedAt",
		        "required": false,
		        "type": "datetime"
		    },
		    {
		        "displayName": "Longitude",
		        "editable": false,
		        "name": "long",
		        "required": false,
		        "timeCol": "positionObservedAt",
		        "type": "decimal"
		    },
		    {
		        "displayName": "Latitude",
		        "editable": false,
		        "name": "lat",
		        "required": false,
		        "timeCol": "positionObservedAt",
		        "type": "decimal"
		    },
		    {
		        "displayName": "Position Observed At",
		        "editable": false,
		        "name": "positionObservedAt",
		        "required": false,
		        "type": "datetime"
		    },
		    {
		        "displayName": "Onsite",
		        "editable": false,
		        "name": "onsite",
		        "required": false,
		        "timeCol": "onsiteChangedAt",
		        "type": "bool"
		    },
		    {
		        "displayName": "Onsite Changed At",
		        "editable": false,
		        "name": "onsiteChangedAt",
		        "required": false,
		        "type": "datetime"
		    }
		]


  

As you might, see the default is to print the just the display name and the expected type, because it is much easier to see the information that can be given for each resource type.

objectdata

Prints or creates a file (JSON or CSV) for objectData's format or view for existing objectData in Loop. The format data will print the schema prints to a file with the Keys and ValueTypes and whether the keys and values are required (i.e. groupID: string required ).

  • format - you would use this to pull down the
  • view

If you are trying to create new objects

objectData options

  	
	oman objectData (format | view) (--forSelectionType= --fileName=) [--groupID=]
    
   

The first part of the command to type in the terminal is oman query.

  • oman templateType
    • Required to select ONLY one of the below:
    • create OR edit OR delete
    • Required selection with selectionType and fileName to save to a file(JSON or CSV) :
      • --selection=<selection> --forSelectionType=<selectionType> --fileName=<fileName>
list request

oman query --selection=objects --forSelectionType=bcdPerson 

list response

  
		 [
			{
			"batterySoC": null,
			"batterySoCObservedAt": null,
			"groupID": "9d6d3255547edffe380502e554bfb24d",
			"id": "f67a2fe51e68ab94e7a921e35745491b",
			"lat": null,
			"long": null,
			"mostRecentPlace": null,
			"mrPlaceChangedAt": null,
			"name": "Person #3",
			"objectType": "bcdPerson",
			"onsite": null,
			"onsiteChangedAt": null,
			"place": null,
			"placeChangedAt": null,
			"positionObservedAt": null,
			"serialNumber": "50002891",
			"temp": null,
			"tempObservedAt": null
		    },
		    {
			"batterySoC": null,
			"batterySoCObservedAt": null,
			"groupID": "9d6d3255547edffe380502e554bfb24d",
			"id": "fbbe8cb1acbb83bc1c300f6fa120d60a",
			"lat": null,
			"long": null,
			"mostRecentPlace": null,
			"mrPlaceChangedAt": null,
			"name": "Person #12",
			"objectType": "bcdPerson",
			"onsite": null,
			"onsiteChangedAt": null,
			"place": null,
			"placeChangedAt": null,
			"positionObservedAt": null,
			"serialNumber": "50002D29",
			"temp": null,
			"tempObservedAt": null
		    }
		]

  

dmanAPIFill / editCSV

This command allows you to pull down the specefic identifier and format it for Loop from the BlueCats DMAN API Client. You must have a Key or Header value in your file named eventID and you must for each value write: - ibeacon for the Proximity UID - eddystone for its Eddystone UID - bluetooth for its Bluetooth Address - bcId for its SN

When you are creating objects, in order to track them in Loop you will need to store at least one unique EventID. For more information on eventIDs. For most cases you will create an EventID based on the beacon's iBeacon, Eddystone UID, Bluetooth address, or bcId (BlueCats Identifier or Serial Number).

Because it is using the DMAN API Client, it will ask for your username and password in order to get authorization.

list options

 oman dmanAPIFill (--fileName=<fileName>)

The first part of the command to type in the terminal is oman createEventID.

  • oman dmanAPIFill
    • Required fileName to save and create the EventIDs to a file (JSON or CSV) :
      • --fileName=<fileName>
list request

oman query --selection=objects --forSelectionType=bcdPerson 

list response

enter bluecats dman api username/email:
enter bluecats dman api password:

 Loop Created eventID(s): :

	created file bcdPerson.csv

editCSV

This command allows you to edit CSV or JSON files by a Key value or Header type by putting a dictionary with the keys being the header values and the dictionary having a list of formatting functions.

Format function Name Description Example
upper Returns all specified values upper case --formatList='{"serialNumber": ["upper"]}'
lower Returns all specified values lower case --formatList='{"serialNumber": ["lower"]}'
delete Deletes all specified values --formatList='{"groupID": ["delete"]}'
filter Returns the entire row only if specified value is present --formatList='{"groupID": ["filter"]}'
missing Returns the entire row only if specified value is missing --formatList='{"groupID": ["missing"]}'
{"fill":"{value to fill}"} fills a key with a given value --formatList='{"eventID": [{"fill":"eddystone"}]}'
{"equalKeep":"{value to check}"}' if the given string is within the value it will keep the entire row --formatList='{"eventID":[{"equalKeep":"eddyUID#616871"}]}'
{"equalDelete":"{value to check}"}' if the given string is within the value it will delete the entire row --formatList=formatList='{"eventID":[{"equalDelete":"eddyUID#616871"}]}'
{"joinFront":"{value to append string}"} will append a string to the front of a given value --formatList='{"eventID": [{"joinFront":"eddystone"}]}'
{"joinBack":"{value to append string}"} will append a string to the front of a given value --formatList='{"eventID": [{"joinBack":"eddystone"}]}'
{"mergeFrontWith": "{column value to append string}"} will merge a the equivalent row value to the front of a given value --formatList='{"eventID": [{"mergeFrontWith":"eventID"}]}'
{"mergeBackWith": "{column value to append string}"} will merge a the equivalent row value to the back of a given value --formatList='{"eventID": [{"mergeBackWith":"eventID"}]}'
{"replaceWith": "{column value to append string}"} will replace a the equivalent row value with a given row value --formatList='{"eventID": [{"replaceWith":"eventID"}]}'
{"findReplace": "{column value to append string}"} will replace a the equivalent row value with a found row value --formatList='{"eventID": [{"findReplace":"eventID"}]}'

There are many times when you need to clean up user submitted data, There is many times when you query an object data is missing, that the serial number should be upper cased, or maybe the wrong groupID was used.

Example of using EditCSV

You can use multiple formatting functions on each specified value. For example let's say I found some objects were not filled out with their eventIDs that I want to fill them with their eddystone UIDs and update them to Loop.

You would run the objectData format to pull down the objects:

oman objectData format --forSelectionType=bcdPerson --fileName=bcdPerson.csv

Then you would remove only the objects with missing eventIDs. The fill eddystone will allow you to prompt all of the objects to create their eventIDs.

oman editCSV --fileName=bcdPerson.csv --formatList='{"eventID": ["missing", {"fill":"eddystone"}]}'

Now that the objects have eddystone in their eventID Keys or headers, you can create their eventIDs and then edit them with loop.

oman createEventID --fileName=bcdPerson.csv
oman for objects --objectLink=create --fileName=bcdPerson.csv

The first part of the command to type in the terminal is oman createEventID.

  • oman createEventID
    • Required fileName to save and create the EventIDs to a file (JSON or CSV) :
      • --fileName=<fileName>
      • The formatList with the specified values and formats. (See above for more details)
        • --formatList=<formatList>
list request

oman editCSV --fileName=bcdPerson.csv --formatList='{"eventID": ["missing",{"fill":"eddystone"}]}'

list response

  Loop performed edit on objects :

		created file bcdPerson.csv

fileCompare

Compares two files of type JSON or CSV file type, and splits the files based on sets (setA is fileName and setB is fileName2):

  • differenceA = setA - setB
  • differenceB = setB - setA
  • intersection = setA & setB
  • union = setA | setB
fileCompare options

  	
	oman fileCompare (--fileName=) (--compare=) (--fileName2=)
   

The first part of the command to type in the terminal is mman fileCompare.

  • oman fileCompare --fileName=<fileName> to compare
    • and the value to compare: --compare=<compare>
    • the secondvalue to compare --fileName2=<fileName2>
list request

	oman fileCompare --fileName=fileCompare.csv --compare=serialNumbers --fileName2=fileCompare2.csv 

objects

From a file (JSON or CSV) for a specific objectType to create, edit, or delete objects.

  • create: Creates objects from a fileName.
  • edit: Edits objects from a fileName.
  • delete: Deletes objects from a fileName.
  • for: ONLY creates, edits, or deletes objectLinks/EventIDs from a fileName.
list options

  	
	oman (create | edit | delete | for) objects [--objectLink=] (--fileName=)

   

The first part of the command to type in the terminal is oman query.

  • oman
    • Required to select ONLY one of the below:
    • create OR edit OR delete OR for
    • For creating eventIDs use the optional [objectLink], it accepts the actions (create, edit, or delete)
      • --objectLink=<objectLink>
    • Required fileName to read from of the file type(JSON or CSV) :
      • --fileName=<fileName>
list request

oman create objects --objectLink=create --fileName=bcdPerson.csv

list response

  
  	Loop created object(s):
  			{
			"objectType": "bcdPerson", 
			"id": {objectID}
			} 
	Loop created eventID(s):
		success 

  

search

From a JSON file, allows a search to the /search endpoint. For more information check: Loop API Search Endpoint

list options

  	
	oman search (--fileName=)

   
list request

oman search --fileName=bcdPerson.json

list response

  
  	Loop API Response:
  			{
			"objectType": "bcdPerson", 
			"id": {objectID}
			} 

  

Support

If you get stuck, you can email us at support@bluecats.com.

You can’t perform that action at this time.