Multi-tenant Environments in ClientSpace

ClientSpace supports multi-tenant environments whereby an install has multiple Prism API configurations and where the Client Number may not be unique across Prism database instances.

Note: Contact ClientSpace Professional Services to implement multi-tenancy configuration. Do NOT try to implement this feature without ClientSpace Professional Services. Attempting to implement this feature on your own can lead to major problems with ongoing imports.

Where is multi-tenancy enabled?

Multi-tenancy is enabled in System Admin > Administrative Data > PEO Configuration by setting the Use Multi-tenancy field database. There are other requirements that must be set up by Professional Services.

How multi-tenant API feeds work

Importing

ClientSpace imports data from multiple PrismHR databases into the appropriate workspaces by combining the PEO ID and the Client Number values into an Import ID on the Client Master record. The ImportID follows the format PEOID::ClientNumber (for example, PEOSolutions::165 signifies the PrismHR database installation for PEO Solutions and Client Number 165 from that database). ClientSpace uses this ImportID format to ensure that the system imports client data to the correct workspace when importing the data from multiple PrismHR databases.

Additionally, you can control whether a new workspace is automatically created from an import file for each PrismHR API feed individually using a CanCreateWorkspaces API parameter in PrismHR API import map detail settings (System Admin > Advanced > API Configuration). See the Additional Parameters section of Ongoing Imports: Configuring the API for Import Map Details for more details.

Exporting

Client data can be exported from the Client Master record in ClientSpace to PrismHR in multi-tenant environments. When Export Client to Prism is clicked on the Client Master to export the client data, the PEO ID on the Client Master and the Secondary ID on the API Config forms are used to determine the correct Prism instance. The two field values must match.

Note: There is error handling to check for a missing PEO ID or an invalid PEO ID (whereby the PEO ID on the Client Master does not match the Secondary ID on the API Configuration.)

  • If the PEO ID is missing, the following error message displays: "Your export cannot be completed without a PEOID. Add the correct PEOID on the Client Master so we know where to export this."

  • If the PEO ID is invalid, the following error message displays: "The PEOID '{PEOID}' on this client's Client Master is invalid. Please correct the PEOID on the Client Master before trying to export this again."

 

How multi-tenant business rules are applied

The ClientSpace business rules engine contains a Workspace Templates field in the Manage Rules configuration to support multi-tenancy:

This field allows you to configure rules to only be triggered when the executing dataform was created from one of the selected workspace templates. If no specific template(s) are selected, the Workspace Templates field will default to "All Templates".

Client Master Import ID Validation

Two of the business rules, SE_ValidateClientNumberChange (soft error validation) and HE_ValidateClientNumberChange (hard error validation), are used in both multi-tenant and single-tenant environments to validate a change to the Client Number. In a multi-tenant environment, these rules also trigger when a change is made to the PEO ID since PEO ID is a component of the Import ID. In a multi-tenant environment, changes to either the PEO ID or the Client Number could cause client data imports to stop working.

Note: Both rules also require the Client Master status to be Client, Pending Termination or Terminated for triggering to occur.

If you are using Soft Error validation ( SE_ValidateClientNumberChange) with Use Multi-Tenancy enabled, the following messages are used when a user changes the PEO ID, the Client Number or both the Client Number and PEO ID, respectively:

  • "Changing the PEO ID will cause the Import ID's and Employee Identifiers to be regenerated, which could affect imported data. Are you sure you want to continue?"

  • "Changing the Client Number will cause the Import ID's and Employee Identifiers to be regenerated, which could affect imported data. Are you sure you want to continue?"

  • "Changing the Client Number or PEO ID will cause the Import ID's and Employee Identifiers to be regenerated, which could affect imported data. Are you sure you want to continue?"

 

If you are using Hard Error validation (HE_ValidateClientNumberChange) with Use Multi-Tenancy enabled, the following messages are used when a user changes the PEO ID, the Client Number or both the Client Number and PEO ID, respectively:

  • "The PEO ID cannot be changed after the Status is set to Client."

  • "The Client Number cannot be changed after the Status is set to Client."

  • "The Client Number or the PEO ID cannot be changed after the Status is set to Client."

Organization ID Updates

The SetOrgImportID rule writes the PEO ID and Client Number field values from the Client Master record to the Organization Details record Import ID field in the same format used on the Client Master record: PEOID::ClientNumber.

