Destination Adapter: PayAnalytics Users

Description

The PayAnalytics Users destination adapter allows you to sync a user database with PayAnalytics. The input for the adapter is a data frame consisting of one or more rows per user. The PayAnalytics Users adapter performs the following operations:

• Creates new users if they exist in the users data frame and not in the PayAnalytics user list
• Detects if user configuration has changed between the users data from and the PayAnalytics user list and applies changes as needed.
• Mark users as inactive in the PayAnalytics user list if they exist in the list but not in the users data frame.

Authentication

You need to provide your PayAnalytics API key as a secret so the DataBridge Engine Pipeline can authenticate against PayAnalytics. You can retrieve the key through the PayAnalytics web interface.

Configuration

Required Parameters

To use this adapter, set the adapter configuration attribute to payanalytics_users.

instance_url (string)

Your PayAnalytics instance URL.

permissions_data_frame (string)

Name of the dataframe containing user permissions data.

api_token_secret_name (string)

Name of the secret containing your PayAnalytics API token.

user_field_map (object)

Configuration for mapping source fields to PayAnalytics fields.

Field Mappings

username (string)

Which field in the permissions_data_frame contains a username.

email (string)

Which field in the permissions_data_frame contains an email address.

first_name (string)

Which field in the permissions_data_frame contains the first name of the user.

last_name (string)

Which field in the permissions_data_frame contains the last name of the user.

user_templates (dictionary, template_name -> template_definition)

Templates that are used as basis for permissions.

Example:

The following example is very minimal, only providing the is_superuser value with the remaining values set to the default value (the default value is always the value providing fewer permissions).

{
  "admin": {"is_superuser": true},
  "normal": {"is_superuser": false}
}

The values admin and normal would be passed as a value in the user_template_field for each respective user.

A full list of attributes is defined in the below as a TypeScript interface:

interface UserTemplate {
  is_superuser?: boolean;
  is_active?: boolean;
  role_id?: number;
  authz_allow_audit_log?: boolean;
  authz_per_record_filter_grant_all?: boolean;
  authz_per_record_filter_reference_dataset?: number;
  authz_per_column_filter_grant_all?: boolean;
  authz_per_column_filter?: string[];
  authz_per_column_filter_system_fields?: string[];
  authz_per_column_filter_reference_dataset?: number;
  authz_per_dataset_filter_grant_all?: boolean;
  authz_per_benchmarking_filter_grant_all?: boolean;
  authz_per_raise_restriction_filter_grant_all?: boolean;
  authz_per_job_evaluation_filter_grant_all?: boolean;
  authz_per_job_config_grant_all?: boolean;
  authz_per_compensation_assistant_preset_grant_all?: boolean;
  authz_allow_per_record_details?: boolean;
  authz_allow_upload_data?: boolean;
  authz_allow_delete_dataset?: boolean;
  authz_allow_modify_dataset_labels?: boolean;
  authz_allow_modify_analysis_labels?: boolean;
  authz_allow_modify_benchmarking_labels?: boolean;
  authz_allow_modify_raise_restriction_labels?: boolean;
  authz_allow_modify_job_evaluation_labels?: boolean;
  authz_allow_modify_job_config_labels?: boolean;
  authz_allow_modify_compensation_assistant_preset_labels?: boolean;
  authz_allow_run_analysis?: boolean;
  authz_allow_change_currency_tables?: boolean;
  authz_allow_change_system_parameters?: boolean;
  authz_allow_run_taskrunner_tasks?: boolean;
  authz_allow_create_api_token?: boolean;
  authz_allow_view_modify_taskrunner?: boolean;
  authz_allow_task_runner_filter_grant_all?: boolean;
  authz_allow_modify_employee_group_labels?: boolean;
  authz_allow_employee_group_filter_grant_all?: boolean;
  authz_allow_compensation_assistant_create_public_result?: boolean;
  visible_compensation_assistant?: boolean;
  visible_compensation_assistant_benchmarking_data?: boolean;
  visible_compensation_assistant_comparison_histogram?: boolean;
  visible_compensation_assistant_comparison_aggregates?: boolean;
  visible_compensation_assistant_predicted_breakdown?: boolean;
  authz_allow_custom_compensation_assistant_analysis?: boolean;
  visible_job_evaluations?: boolean;
  visible_dataset_overview?: boolean;
  visible_compensation_brackets?: boolean;
  visible_benchmarking_data?: boolean;
  visible_labels?: boolean;
  /**
   * authorized_label_entries: A list entries specifying label ids. Example: [[1,2],[3]] indicates
   * that user should have access to resources (e.g. datasets) marked with labels:
   * - id: 1 AND id: 2
   * OR
   * - id: 3
   * See mapping from label names to label id's on the endpoint:
   *     https://<tenant>.payanalytics.com/api/v1/labels/
   */
  authorized_label_entries?: number[][];
}

