Automating the Administration of the Platform Hierarchy using the API

Introduction

The OpsAnalitica platform has an exposed Rest Like API. OpsAnalitica.net/api, It is with this API that an administrator can connect to the platform and script changes to the platform's configuration to keep it current. We recommend using the API for the administration of Orgs, Users, User Filters, and Locations.

This is an advanced operation and will require a knowledge of scripting, your current infrastructure and how hierarchy is managed within your company and a knowledge of how the OpsAnalitica platform is configured.

This article will cover a standard implementation of the OpsAnalitica platform but the administrator should confirm with their corporate admin how they have elected to configure the platform.

Definitions:

Term	Definition
Checklists	Checklists are the catch all term for any Question Set in the system. Checklists can be audits, logs, checklists, forms, etc.. Team members completing checklists is one of the primary purposes of the OpsAnalitica Platform. Completed Checklists are called Response Sets and they can be viewed in the Completed folder.
Location	Locations are physical places in the system. Checklists have to be conducted at a location. Users are assigned to locations through tags and User Filters. We use tags on locations to designate their hierarchy and reporting relationships.
Location Filter	A Location Filter uses tags, tags assigned to locations, to create groups of locations. Location filters are created and assigned to Checklists and Checklist Schedules, on the Checklist administration page. Location filters allow locations to only see the Checklists that they are assigned for convenience purposes. Location Filters can also be used on report filters to filter the results to a location or group of locations. Filters are explicit not dynamic, they do not adjust to tag changes on the objects they are associated.
Organizations	Organizations are containers of information that have a Parent Child Relationship. Checklists, Response Sets, Locations, and Users exist in organizations. Each OpsAnalitica Client is given a Parent Organization. If they choose, they can create Child Organizations. If a parent wants to share objects, checklists, roles, etc.., they can inherit those objects and make them available to their children. Children have no concept of their parents or siblings. Children can only consume inherited items, they cannot edit them. Children can create their own checklists that will only live in their organization and those of their children. You cannot move locations or checklists between siblings. We generally set up franchisees as their own Child Organizations to a Franchisor as a parent. In the franchisee example, you cannot move checklists or locations between orgs. If a location is sold to a different franchisee, the best practice is to inactivate the original location and then create a new version in the purchasers organization.
Roles	Roles are configurable security permissions granted to a user account that grant them access to the platform. Roles are 100% configurable. A user account with Roles will be instantly logged out because they will have no access to the system. For any kind of scripting you should create a Service account within OpsAnalitica with the Administrator Role The standard roles for an end user are Inspector, and View Reports.
Tags	Tags are text that provide context to the object that they are applied. Tags are used throughout the system: Users, User Filters, Locations, Location Filters, Checklist Questions, Checklist Responses, Checklist Response Sets, and Report Filters. Tags don't automatically connect Users and Locations, without the use of a Filter.
Users	Any person wanting to have access to the OpsAnalitica Platform needs to have an active User Account with the proper Roles. We use tags on users to designate which locations, via hierarchy tags, the user should have access to. Email addresses must be unique throughout the entire platform. Generate Password is a setting where the User gets an email to set their password. You can set the password, must be 8 digits, and you can require a change of password on first login. You must set basic roles for the user when you create their account so they can login.
User Filters	A user filter uses tags, tags assigned to users, to create groups of users. User filters are created and assigned to locations, on the location administration page. User filters allow users to only see the locations that they are assigned to for convenience purposes. Tags have to be created before they can be applied to a filter. Filters are explicit not dynamic, they do not adjust to tag changes on the objects they are associated. If you are changing the hierarchy of a location, you will need to go in and update the tags on the location and the User Filter to match. 99% of the time, the User Filter's operator is Or Else.

Standard OpsAnalitica Configuration

If you engage with OpsAnalitica to implement your platform we will generally follow this type of set-up, described below. It doesn't matter if this is a single org or multi org structure as all changes to object configuration need to take place in the org where the object is located.

For multi-org structures:

You will need to login through the api.
You will be provided with a token.
Then you will need to generate a refresh token with the org you want to navigate to.
Then you will need to switch to that org, in order to execute what ever operations you require.
You will always need to switch orgs to the proper org to execute the appropriate updates and changes.
Therefore you will need to have an intimate knowledge of how your OpsAnalitica Platform was configured and understand where things live.

Organizations:

If you are single org organization you can stop reading and move to the locations section. All of your objects will exist in your parent org.
We generally set up the parent org, in multi-org structures, with all corporate employees and all standard checklists and tags and inherit them down.
We set up all child org: locations, user filters, and users in the child orgs to limit their access.

Locations:

Locations are created and tagged with their hierarchy tags.
Hierarchy tags are just normal tags but represent the hierarchy of your organization.
It doesn't matter how many layers of hierarchy your organization has but each location should be tagged with a minimum of their: Location Name and All Locations. You can have as many layers in the middle as you want.
User Filters should be created for each location, best practice is to name them exactly the same, and should explicitly define each layer of the hierarchy with an Or Else operator in between.
User Filters after creation should be assigned to the locations.
User Filters should always contain the location name and the All Locations tags.
Once you have one location with a User Filter, any location created that doesn't have a user filter will throw off notifications to all Users.
Every location should have a User Filter unless you are a single unit operation.
When you want to change the hierarchy or whom is assigned to a location, you need to change the tags on the Location and the associated User Filter.

Service Accounts:

It is recommended that you create a service account in the Top Org with the Administrator role and run all of your scripts using that account vs. using a person's account.

User Filters:

Each location should have a user filter with the same name.
Each User filter must explicitly contain each hierarchy tag for the respected location.
Any change to a locations hierarchy needs to be updated in the User Filter for it to take affect.
99% of the time User Filters only use the Or Else Operator.

Users:

Users are created and generally are only tagged with hierarchy tag.
You should take users with multiple locations and tag them with a region name vs. putting each location tag on their separately.
Users automatically can have access to their children organizations, if they have the Switch Orgs Role.

Common Configuration Scenarios:

New User Account:

Navigate to proper organization
Create User
Apply proper hierarchy tag

User Leaves Company:

Navigate to proper organization
Edit User
Log Out User
Inactivate User

New Location:

Navigate to proper organization
Create Location
Tag Location with Proper Hierarchy Tags
Create User Filter
Apply User Filter to Location

Hierarchy Change 1 for 1:

Navigate to proper organization
Inactivate current user
If tag is personalized change tag to reflect new users name
Create new user
Apply updated tag

Hierarchy Change Not 1 for 1:

Navigate to proper organization
Create New User
Create New User Tags (if necessary)
Go to each location affected by change, update hierarchy tags
Go to each locations user filter affected by change, remove old tags and replace with new hierarchy tags

API Calls Used:

/api/filters
/api/account/token
/api/organizations/{id}
/api/users/{id}
/api/account/login
/api/locations/{id}
/api/geoinfos/{countryCode}/{administrativeDivision1}/city/{startsWith}
/api/geoinfos/{countryCode}
/api/organizations
/api/tags
/api/locations
/api/users/{id}/organizations/{organizationId}
/api/users/{id}/organizations
/api/roles
/api/users
/api/organizations/current/{id}

Next Section