REST API

From IT Asset Management - Oomnitza Wiki
Jump to: navigation, search

The official documentation for the Oomnitza Platform API v1. This is a REST API with JSON structure.

Contents

Authorization

Logging In

This will retrieve an API access token from the Oomnitza system. Lets assume a system user called SysUser exists with password abc123 to authenticate.

   HTTPS POST
   Content Type: application/x-www-form-urlencoded
   URL: https://company.oomnitza.com/api/request_token?login=SysUser&password=abc123
   Body: [empty]
   Response Content-Type: application/json
   Response Body: {“token”:”random_generated_token”}

Logging Out

This will end the current session between the user and the system.

   HTTPS POST
   Content Type: application/x-www-form-urlencoded
   URL: https://company.oomnitza.com/service/logout
   Body: [empty]
   Response Content-Type: application/json
   Response Body: {“errors”:[]}

User Management

Getting User Permissions

This will retrieve the available user permissions to be used for user creation or existing user role updates.

   HTTPS POST
   Content Type: application/x-www-form-urlencoded
   URL: https://company.oomnitza.com/api/people/permissions/blocks?access_token=retrieved_token
   Body: [empty]
   Response Content-Type: application/json
   Response Body: {“errors”: [], "rows":[], "has_next":false, "has_prev":false}  (Errors array will be nonempty if error occurs)
   

Row Object

Key Type Description
sub_indicator String Asset string reference (or null).
sub_label2 String User configured asset secondary sub label.
sub_label String User configured asset sub label.
id Integer Id of asset.
label String Label to display for asset.

Adding a User

This will create a new user in Oomnitza.

   HTTPS POST
   Content Type: application/x-www-form-urlencoded
   URL: https://company.oomnitza.com/api/people/individuals/add?access_token=retrieved_token
   Body: output[USER]=john.smith
         &output[PASSWORD]=admin123
         &output[FIRST_NAME]=John
         &output[LAST_NAME]=Smith
         &output[EMAIL]=john@smith.com
         &output[HOURLY_WAGE]=0
         &output[PERMISSIONS_ID]=39
         &output[POSITION]=Employee
         &output[PHONE]=6501234567
         &output[ADDRESS]=12 Berry Road, Los Altos, CA
   Response Content-Type: application/json
   Response Body: {“errors”:[], “id”:”user_id”}  (Errors array will be nonempty if error occurs)

Removing a User

This will remove the specified user in Oomnitza.

   HTTPS POST
   Content Type: application/x-www-form-urlencoded
   URL: https://company.oomnitza.com/api/people/individuals/delete?access_token=retrieved_token
   Body: ids[]=john.smith
   Response Content-Type: application/json
   Response Body: {“errors”: []}  (Errors array will be nonempty if error occurs)

Location Management

Getting Location Fields

This will query the system for active location fields. In order to create a new location, this service will generally be required to identify necessary fields.

   HTTPS POST
   Content Type: application/x-www-form-urlencoded
   URL: https://company.oomnitza.com/api/assets/locations/empty_location?access_token=retrieved_token
   Body: [Empty]
   Response Content-Type: application/json
   Response Body: {“errors”:[], “info”:[]}  (Errors array will be nonempty if error occurs)

Info Field Object

Key Type Description
CHECKBOX Integer Indicates if the field is checked (disregard if non-checkbox).
GROUP String String of group that field is associated.
DATA_TYPE String Field data type (i.e. CHAR, TEXT, INT, DATE, USERS, LOCATION, etc.)
LIST String[] String array of drop-down field options (empty if none).
EDITABLE Integer Indicates if field is editable (i.e. '0' or '1')
VALUE String Field value to display.
LABEL String Label to display for field name.
VISIBLE_IN_DETAILS Integer Indicates if field should be shown in asset detail view (i.e. '0' or '1')
OPTIONAL Integer Indicates if this field is mandatory or optional (i.e. '0' or '1')
ID String ID of field in system.

Adding a Location

