Setting up the OData V4 Permission Sets


The Web Services Interface allows secure access to the data in the database from desktop applications such as Excel and PowerBI, and for programmatic extraction to other systems. The interface implements the industry standard Open Data Protocol (OData), which defines a set of best practices for consuming RESTful APIs. To learn about OData, and how it is used, please visit www.odata.org. The EnergySys platform currently supports OData v2 for reading data and is introducing support of OData v4.01 to allow Creation, Reading, Updating and Deletion (CRUD) of records.


No business data is available via the Web Services Interface until you have decided what you want to publish, and to whom. This article describes how this is configured. 


Permissions Set

The Web Services Interface uses the concept of a Permission Set as a collection of object permissions that are restricted to a particular role or roles. 



To define a Permission Set:

  1. In the Top Bar, select your Instance and the Configuration Application. 
  2. In the Side Menu, click Permission Sets > Permission Set to display the Permission Set screen. 
  3. The Permission Set Screen shows all the Permission Sets that exist in the system (if any).
  4. Click New to display the Permission Set Editor.
  5. By default, the Editor provides settings for one new Permission Set. If you want to add more, enter the amount in the Add Records field, and then click Add to create the new records. 
  6. A Permission Set record consists only of a Name for the Permission Set. This name is then used to identify all the objects and permissions that comprise this Collection.
  7. Enter a Name for your Permission Set. We recommend that you use consistent naming conventions and give your Permission Set a meaningful name. 
  8. Repeat steps 6 and 7 for every Permission Set you want to create.
  9. Enter an Audit Comment to explain why you have created the Process. 
  10. Click Save and Refresh.


You have now created the Permission Set(s). Next you need to define the Objects that are contained within that Permission Set. These are the objects that will be available to the end user of the feed.


Permission Set Objects

Any object defined in EnergySys can be added to a Permission Set. This includes standard objects as well as virtual objects (read-only objects that are backed by database views) which remain restricted to read permissions only. 


To add an Object to your Permission Set:

  1. In the Permission Set Screen, ensure that the Permission Set you want to work on is highlighted (selected) in the top Permission Set panel.
  2. In the Object Permissions panel, click Edit.
  3. In the box to the right of the Add button, enter the number of Objects you want to add to your Permission Set, and then click Add. This will create the number of records you need.
  4. The Permission Set Name column will be pre-populated with the Permission Set you had selected, so you just need to add the Objects you want to include in the Permission, using the drop-down list in the Object column.
  5. For each added Object you will need to specify whether the Object will be made available with Create, Read, Update and Delete permissions. If you do try to select to give Create, Update or Delete permissions for a Virtual Object these will not be allowed when there is an attempt to POST, PUT or DELETE data.
  6. When you have entered all the Objects you need, Enter an Audit Comment, and then click Save and Refresh.


These objects will now be available across the OData feed, to those users within the security Roles defined for this Permission Set.


Permission Set Roles

The Objects defined in a Permission Set will be accessible via OData to all users belonging to any of the Roles specified in the Permission Set Roles.


To add an Role to your Permission Set:

  1. In the Permission Set Screen, ensure that the Permission Set you want to work on is highlighted (selected) in the top panel.
  2. In the Roles panel, click Edit.
  3. In the box to the right of the Add button, enter the number Roles you want to add to your Permission Set, and then click Add. This will create the number of records you need.
  4. The Permission Set column will be pre-populated with the Permission Set Name you had selected, so you just need to add the User Roles you want to include in the Permission Set, using the drop-down list in the Role column.
  5. When you have entered all the Roles you need, Enter an Audit Comment, and then click Save and Refresh.


Note that the User Roles must be present in the system before you can add them to a Permission Set. To learn about defining User Roles, please see: Defining User Roles.


Now that you have set up your Permission Set, you can start to use them to access data on OData V4.