SmartBox Data Access Overview

To use SmartBox Data Access in your environment the following is required:

• The K2 database must be installed on Microsoft SQL Server 2016 (running in compatibility mode 130 or higher), or Microsoft SQL Azure (running in compatibility mode 130 or higher).
• To create, enable, disable and delete policies, you must be a member of the Security Administrators role which is a built-in system role that manages SmartBox Data Access policies.
• Data Access policies can only be created on basic SmartBox Objects and not Advanced SmartBox Objects.

A Data Access policy provides security at the database level so when a user, group or role is a member of a policy, they can access the data of a SmartBox SmartObject in a K2 application.

When creating a policy on a SmartBox SmartObject in K2 Management, three options are available:

• Full Data Access: Users, groups and roles can access all data of SmartBox SmartObjects. See the Understanding Full Data Access topic for more information.
• Limited Data Access: Users, groups and roles can access a subset of the data in a SmartBox SmartObject, based on property values. See the Understanding Limited Data Access topic for more information.
• Included SmartBox Objects: Allows you to extend your policy to associated child SmartBox SmartObjects. See the Understanding Included SmartBox Objects topic for more information.

Data Access Policy Guidance and Scenarios

• In general, use a Limited Data Access policy when you have a single SmartBox SmartObject that has a single association to a SmartBox object containing data that everyone can see, such as a list of regions around the world, such as in Understanding Limited Data Access. Limit data access by region in this scenario.
• Use an Included Data Access policy when you have multiple, associated SmartBox SmartObjects containing related data that cascades, such as in the SalesQuote and SalesQuoteLineItem example in Understanding Included SmartBox Objects
• You can use a combination of these approaches as well, limiting data at the higher lever (by region in the example) and including the data access policy for lower-level associations.

Below are scenarios of data access policies you can configure. Say that you have the following SmartBox SmartObjects deployed:

• Region
  • Country
    • State
  • Customer
    • SalesQuote
      • SalesQuoteLineItem
    • SupportTicket
      • SupportTicketAttachment

In this scenario you create two Data Access policies:

Policy #1
Secured object = SalesQuote
Secured by = Region
The SalesTeam-Asia role can see sales quotes for Asia, while the SalesTeam-Managers role has full access to all SalesQuotes. You extend this down to SalesQuoteLineItem so that only sales people can see quotes, not everyone on the Customer Success team.

This is the policy created as an example in Understanding Included SmartBox Objects.

Policy #2
Secured object = Customer
Secured by = Region
The CustomerSuccessTeam-Asia role can only see customers in Asia, while the CustomerSuccessTeam-Managers role has full access. You extend this policy down to SupportTicket and also to SupportTicketAttachment, using Included SmartBox Objects, as you want everyone on the customer success team for that region to see and respond to support tickets.

Full Data Access

The Full Data Access option allows users, groups and roles to have access to all data in a SmartBox SmartObject at runtime. To a create policy with Full Data Access see the Data Access topic for more information.

For the purpose of this example, the Customer Success Manager must have access to view data on all regions and countries in which their customers reside. Anthony, the Global Customer Success Manager needs to be able to view all data from the Customers SmartBox SmartObject at runtime. To achieve this, Anthony needs to part of a Data Access Policy which has Full Data Access on the Customers SmartBox SmartObjects.

Adding Anthony to Full Data Access section in the policy Customers SmartBox SmartObject allows him to see all data contained in the Customers SmartBox SmartObjects.

Limited Data Access

The Limited Data Access option allows users, groups and roles to access a subset of data in SmartBox SmartObjects. To a create policy with Limited Data Access see the Data Access topic for more information.

There are three options available in the Limited Access section:

• None: No item-level security.
• This SmartBox object:[SmartBox Object]: Select this option to restrict access to properties of the current SmartBox SmartObject.
• Another SmartBox object: [Set]: Select this option to populate a list of associated SmartBox SmartObjects.

After you choose an option, in this case the Another SmartBox object: [Set] option is chosen, select the Region SmartBox Object. You want Bob, who is the member of the Customer Success Team - Asia role to only see data for the Asia region on the Customers SmartBox Object. Select Asia and add the Customer Success Team - Asia role .Once the role is assigned to a property value, the members of the role (Bob) can only see the data of the assigned property value, in this case Asia, at runtime. You can add users, groups or roles to SmartBox Object properties. You can then determine the display properties of the SmartBox Object by clicking the Display Properties... link.

As shown below, the Customer Success Team - Asia role is added to the record in the Customers SmartBox SmartObject and is secured by the Region SmartBox Object's Asia property. This means that Bob, who is a member of the Customer Success Team - Asia can only see data for the Asia region of the Customers SmartBox Object at runtime.

Limited Data Access Considerations

When configuring limited data access in your policy, certain types of associations do not appear in the returned list of associations when you select the Another SmartBox object : [Set] option:

• The parent object in the association does not have a key field.
• The association maps a non-key field from the parent object to a field on the child object.
• The association maps a key field from the parent object to a field on the child that is a different data type.
• The association maps a key field from the parent object to a field on the child that is the same type but a different size, for example, if text max length is 100 on the parent field and 50 on the child.
• The mapped field on the child is encrypted (key fields on the parent cannot be encrypted).
• The parent object contains multiple key fields but the association only maps one field to the child.
• The parent object contains multiple key fields and the association maps to multiple fields on the child, but one or more of the child fields have a different data type than the corresponding parent field.

• If the secured by SmartBox Object is already part of a Data Access policy, you may not see all the data if you have Limited Data Access on that SmartBox Object.

Included SmartBox Objects

The Included SmartBox Objects option allows you to extend your Data Access policy to associated SmartBox SmartObjects. You can also include or exclude the current SmartBox Object from your policy. To extend a policy to associated SmartBox Objects see the Data Access topic.

Use the following information and guidance to determine how to use Data Access on SmartBox SmartObjects. Also see the Considerations section below for more details and known issues.

• The SmartObject is open until you add data access security, and then the data can only be accessed by those who are part of the policy.
• You must include the K2 Package and Deployment role, which is added by default, to every SmartObject you secure if you want to be able to create packages that include the data in those SmartObjects as part of the deployment.
• The Everyone role is added by default, but typically you want to remove this role immediately and add another role (such as this custom one, Headquarters) as shown here:
  
• If you do not remove the Everyone role, configuring limited data access has no effect because all authenticated users receive access to all data.
• If you do not have Full Access and you are trying to configure an enabled Limited Access policy, you will see a No Data Found message as in the following image:
  
• The records you can see in the Limited Access dialogs are filtered by the active Data Access policy, which means you may see the No Data Found message if you don't have access to the data.
• If you need to limit records to a particular item contained in an association, such as limiting the list of Countries to a particular Region, configure limited data access security on the Country SmartObject by choosing the Region SmartObject. A Country can have only one Region, but a Region can have many Countries.
• If you further wanted to limit the list of regions by user, group or role, you would configure limited data access on the Region SmartObject (Default: Region) and typically configure the same users, groups, and roles for particular regions that you did for your Country SmartObject.
• To remove a limited data access policy, click None and confirm to delete it. Alternatively, you can disable the policy if you want to remove it temporarily, but you will not be able to add a new Data Access policy to the SmartObject or any associated SmartObjects that the disabled policy uses.
• You must create a policy and enable it for it to take effect. Any changes to a policy are applied immediately.

• If you are a member of the Security Administrators role, you can create Data Access policies, but you may not see data if you do not have full or limited data access.
• You can only apply a SmartBox Data Access policy to basic SmartBox SmartObjects.
• You can not apply a policy to Composite and Advanced SmartBox SmartObjects.
• You can apply only one policy per SmartBox SmartObject.

• If you create a policy containing a user who is a member of the Full Data Access and Limited Data Access sections, the Full Data Access configuration is the effective access for that user.

• You can only create a Limited Access policy on your SmartBox SmartObject using data in your SmartBox SmartObject, or in data in an associated parent SmartBox SmartObject via a Many to One relationship. You can extend a policy to child SmartBox SmartObjects with either a One to One association or a One to Many association from the SmartBox SmartObject you have created the policy on. You cannot use SmartBox SmartObjects associated via Many to Many associations, or SmartBox SmartObjects that have multiple Key properties.
• If a SmartObject has a limited data access policy defined, and someone tries to save data for a record that they do not have access rights to, they receive an error “Violation of PRIMARY KEY Constraint [name]. Cannot insert duplicate key in object [ObjectName]…”. While the error message does not clearly describe the cause of the error, this is expected behavior since users should not be able to save data for records that they do not have access to.
• When someone tries to delete a record that is being used to secure data in another record, they receive an error “The DELETE statement conflicted with the REFERENCE constraint [ConstraintName]. The conflict occurred in database “K2”…”. To address the issue, you must remove the Data Access Policy entry for SmartBox record that is being used by the policy, and then delete the record.
• You may not be able to create a Data Access Policy on a SmartBox object that has two or more key properties. When you attempt to define a policy on a SmartBox SmartObject with two or more key properties, you may encounter an error “Error executing compiled Sql from Policy Compiler GenerateSetSecuredBy method”.
• When you attempt delete a SmartBox object that has a policy, you may encounter an error “SmartObject Server Exception: Error: The SmartBox Object [SmartObjectName] is part of an existing policy”. This error occurs when a data access policy is applied to a SmartBox SmartObject and someone tries to delete the SmartObject. To delete the SmartObject, you must disable the policy first, and then delete the SmartObject.
• If someone is viewing data for a SmartBox Object in a list view, and you implement a policy that prevents them from seeing the data while they still have the view open, they get an error when they re-load the list view for the first time. The error says “Binding for the non-schema bound security predicate on object [ObjectName] failed with one or more errors…”. This issue only happens in a Microsoft SQL Server 2016 environment where SQL Server Service Pack 1 or later is not installed. You can either ignore the error and refresh the list, or you can install the service pack to avoid this error message.
• When you attempt to setup a policy on SmartBox Objects that have associations with non-unique keys, you receive the error: Error converting data type nvarchar to bigint. Error converting data type nvarchar to bigint. To resolve this issue, bind the SmartObject association to a property that is a number or unique key.
• When you attempt to extend a Data Access policy to associated SmartBox Objects using the Included SmartBox Objects option that are already part of an existing policy, the associated object is locked on the Add Associated SmartBox Object page, with the following message: The SmartObject is already in use by a policy. The message is displayed even when the SmartBox Object is part of a policy that is disabled.
  
• When you attempt to create a Data Access policy on a SmartBox Object that is already part of policy (via the Included SmartBox Objects option) the following message is displayed when viewing the Data Access tab of that SmartBox Object: The [SmartBox Object Name] SmartObject is already secured by a Data Access policy on the [SmartBox Object Name] SmartObject. The message is displayed even when the SmartBox Object is part of a policy that is disabled.
  
• When you modify a simple SmartBox Object that already has a Data Access policy, changing it to an Advanced SmartBox Object by adding non-SmartBox Properties or methods to it, when you try to save the object in K2 Designer, the following error is displayed: You cannot make this an Advanced SmartObject unless you delete its Data Access policy. Contact your K2 administrator.