This will create a location within the system. To determine the required fields to create the location, see the above request.

   HTTPS POST
   Content Type: multipart/form-data
   URL: https://company.oomnitza.com/api/assets/locations/add_location?access_token=retrieved_token
   Body: output[LOCATION_ID]=345322
         &output[ASSET_TOTAL]=1500
         &output[LABEL]=Headquarters
         &gps[LAT]=37.3860517
         &gps[LNG]=-122.083511
         ... 
   Response Content-Type: application/json
   Response Body: {“errors”:[], “id”:1134}  (Errors array will be nonempty if error occurs)

Getting Location Information

This will retrieve data about a specified location.

   HTTPS POST
   Content Type: application/x-www-form-urlencoded
   URL: https://company.oomnitza.com/api/assets/locations/get_info?access_token=retrieved_token
   Body: id=HQ
   Response Content-Type: application/json
   Response Body: {“errors”:[], “info”:[], "GPS":{}, "assets":[], "media":[], 
                  "thumbnail":""}  (Errors array will be nonempty if error occurs)

Location Info Response Object

Key Type Description
info String[] Array of field label - value pairs with asset info.
media String[] Array of media fields (empty if none).
errors String[] Array of errors (empty if none).
thumbnail String String with id of thumbnail (null if none).
assets Dictionary Dictionary with key (asset id) and value (string[] asset label info)

Searching for Locations

This will query the database for location results.

   HTTPS POST
   Content Type: application/x-www-form-urlencoded
   URL: https://company.oomnitza.com/api/assets/locations/filter?access_token=retrieved_token
   Body: []
   Response Content-Type: application/json
   Response Body: {“errors”:[], “info”:[]}  (Errors array will be nonempty if error occurs)

Info Field Object

Key Type Description
CHECKBOX Integer Indicates if the field is checked (disregard if non-checkbox).
GROUP String String of group that field is associated.
DATA_TYPE String Field data type (i.e. CHAR, TEXT, INT, DATE, USERS, LOCATION, etc.)
LIST String[] String array of drop-down field options (empty if none).
EDITABLE Integer Indicates if field is editable (i.e. '0' or '1')
VALUE String Field value to display.
LABEL String Label to display for field name.
VISIBLE_IN_DETAILS Integer Indicates if field should be shown in location detail view (i.e. '0' or '1')
OPTIONAL Integer Indicates if this field is mandatory or optional (i.e. '0' or '1')
ID String ID of field in system.

Removing a Location

This will delete a location from the system. The location will no longer appear in the system, however all data related to the location will be preserved in the archive.

   HTTPS POST
   Content Type: application/x-www-form-urlencoded
   URL: https://company.oomnitza.com/api/assets/locations/delete_location?access_token=retrieved_token
   Body: ids[]=HQ
   Response Content-Type: application/json
   Response Body: {“errors”:[]}  (Errors array will be nonempty if error occurs)

Field Management

Adding a Field

This will create a new field in the system for tracking asset, location, or work order data.

   HTTPS POST
   Content Type: application/x-www-form-urlencoded
   URL: https://company.oomnitza.com/api/assets/customization/add_field?access_token=retrieved_token
   Body: output[LABEL]=New Field Title
         &output[BELONGS_TO]=ASSETS
         &output[DATA_TYPE]=TEXT
         &output[EDITABLE]=1
         &output[OPTIONAL]=0
         &output[DISPLAY_ORDER]=2
         &output[DEFAULT_VALUE]=
         &output[SEARCHHELP]=
   Response Content-Type: application/json
   Response Body: {“errors”:[], “id”:”field_id”}  (Errors array will be nonempty if error occurs)

Removing a Field

This will remove a specified field from the system.

   HTTPS POST
   Content Type: application/x-www-form-urlencoded
   URL: https://company.oomnitza.com/api/assets/customization/delete_fields?access_token=retrieved_token
   Body: ids[]=261
   Response Content-Type: application/json
   Response Body: {“errors”:[]}  (Errors array will be nonempty if error occurs)

Asset Management

