AX1283

Managing users in Axiom Security using Save Type 4

Using Save Type 4, you can create or edit Axiom users by using save-to-database within a spreadsheet, rather than using the security administration tools. This may be a more convenient approach if you need to create or edit users as part of an automated process.

NOTE: Although both features allow security edits within a spreadsheet environment, Save Type 4 is intended to be used for a different purpose than Open Security in Spreadsheet. Open Security in Spreadsheet is a system-controlled environment that is intended for one-time edits to security. Save Type 4 is intended to handle custom security management needs, such as automating ongoing security updates based on external sources.

Save Type 4 depends on the placement of save-to-database tags within the sheet. There are three components:

  • The primary SaveStructure2DB tag, which defines the locations of the save-to-database control row and control column, and specifies the desired operation.
  • Column tags in the save-to-database control row, to specify the columns which hold the user properties.
  • Row tags in the save-to-database control column, to flag rows to be saved.
Save-to-database tag summary
Tag Type Tag Syntax

Primary tag

[SaveStructure2DB;Axiom.Principals;CustomSaveTag=Name]

Row tags

[Save]

Column tags

Any supported user property exposed from Axiom.Principals.

NOTES:  

  • Save Type 4 must be enabled for the sheet on the file's Control Sheet in order for the save process to occur. For more information, see Using Save Type 4.
  • Only general user properties and table-related security permissions (from the Tables tab of security) can be modified using Save Type 4.
  • The user performing the save must be an administrator or have the Administer Security permission. Subsystem administrators cannot create or edit users using Save Type 4.

Placing the primary save-to-database tag in the sheet

To define the save-to-database process, place the following tag in any cell in the sheet, within the first 500 rows:

[SaveStructure2DB;Axiom.Principals]

The row containing SaveStructure2DB becomes the control row, and the column containing SaveStructure2DB becomes the control column.

You can also optionally use the custom save tag parameter. For example:

[SaveStructure2DB;Axiom.Principals;CustomSaveTag=SaveUser]

NOTES:  

  • The primary SaveStructure2DB tag must be located in the first 500 rows of the sheet.

  • The SaveStructure2DB tag can be placed within a formula, as long as the starting bracket and identifying tag are present as a whole within the formula. For more information, see Using formulas with Axiom feature tags.

Defining the user properties in the control row

Within the control row for the save-to-database process, specify the columns that define the user properties by placing the reserved names from Axiom.Principals in any column. The column tags can be placed to either the right or the left of the SaveStructure2DB tag. See Axiom.Principals for a full list of user properties.

At minimum, you must include the following properties in the control row to create a new user. All other user properties will use the default value if omitted from the save.

  • PrincipalID (set this to 0; the ID will be automatically assigned when saving)
  • LoginName
  • FirstName
  • LastName
  • EmailAddress

NOTE: If PrincipalID is set to 0 but the LoginName matches an existing user name, then that existing user will be updated instead of creating a new user. If you intentionally have duplicate user names across different domains then you must also include the Domain to differentiate them.

When updating an existing user, you must include the LoginName and the PrincipalID in the save to identify the user to update (and also the Domain if there may be duplicate user names across different domains). You can modify any of the following user properties:

  • LoginName
  • FirstName
  • LastName
  • EmailAddress
  • Domain
  • Password
  • AuthenticationType (Windows User, LDAP Prompt, Axiom Prompt, OpenID, SAML)
  • IsSyncEnabled
  • UserLicenseType (Standard, Viewer, AxiomStaff)
  • IsEnabled
  • IsAdmin
  • RoleIDList or RoleNameList (use one or the other; if both are included then RoleIDList will be used)
  • Subsystems
  • TableType and Table permission columns (as detailed in Axiom.Principals)

The control row must be dedicated to containing only valid column names for the Save Type 4 operation to the target table. Any invalid entries in the control row will cause an error when saving.

NOTES:  

  • If the Password field is included in the save-to-database control row and it contains any non-blank value, that value will always be saved, even if no change has been made. If you are not making changes to the Password field, then you should not include it in the control row.

  • If you include a TableType or Table permission column in the control row but leave it blank in the save, this is interpreted as setting the permission to no access. If instead you want the user to default to no configured permission for the table or table type, then you should either not include the column in the control row, or include it but set the value to NotConfigured.

  • If an administrator user is disabled using Save Type 4, the administrator permission is automatically removed from that user.

IMPORTANT: For performance reasons, only a small number of table and table type filters are validated when creating or editing users via Save Type 4. Additionally, any text in table or table type permission columns that does not match the reserved permission values (such as NotConfigured or FullAccess) is interpreted as filter text. Use caution when setting up and using this feature as it can be quite easy to save invalid filters. It is recommended to run the Validate Security Filters utility after saving, to catch any invalid filters. This utility can be run using the Run QA Diagnostics command. For more information, see Using file diagnostics for troubleshooting and optimization.

Flagging the rows to be saved

Within the control column for the save-to-database process, mark each row that you want to be saved with a [Save] tag. This is the only valid tag for the security save. Users cannot be deleted using Save Type 4.

If you have defined a custom save tag in the SaveStructure2DB tag, then you must mark the rows with that tag instead of the default tag. For example, if your primary tag is [SaveStructure2DB; Axiom.Principals; CustomSaveTag=MySave] then you would place the tag [MySave] in the rows that you wanted to be saved.

Only rows that are marked with a valid tag are processed; all other rows are ignored, even if there is content in the property columns. If a row contains a valid tag but no content exists in the property columns, a save error will occur.

NOTE: The row tag can be placed within a formula if desired.

Populating the user properties in the spreadsheet

In the property columns, enter the relevant user properties for each Axiom Software user that you want to create or update. Typically this process would be automated by using an Axiom query, either to the Axiom.Principals table to bring in properties for existing users, or to another table stored in the system for purposes of automating user management.

For example, you might have an import utility that imports user data from an external system to a "staging" table in the Axiom Software database. You can then query the user data from the staging table into your Save Type 4 report. The report can contain calculations to determine which users should be created or edited and what their settings should be. You can then run the save-to-database against the Axiom.Principals table to create or edit the users. The entire process could be automated via a Scheduler job so that the import runs first, then the report is processed.

See also