Company Grouping
Company Grouping is a feature that gives you granular control over how users are allowed to interact with data in Flow.
This is done by creating segments, which represents a set of permissions for a role and is applied to a resource like an address or agreement. You'll find a full list of namespaces and endpoints that currently support data segmentation below.
Overview
This guide uses the case of two organisations and two users to demonstrate how Company Grouping can be used.
In our example we have two organisations, Organisation A and Organisation B, and two Users/Roles, User A and User B. User A has a Support role at Organisation A, and User B has a Technician role at Organisation B. Our intention is for User A to be able to access data related to their Support work at Organisation A, and User B to be able to access data related to their Technician work at Organisation B.
Prerequisites
Before you can start using Company Grouping, you need to have the following set up in your Flow instance:
- Environment variable DATASEGMENTATION_ENABLED=true set on the component.
- Two organizations, Organization A and Organization B
- Two roles, Org A - Support and Org B - Technician
- Two users, User A and User B
- Two addresses, A Street and B Street
Availability
Company grouping can be used on following components of Flow. Not all endpoints support company grouping, refer to the list at the end of this document.
- Flow Auth
- Flow GUI
- Address
- Customer
- Product
- Inventory
- Billing
- Ticket
Creating a segment
To create a segment, you need to log in as an administrator and navigate to the Segments section in the Administration menu. From here, you can create a new segment by clicking the Plus button in the top right corner.
The Create a new segment modal will open. We will create a segment for each of our two organisations, Organisation A and Organisation B.
Configuring a segment
To configure the permissions for a segment, you navigate to the Roles section in the Administration menu. From here, you can select the role you want to configure and select what permissions you want to associate with what segment for that role in the Data Segmentation Permissions widget.
Here, we only show us configuring the permissions for the Support role at Org B but you can configure the permissions for the Technician role at Org A in a similar way. We give the Support role read access to the Address and Outlet namespaces.
Assigning a segment to a resource
Once you have created a segment and configured the permissions for an associated role, you can assign one or more segments to a resource.
To assign a segment to a resource, you navigate to the resource you want to assign the segment to in the Permission Segment box. By default, resources will be assigned to the Default segment, which does not constrain access.
Now, lets remove the default segment and assign the Organisation A segment to the Address resource, resulting in only the Technician role (or other roles with the same permissions on the same segment) being able to access the Address resource.
While we're at it, let's also assign the Organisation B segment to another address so that we can make sure that only the Support role can access the address.
Observing the results of segmentation
Let's take a look at how the results of our segmentation look like. We'll log in as User A and navigate to the Address resource.
Here we can see that the Organisation A segment is applied to the Address resource, and that only the Support role can access the resource.
Conclusion
In this guide, we've demonstrated how to use Company Grouping to control access to data in Flow in a multi-organisation, multi-role environment. We've shown how to create segments, configure permissions for roles, and assign segments to resources.
Our scenario is only a small example of how Company Grouping can be used in a real-world scenario. We hope this can serve as inspiration when using Company Grouping in your own environment.
Full list of namespaces and endpoints that currently support data segmentation
To use an endpoint when company grouping is turned on a user must be admin or a role of the user needs a segemnts permission on the coresponding namespace.
Address component
Uses segments set on the address object. If looking for an outlet, a check against segments attached to the address the outlet is connected to is made.
| Namespace | Endpoint | Methods |
|---|---|---|
| address/address | address/address | CREATE, OPEN, LIST, UPDATE, DELETE |
| address/address | address/address/extended | OPEN, LIST |
| address/address | address/address/withlabel | LIST |
| address/address | address/address/customer | LIST |
| address/address | address/address/availableproducts | LIST |
| address/address | address/address/agreement | LIST |
| address/address | address/address/customeraddressrelation | CREATE |
| address/address | address/address/flowaccess | LIST |
| address/outlet | address/outlet | CREATE, OPEN, LIST, UPDATE, DELETE |
| address/outlet | address/outlet/extended | OPEN |
| address/outlet | address/outlet/address | OPEN |
| address/outlet | address/outlet/access | OPEN |
| address/outlet | address/outlet/fromport | LIST |
| address/outlet | address/outlet/portfeasibility | OPEN |
Customer component
Uses segemnt defined on the customer object.
| Namespace | Endpoint | Methods |
|---|---|---|
| customer/customer | customer/customer | CREATE, OPEN, LIST, UPDATE, DELETE |
| customer/customer | customer/customer/organisation | CREATE, LIST, DELETE |
| customer/customer | customer/customer/profile | CREATE |
| customer/customer | customer/customer/address | CREATE, LIST |
| customer/customer | customer/customer/extended | OPEN, LIST |
| customer/customer | customer/customer/fromaddress | LIST |
| customer/customer | customer/customer/availableproducts | LIST |
| customer/customer | customer/customer/agreement | CREATE, LIST |
| customer/customer | customer/customer/facilities | LIST |
Product component
Uses segments defined on product or agreement object.
| Namespace | Endpoint | Methods |
|---|---|---|
| catalogue/agreement | catalogue/agreement | CREATE, OPEN, LIST, UPDATE, DELETE |
| catalogue/agreement | catalogue/agreement/create | CREATE |
| catalogue/agreement | catalogue/agreement/restart | CREATE |
| catalogue/agreement | catalogue/agreement/extended | OPEN, LIST |
| catalogue/agreement | catalogue/agreement/extendedfromaddress | OPEN, LIST |
| catalogue/agreement | catalogue/agreement/extendedfromproduct | OPEN |
| catalogue/agreement | catalogue/agreement/extendedfromcustomer | OPEN |
| catalogue/agreement | catalogue/agreement/serviceinstance | OPEN |
| catalogue/agreement | catalogue/agreement/customer | OPEN |
| catalogue/agreement | catalogue/agreement/address | OPEN |
| catalogue/agreement | catalogue/agreement/operation | OPEN |
| catalogue/agreement | catalogue/agreement/settings | LIST |
| catalogue/agreement | catalogue/agreement/outlets | LIST |
| catalogue/agreement | catalogue/agreement/fromoutlet | OPEN |
| catalogue/agreement | catalogue/agreement/msmusernamesetting | OPEN |
| catalogue/agreement | catalogue/agreement/msmsubscriberreferencesetting | OPEN |
| catalogue/agreement | catalogue/agreement/flowaccess | LIST |
| catalogue/agreement | catalogue/agreement/startbilling | CREATE |
| catalogue/agreement | catalogue/agreement/stopbilling | CREATE |
| catalogue/agreement | catalogue/agreement/alerts | LIST |
| catalogue/agreement | catalogue/agreement/light | OPEN |
| catalogue/product | catalogue/product | CREATE, OPEN, LIST, UPDATE, DELETE |
| catalogue/product | catalogue/product/priceitem | LIST |
| catalogue/product | catalogue/product/productorder | LIST |
| catalogue/product | catalogue/product/settings | LIST |
| catalogue/product | catalogue/product/label | CREATE, LIST, DELETE |
| catalogue/product | catalogue/product/fromservice | LIST |
| catalogue/product | catalogue/product/availability | LIST |
| catalogue/product | catalogue/product/organisation | LIST |
| catalogue/product | catalogue/product/extended | LIST |
| catalogue/product | catalogue/product/msmsubscriberreferencesetting | OPEN |
| catalogue/product | catalogue/product/msmusernamesetting | OPEN |
| catalogue/product | catalogue/product/msmsubscriptionreferencesetting | OPEN |
| catalogue/product | catalogue/product/msmstaticipsetting | OPEN |
| catalogue/product | catalogue/product/flowaccess | OPEN, LIST |
| catalogue/product | catalogue/product/conditions | LIST |
Billing component
Uses segment on the agreement the billing is assoicated with.
| Namespace | Endpoint | Methods |
|---|---|---|
| billing/billing | billing/billing | CREATE, OPEN, LIST, UPDATE, DELETE |
| billing/billing | billing/billing/add | CREATE |
| billing/billing | billing/billing/economy | UPDATE |
| billing/billing | billing/billing/product | UPDATE |
| billing/billing | billing/billing/address | UPDATE |
| billing/billing | billing/billing/customer | UPDATE |
| billing/billing | billing/billing/terminate | UPDATE |
| billing/billing | billing/billing/children | LIST |
Ticket component
Currently there is no way in the GUI to set segment on a ticket. Create an event for creating and updateing a ticket to make sure segement is correctly set on the ticket.
| Namespace | Endpoint | Methods |
|---|---|---|
| ticket/ticket | ticket/ticket | CREATE, OPEN, LIST, UPDATE, DELETE |
| ticket/ticket | ticket/ticket/label | CREATE, LIST, DELETE |
| ticket/ticket | ticket/ticket/comment | LIST |
| ticket/ticket | ticket/ticket/extended | OPEN |
| ticket/ticket | ticket/ticket/showcontact | OPEN |
| ticket/ticket | ticket/ticket/affected | LIST |
| ticket/ticket | ticket/ticket/subscribed | LIST |
| ticket/ticket | ticket/ticket/flowaccess | OPEN, LIST |
| ticket/ticket | ticket/ticket/flowaccess/contactinfo | OPEN |
| ticket/ticket | ticket/ticket/quick | LIST |