It may be helpful to visit the url https://<instance-name>.payanalytics.com/api/v1/settings/users/ where you can view the user configuration for existing users.

user_template_field (string)

The field in the provided users dataset that contains the respective name of the user template (e.g. admin or normal)

Example value: Role. The Role field has to exist on the provided dataset and would contain the value admin or normal to match the example for user_templates provided above.

per_record_filter_field (string, optional)

The field in the provided users dataset that contains the name of the field to use for per-record access filtering.

Example value: Country

exempt_users (string[])

A list of usernames that are ignored by the user integration pipeline.

Example: ['api-user']

send_invite_to_new_users (boolean)

Whether to send an invitational email to newly created users.

authorized_labels_field (str or null)

A field in the users dataset that contains label configuration. Multiple rows are allowed per user where each row can contain multiple labels separated with the pipe character (|). For a user to have access to a resource, all labels separated by a pipe character need to be applied to the resource.

Multiple rows with non-empty value in the authorized_labels_field indicates an OR relationship, e.g.:

Row 1: Spain|Official Row 2: France|Testing Row 3: Romania

The rows above suggest that user can access resources with the following label arrangement:

(Spain AND Official) OR (France AND testing) OR (Romania)

A configuration through authorized_labels_field is appended (using OR relations) to what is specified in the authorized_label_entries of the user template.

Configuration Examples

Basic Configuration

{
  "version": 1,
  "destination_adapters": [
    {
      "adapter": "payanalytics_users",
      "configuration": {
        "instance_url": "my-instance.payanalytics.com",
        "api_token_secret_name": "my-api-key",
        "permissions_data_frame": "user_permissions",
        "user_field_map": {
          "username": "WorkerId",
          "email": "Email",
          "first_name": "GivenName",
          "last_name": "FamilyName"
        },
        "user_templates": {
          "Admin": {"is_superuser": true},
          "Global":  {"role_id": 1},
          "Local":  {"authz_allow_upload_data": true, "authz_per_record_filter_grant_all":  false}
        },
        "user_template_field": "Template",
        "per_record_filter_field": "Country",
        "exempt_users": ["api-user"],
        "send_invite_to_new_users": false,
        "authorized_labels_field": "AccessLabels"
      }
    }
  ]
}

With a dataset on the following format:

WorkerId	Email	GivenName	FamilyName	Template	Country	PerRecordField	AccessLabels
john	john@example.com	John	Doe	Admin
jane	jane@example.com	Jane	Dee	Local	France	Country
jane	jane@example.com	Jane	Dee	Local	Spain	Country
harry	harry@example.com	Harry	Smith	Local	Spain		Official
harry	harry@example.com	Harry	Smith	Local	Spain		Testing|EU

This will configure users as follows:

John is configured according to the Admin template (is_superuser: true).

Jane is configured according to the Local template. Additionally she has a per-record filter active and only sees records where the "Country" field in the dataset has either of the following values:

• France
• Spain

Harry will only see datasets with the following label configuration:

• Official OR
• Testing AND EU (both labels applied)