14.4

One September 4th, 2021, Help Lightning released 14.4 of its server software. This version contains APIs around the new Workspaces feature.

Workspaces can be thought of as “sub-enterprises”. You can use all the same /enterprise/* routes on a workspace, just like you would on your primary enterprise.

The terminology in the API is not a 1-to-1 match with the terminology that the frontend or marketing uses. Here are some definitions:

• Primary Site :: This is the top level Primary Enterprise. This holds all the primary users and the workspaces. No calls ever happen at this level, it is for administrative purposes only.
• Workspace :: This is a Sub-Enterprise. It is a full enterprise, which has users (aliases), groups, calls, and settings. The only difference from a previous enterprise, is that it has a parent id pointing to its Primary Site.
• Primary/Login User :: This is a user that exists in the Primary Site. This user is associated with a Login and can have 0 or more aliases in different workspaces. This user is never used for calls directly. It is used for authentication and switching to an Alias user, and in the case of a Site Administrator, for management of the Primary Site.
• Alias User :: This is a user that exists in a specific workspace. Each alias user will have a parent id pointing to its Primary/Login User in the Primary Site. Each Alias User will have its own id and its own data.
• Enterprise :: Both Primary Sites and Workspaces are types of Enterprises. The only difference being their permission sets and whether they are a parent or child enterprise. Almost all APIs operate on Enterprises which could be either a Primary Site or a Workspace. Throughout this document, we will use Enterprise to talk about a generic data structure or API, and use Primary Site or Workspace when discussing a specific type of Enterprise.

Each workspace can have their own features, settings, and developer keys.

When 14.4 was released, a data migration took place. This migration created a new Primary Site for every single existing Enterprise. It then took the current Enterprise, and made it a Workspace under the new Primary Site. The migration also created a new Primary/Login User in the new Primary Site for every existing user. The existing users then became Aliases for the new Primary Users.

This left no noticeable changes for users or API integrations. They continued to operate on their normal enterprise and users, even though those are now a Workspace and Alias Users.

This is because each Workspace is actually a different enterprise, with a different ID and different partner keys. The existing partner keys just operate on the default Workspace. When “switching” to a different workspace, you are actually transparently becoming a different user in a different enterprise.

There are two ways to utilize Help Lightning Workspaces with regards to the API:

1. If your workspaces are static, you can manually create the new workspaces, and manually create a new partner key for each workspace. You can then continue using the API as you always have, you will just need to change which partner key you are using when working with a different workspace. You can essentially treat each workspace as a completely separate site.

2. If you are going to need to dynamically create workspaces, or move users into multiple workspaces, then you will want to utilize Help Lightning’s new APIs. You will need to generate a new partner key at the Primary Site level (this can only be done programatically). Utilizing this new partner key, you can create/delete workspaces, add/remove users, and organize them into workspaces. You can also get a token for each workspace to modify any of its users, calls, groups, or any other properties. This method gives you the most power, but will require some significant changes in your existing integrations!

If you choose to go with option #2 from above, then you will need to create a partner key in your Primary Site. This will be your master partner key, and will have the ability to manage ALL of your workspaces!

The Help Lightning interface currently doesn’t support creating a partner key in the Primary Site. If you choose to do so, you will need to do it manually through the Help Lightning API.

You MUST be a Site Administrator to do this

It is recommended that you read through the Token documentation first.

Log in to your site and get a refresh token for your Primary/Login User. You can either use your web browser’s developer tools and capture the response (this is required if you sign in using SSO), or you can use the /v1r1/auth API.

You need to then use the refresh token to get an updated user token. This can be done using the /v1/refresh API.

This is necessary, since by default, Help Lightning lowers the privileges of your Primary/Login User upon authentication, since most operations should be done with an Alias User.

Using your user token, you can now get an enterprise token to your Primary Site using the /v1/enterprises API.

Please verify that you are working on your Primary Site!. You can verify the ID of the site to make sure it is not actually a Workspace.

You can now use the enterprise token from the previous API call to generate a partner key using the /v1r1/enterprise/partner_key APIs. For more information on Partner Keys, please see the Partner Keys Documentation.

The API call will create a public/private key pair. Make sure you save your private key in a safe place. This key cannot be recovered. If lost, you will have to generate a new one which invalidates the old one.

Using this partner key, you can begin using the new workspaces API as outlined in the next section.

There are several new workspace APIs that you can use to manage your workspaces.

GET /v1r1/enterprise/workspaces.

This API will list all workspaces in your Primary Site. Not only will it return basic information about each workspace, but will also return a token for that workspace. This token is an “enterprise token” and can be used with any enterprise routes by using the “enterprise token” in the Authorization: header.

It is possible to not have any workspaces! However, this isn’t very useful, as calls can only be made from inside of a workspace.

If you know the ID of one of your workspaces, you can get it directly using the GET /v1r1/enterprise/workspaces/{id} API.

POST /v1r1/enterprise/workspaces.

This API will create a new workspace in your Primary Site. The response will include a token, which is an “enterprise token” that can be used with any enterprise route to manipulate this workspace, such as adding users, groups, and generating call reports.

Deleting a Workspace deactivates it along with all user aliases. You can still pull reports from it, or reactivate it.

DELETE /v1r1/enterprise/workspaces/{id}.

If a user only belongs to a single workspace, and that workspace is “deleted”, then that user alias will be deactivated, and they will not be able to use Help Lightning unless they are moved to an active workspace.

There are no new APIs for modifying an existing workspace since they are just Enterprise objects. You just need to get a token for your workspace, either by listing your workspaces or by getting a workspace by ID. This is an “enterprise token” which can then be used with any enterprise routes to modify that workspace.

Remember: 1) A Workspace is just an enterprise that has a parent, 2) The token has the ID of the workspace embedded into it. Using it as part of the Authorization: header to any route will cause that route to operate on that specific enterprise (workspace).

Help Lightning always strives to keep 100% backward compatibility in our RESTful API. However, we do sometimes add additional parameters or key/values to the response.

Several existing Help Lightning APIs have been updated to include some additional information about workspaces that may be helpful. For example, if you call GET /v1r1/enterprise/users on your Primary Site to list all of your users, each user will now have additional information about the workspaces they belong to.

Please read carefully as Alias Users are deleted by default rather than deactivated, and cannot be recovered!

As mentioned earlier, every user in the Help Lightning system now has a Primary/Login User which is used for authentication. The user then switched into one of their Alias Users, which actually involves becoming a different Help Lightning User in a different Help Lightning Enterprise.

When a user is added to a workspace, the system creates a new user object, which we call an Alias inside of the workspace enterprise. This user has different properties (name, username, role, permissions), and has different data associated with it (pods, calls, tags, …)

To remove a user from Help Lightning, you have three options:

1. Deactivate the Primary User :: This can be done by calling PUT /v1r1/enterprise/users/{id} with the active=False flag set on the Login/Primary User in the Primary Site. This will deactivate the Login/Primary User and that user will no longer be able to log in or use the system. All data surrounding this user in both the Primary Site and any Workspaces they belong to will be retained in reports. The user can be reactivated by calling the same API with active=True.
2. Deactivate the Aliases :: This can be done by calling PUT /v1r1/enterprise/users/{id} with the active=False flag set on the Alias User in the desired Workspace. This will only deactivate that specific user alias. However, if a user does not have any active Aliases, then they cannot log into the application and make calls. If they are a Site Admin in the Primary Site, then they can still log into the web interface and manage the site or download call reports. This would be an example of an Admin only user. All data associated with a deactivated Alias is retained in reports, and the Alias can be reactivated by calling the same API with active=True.
3. Deleting the Aliases :: This can be done by calling DELETE /v1r1/enterprise/users/{id} on the Alias User in the Workspace. This is a destructive operation and cannot be undone! This will permanently delete the Alias and remove any associated data with this Alias. Call Reports and Audit logs will no longer show information tied to this user, and will instead show Deleted User.