See an example in the image below:

Organization Detail Record With Multi-Tenant Import ID

The rule is triggered when:

  • The Client Number and PEO ID on the Client Master record are populated (i.e., not empty).

  • A change occurs (i.e., an "Is Dirty" condition exists) on Client Number and/or PEO ID on the Client Master record.

Note: 

  • If the status of the Client Master record is Client, Pending Termination or Terminated and the HE_ValidateClientNumberChange business rule is Active, hard error validation will trigger when changes are made to the PEO ID or Client Number in multi-tenant environments and prevent updates from being saved to the PEO ID or Client Number. If this happens, the SetOrgImportID rule cannot trigger.

  • Though the SetOrgImportID rule was created for multi-tenant sites, enabling Use Multi-Tenancy (System Admin > Administrative Data > PEO Configuration) is not required for the rule to work.

Benefits Batch, Benefit Group, and Employee Benefits Detail Import ID Updates

To support the benefit renewal process in multi-tenant environments, business rules are configured to use the SetImportID business rule method to set the Import ID on the Benefits Batch, Benefits Group, and Employee Benefits Detail dataforms.

For the Benefits Batch form:

  • The rule is triggered when Client Master Import ID, Benefits Batch Effective Date and Benefit Batch Type are not empty and the Benefits Batch Effective Date or Benefit Batch Type is updated.

  • If any of the required values are empty, the Import ID field is empty.

  • The Import ID is created by combining the Client Master Import ID, Benefits Batch Effective Date and Benefit Batch Type values.

  • The ImportID follows the format {ClientMaster.ImportID}- {BenefitBatch.EffectiveDate} - {BenefitBatch.luType}.

     

    Example: PEOSolutions::165-20240101-RFP where PEOSolutions::165 signifies the Client Master Import ID, 20240101 signifies Benefits Batch Effective Date and RFP signifies the Benefits Batch Type.

For the Benefit Group form:

  • The rule is triggered when Client Master Import ID and Benefit Groups Group Code are not empty and either of these fields is updated.

  • If any of the required values are empty, the Import ID field is empty.

  • The Import ID is created by combining the Client Master Import ID and Group Code values.

  • The ImportID follows the format {ClientMaster.ImportID}- {OfferedPlanClassification.ClassificationCode}.

     

    Note: The OfferedPlanClassification.ClassificationCode is the Group Code on the Benefit Groups form.

     

    Example: PEOSolutions::165-Main where PEOSolutions::165 signifies the Client Master Import ID and Main signifies the Group Code value from the Benefit Groups form.

For the Employee Benefit Detail form:

  • The rule is triggered when Client Master Import ID and Employee Identifier are not empty and the Plan ID, Effective Date, IsActive checkbox, Employee ID or Client Master Import ID is updated.

  • If any of the required values are empty, the Import ID field is empty.

  • The Import ID is created by combining the Client Master Import ID, Employee Identifier, Plan ID and Effective Date values.

  • The ImportID follows the format {ClientMaster.ImportID}- {Employee Identifier} - {Plan ID} - {Effective Date}.

     

    Example: PEOSolutions::165-D456477-645-20240423 where PEOSolutions::165 signifies the Client Master Import ID, D456477 signifies the Employee Identifier from the Employee record, 645 signifies the Plan ID from the Employee Benefits Detail form and 20240423 signifies the Effective Date from the Employee Benefits Detail form.

How the PrismHR link works

When you click the PrismHR link on the Workspace Landing page to connect to PrismHR, ClientSpace uses the PEOID field value from the workspace's Client Master dataform to identify the correct PrismHR instance to log into.

How searching for clients works in a multi-tenant environment

Since the Client Number will not always be unique across the PrismHR databases in a multi-tenant environment. The PEO ID serves as a secondary ID that you can use to filter by on the following module dashboards:

  • Cases

  • Clients

  • Employees

  • WC Claims

  • UI Claims

  • Benefits Batch Search

Note: Even if the PEO ID is not unique, a search that includes the PEO ID may help to narrow your results.

The PEO ID field in the More search of these dashboards is a Text datatype field. You must type the entire PEO ID when filtering. The search requires an exact match to return results.

You can also add the PEO ID column to these dashboards. By default, the PEO ID column is hidden. Add it by clicking the vertical three dot (i.e., Kebab) icon on any column heading and selecting PEO ID on the Columns list: