Editing dimensions in the security schema file

If you're not using security dimension values providers, modifying the security dimensions of a deployed i2 Analyze server means editing the security schema file. After you change the security dimensions, you might also need to update the data in your system.

About this task

To modify the display name or the description of a dimension or a dimension value, you change the DisplayName or Description attributes of an existing <Dimension> or <DimensionValue> element. Do not change the value of the Id attribute.

To add a security dimension value to a security dimension, you add a <DimensionValue> element as a child of an existing <Dimension> element.

To remove a security dimension value from a security dimension, you remove the corresponding <DimensionValue> element.

Note: If the deployment contains records with dimension values that you remove, users of i2 Analyze client software see those values marked as suspended in the user interface. They don't contribute to access level calculations and cannot be assigned to records unless you restore them.

If you follow this procedure in a deployment that provides high availability, you must complete each step on every Liberty server in your environment before you move to the next step.

Procedure

Edit the security schema:

Using an XML editor, open the security schema file for the deployment.
The security schema file is in the toolkit\configuration\fragments\common\WEB-INF\classes directory. The name of the file is specified in the DynamicSecuritySchemaResource property of the ApolloServerSettingsMandatory.properties file in the same directory.
Modify the security dimensions in the security schema file according to your requirements.
Remove or edit any security permissions that refer to dimension values that are no longer in the schema. Add security permissions for any dimension values that you added.
Check the updated schema to ensure that it remains possible for all users to get the "Read only" or "Update" access level for at least one value in every dimension.
Increment the version number that is stated in the Version attribute of the <SecurityDimensions> element in the security schema file.
Save and close the file.

Redeploy i2 Analyze to update the application with your changes:

In a command prompt, navigate to the toolkit\scripts directory.
Stop Liberty:
```
setup -t stopLiberty
```
If you completed a change that requires a reindex, clear the search index:
```
setup -t clearSearchIndex --hostname <liberty.hostname>
```
In a deployment that provides high availability, you only need to run this command on one Liberty server.

Update and redeploy the system:

setup -t updateSecuritySchema
setup -t deployLiberty

Start Liberty:
```
setup -t startLiberty
```

What to do next

If your changes to the security schema included removing dimension values, records with those values remain in the system. The records might be in the Information Store as a result of ingestion or user upload; or they might be on charts that users have created. The removed values are not harmful, but they are potentially confusing, and you should try to delete them from existing data.

For system-governed records that you add to the Information Store through an ETL pipeline, you can modify the ingestion mappings so that the removed values are no longer used, and then ingest the records again. Records on users' charts are updated automatically when they connect to the server.

For analyst-governed records that users create, users who inspect the security settings of a record see (suspended) after the name of any dimension value that you removed. If they have "Update" access to the record, they can edit its security settings to deselect suspended values and select new ones as appropriate.

Whenever you make changes to the security schema, keep your users' experience in mind, and inform them of any changes they'll see (or need to make) as a result.