Adding & Managing Devices

Adding, Editing, or Deleting Devices

Once you have created your Device Labels, you are ready to add your first devices from Device Management. Adding, editing, or deleting a device can be done in three ways: 

• Manually add individual devices,
• Batch upload multiple devices using a CSV file,
• Add devices via API.

To add a device, you'll need its name and device ID. IP address and latitude/longitude are optional. The device name is simply a unique user-friendly name for display on the dashboard, but the device ID is the unique identifier sent by the device and must match the ID configured in Device Management.

To add the first device for your solution:

1. Select Device Management. 
2. You will see 2 buttons in the middle of the screen, one for batch uploading multiple devices and one for adding devices individually.
   

If your solution already has devices, these buttons will appear in the top right corner of Device Management. A third button, Devices Export, will export a CSV file of all existing devices in the solution.

Manually adding devices

To manually add a device:

1. First, click 'add new device'. 
2. Enter the Device Name and Device ID. You also have the option to add an IP address, latitude, and longitude. The Device ID must not have spaces, and each Device ID must be unique. 
3. Enter the device label values. These values will appear under 'Edit record'. See Creating Device Labels for more information. 
4. Click 'Save' to upload the device.
   

Batch uploading devices

To upload several devices at once: 

1. First, select 'Batch device upload'. 
2. Click the blue 'CSV Example button' to download an example file. This file will contain column headings for the following fields: 
   • Device Name, 
   • Device ID,
   • Username, 
   • Password,
   • IP Address,
   • Latitude and Longitude,
   • Any existing Device Labels.
3. Enter the details for each device. The Device ID must not contain spaces, and each Device ID must be unique. Only the Device Name and Device ID fields are mandatory. Each new row in the CSV file represents one device. 
4. From Device Management, click 'Choose File' and select your file. 
5. Check for a 'Done' message in the green bar. 
6. Click 'Upload' to complete the process. Under Upload History, you can see the time of upload, the number of rows in the CSV, and the number of devices uploaded. 
7. If a 'Done' message doesn't appear, check your CSV file. If there are duplicate names or ID values in the file, these records won't be valid. If you have used device labels, check if they require a specific data format such as String or Date. 
   

Exporting devices

The 'Devices export' button allows you to download a CSV file of all existing devices, device labels, and label values in the solution. This functionality is useful when you already have devices in the solution and want to edit several devices, device labels, or label values.

To export, edit, and re-upload a CSV file:

1. Click 'Devices Export'. 
2. Open the downloaded file and edit it as required. Add new devices by creating new rows, or delete devices by removing rows. You can also edit label values for existing devices. 
3. Save the updated file. 
4. From Device Management, select 'Choose File'. Add the now-edited CSV and wait for the 'Done' message in the green bar. 
5. Click 'Upload' to complete the process. 
6. Under Upload History, you can find the time of upload, the number of CSV file rows, and the number of successfully uploaded devices.

Adding devices via API

You can call the API by making HTTP GET requests to retrieve information about the current state or sending HTTP POST requests to make modifications. A specific list of operations is available, each requiring a particular set of parameters. These parameters are passed in the request body as JSON objects or URL parameters. For example, to get an authentication token, the request URL could be:

{

    "username": "username",

    "password": "password"

}

Or, the url could be: 

https://external_apis.rayven.io/GetAccessToken?username=xxx@yyy.com&password=asfdaf

With no request body.

A more complex url example could be 

https://external_apis.rayven.io/createUpdateDevicesProcess?project_id=670&device_details=dn,dc,_un,_pw,_ip,_lat,_lng,test,b,ab,sel,ft,val2,val3,testn%0D%0A"device a18","device_a18",aaa,bbb,1.2.3.4,1.1,2.2,ccc,1,ddd,am.,eee,fff,ggg,hhh

With %0D%0A signifying a new line in the parameter.

Below is an outline of available GET and POST requests and their expected results.

Get Access Token

You can use the GetAccessToken GET request to obtain login credentials. It requires a manager username and password (i.e., the credentials used to access the Rayven Manager) and returns an authorization token valid for 24 hours. Each request, except GetAccessToken, must be accompanied by a valid token.

Device Management

The Device ID column name in the devices table determines the name of the parameter used to pass the Device ID. You can find the name of this parameter using the /getDeviceIdParamName API.

Get Device ID Parameter Name

Use the GetAllEndUserGroups GET request to obtain a list of all User Groups listed by Project.

Bulk Device Update and Insertion

For bulk operations on devices in the project, the following methods allow an offline process:

Get Device Details CSV Example

GetDeviceDetailsCsvExample returns the list of parameters required for each device.

Create Update Devices Process

This API initiates a bulk update/insert operation of devices in the project.

Get Update Devices Process Status

Check the status of a previously created bulk update operation.

Commit Update Devices Process

If a process reaches the uploaded state and is valid, this process saves it and commits the changes to the project devices.

Delete Device

Delete a device using the device id. The device id parameter depends on the project and can be retrieved using GetDeviceIdParamName.

Create Device

Create a new device in the project. The parameters for each device vary depending on the specific project and can be retrieved using GetDeviceDetailsCsvExample.

Update Device

Similar to /CreateDevice. Used to update an existing device. You can't change existing device codes.

Get Device By Code

Get the details of a specific device.

Get Devices for Project

Get the details of all devices in the project.

Examples and Testing

You can test API endpoints using Postman.

Generate a Token

To generate a valid authorization token, use the GetAccessToken call:

2. Create a new request in postman. 
3. Set request type to 'Get'. 
4. Use the address of the API ( https://external_apis.rayven.io ) and the call name (GetAccessToken) to generate the address.
5. In the 'body' section, select 'raw' and enter the request: {"username":"XXXX@XXXX","password":"XXXXX"}
6. Click 'send' to submit the request and receive the authorization token.

GET Request

1. Create a new request in postman. 
2. Set request type to 'Get'. 
3. Use the address of the API ( https://external_apis.rayven.io ) and the call name (for instance, GetProjectMasterTags) to generate the address.
4. In the 'body' section, select 'raw' and enter the request: {"project_id":"XX"}
5. Select the 'Headers' section. 
6. Add a header name 'Authorization'. Set it’s value to 'basic xxxxxx' where xxxxx stands for the token received from the GetAccessToken request.
7. Click 'Send' to send the request. The response contents will contain the list of tags. 

POST Request

1. Create a new request in postman. 
2. Set request type to 'Post'.
3. Use the address of the API ( https://external_apis.rayven.io ) and the call name (for instance, createUserGroup ) to generate the address.
4. In the “body” section, select “raw” and enter the request: {"project_id": "670", "group_name":"tstgrp7"}
5. Select the 'Headers' section. Add a header name 'Authorization'. Set it’s value to 'basic xxxxxx' where xxxxx stands for the token received from the GetAccessToken request.
6. Click 'send' to send the request. A return value of 200 or 201 indicates success.