Getting Asset Fields

This will query the system for active asset fields. In order to create a new asset, this service will generally be required to identify necessary fields.

   HTTPS POST
   Content Type: application/x-www-form-urlencoded
   URL: https://company.oomnitza.com/api/assets/assets/empty?access_token=retrieved_token
   Body: [Empty]
   Response Content-Type: application/json
   Response Body: {“errors”:[], “info”:[]}  (Errors array will be nonempty if error occurs)

Info Field Object

Key Type Description
CHECKBOX Integer Indicates if the field is checked (disregard if non-checkbox).
GROUP String String of group that field is associated.
DATA_TYPE String Field data type (i.e. CHAR, TEXT, INT, DATE, USERS, LOCATION, etc.)
LIST String[] String array of drop-down field options (empty if none).
EDITABLE Integer Indicates if field is editable (i.e. '0' or '1')
VALUE String Field value to display.
LABEL String Label to display for field name.
VISIBLE_IN_DETAILS Integer Indicates if field should be shown in asset detail view (i.e. '0' or '1')
OPTIONAL Integer Indicates if this field is mandatory or optional (i.e. '0' or '1')
ID String ID of field in system.

Adding an Asset

This will create an asset within the system. To determine the required fields to create the asset, see the above request.

   HTTPS POST
   Content Type: multipart/form-data
   URL: https://company.oomnitza.com/api/assets/assets/add?access_token=retrieved_token
   Body: output[BARCODE]=345345
         &output[NAME]=Asset Name
         &output[LOCATION]=Location ID
         &output[MANUFACTURER]=Asset Make
         ... 
   Response Content-Type: application/json
   Response Body: {“errors”:[], “id”:1134}  (Errors array will be nonempty if error occurs)

Getting Asset Information

This will retrieve data about a specified asset.

   HTTPS POST
   Content Type: application/x-www-form-urlencoded
   URL: https://company.oomnitza.com/api/assets/assets/info?access_token=retrieved_token
   Body: id=123
   Response Content-Type: application/json
   Response Body: {“errors”:[], “info”:[], "GPS":{}, "history":[], "label":"", "media":[], 
                  "sublabel":"", "thumbnail":""}  (Errors array will be nonempty if error occurs)

Asset Info Response Object

Key Type Description
info String[] Array of field label - value pairs with asset info.
media String[] Array of media fields (empty if none).
errors String[] Array of errors (empty if none).
thumbnail String String with id of thumbnail (null if none).

Searching for Assets

This will query the database for asset results.

   HTTPS POST
   Content Type: application/x-www-form-urlencoded
   URL: https://company.oomnitza.com/api/assets/assets/filter?access_token=retrieved_token
   Body: []
   Response Content-Type: application/json
   Response Body: {“errors”:[], “info”:[]}  (Errors array will be nonempty if error occurs)

Info Field Object

Key Type Description
CHECKBOX Integer Indicates if the field is checked (disregard if non-checkbox).
GROUP String String of group that field is associated.
DATA_TYPE String Field data type (i.e. CHAR, TEXT, INT, DATE, USERS, LOCATION, etc.)
LIST String[] String array of drop-down field options (empty if none).
EDITABLE Integer Indicates if field is editable (i.e. '0' or '1')
VALUE String Field value to display.
LABEL String Label to display for field name.
VISIBLE_IN_DETAILS Integer Indicates if field should be shown in location detail view (i.e. '0' or '1')
OPTIONAL Integer Indicates if this field is mandatory or optional (i.e. '0' or '1')
ID String ID of field in system.

Deleting an Asset

This will delete an asset from the system. The asset will no longer appear in the system, however all data related to the asset will be preserved in the archive.

   HTTPS POST
   Content Type: application/x-www-form-urlencoded
   URL: https://company.oomnitza.com/api/assets/assets/delete?access_token=retrieved_token
   Body: ids[]=1143
   Response Content-Type: application/json
   Response Body: {“errors”:[]}  (Errors array will be nonempty if error occurs)