Archer

1. Overview and Prerequisites

The Archer integration is a one-way pull: data flows from Archer into RegScale. No writes are made back to Archer.

Three sync commands ship today:

Prerequisites:

• RegScale CLI installed and regscale init completed (creates init.yaml).
• Archer credentials and base URL available.
• Run regscale archer login to validate credentials before running sync commands. The login command reads the same init.yaml keys and confirms the Archer session token can be obtained.
• The Archer Content API (OData) is used to read application records.

2. Configuration (init.yaml)

Add the following keys to your init.yaml. All keys can also be set as environment variables (case-insensitive exact name or UPPER_SNAKE_CASE). Environment variables take precedence over init.yaml values.

Example init.yaml block (mirrors init.yaml.example):

archerBaseUrl: https://archer.example.com/RSAarcher
archerInstanceName: Default
archerUsername: ''
archerPassword: ''
archerUserDomain: ''
archerSslVerify: 'true'
archerMappingFile: ''

3. Mapping File

Resolution Order

The integration resolves the mapping file in priority order (first match wins):

1. CLI flag -m / --mapping_file — explicit path passed at runtime.
2. init.yaml key archerMappingFile — path configured globally.
3. Bundled default — regscale/integrations/commercial/archer/mappings/default_archer_mappings.json inside the installed package.

JSON Anatomy

The mapping file is a single JSON object with one top-level key per entity: controls, issues, evidence, and workflows. Each entity has three keys:

Default Mapping

The bundled default (mappings/default_archer_mappings.json) assumes standard Archer application and field names. Copy and edit it for customized Archer environments:

{
  "controls": {
    "application": "Controls",
    "fields": {
      "controlId": "Control ID",
      "title": "Control Name",
      "status": "Implementation Status",
      "description": "Control Description"
    },
    "value_maps": {
      "status": {
        "Implemented": "Fully Implemented",
        "Partial": "Partially Implemented",
        "Not Implemented": "Not Implemented"
      }
    }
  },
  "issues": {
    "application": "Findings",
    "fields": {
      "title": "Finding Title",
      "severity": "Severity",
      "status": "Status",
      "description": "Description",
      "dueDate": "Remediation Date"
    },
    "value_maps": {
      "severity": {"Critical": "Critical", "High": "High", "Medium": "Medium", "Low": "Low"},
      "status": {"Open": "Open", "Closed": "Closed"}
    }
  },
  "evidence": {
    "application": "Evidence",
    "fields": {"title": "Title", "description": "Description"},
    "value_maps": {}
  },
  "workflows": {
    "application": "Workflows",
    "fields": {"name": "Workflow Name", "status": "Status"},
    "value_maps": {}
  }
}

To customize, copy the file and pass its path via -m or set archerMappingFile in init.yaml.

4. RegScale Field Reference

4.1 Controls → ControlImplementation

Important behavior: sync_controls updates the status of ControlImplementations that already exist on the plan. It does not create new ControlImplementations. Archer control records are matched to existing implementations by control label (the controlId field value is matched against the RegScale control's label). Controls present in Archer but not on the plan are logged and skipped.

ControlImplementationStatus valid values:

The value in the status field of your mapping file (the right-hand side of the value_maps.status object) must be one of the string values above.

4.2 Issues → Issue

Issues are routed to create (new record) or update (existing record) by otherIdentifier. New records are created with parentId = the -id plan argument and parentModule = "securityplans".

Auto-set fields (not user-mapped):

IssueSeverity valid values (canonical long-form):

Use either the short alias (e.g. Critical) or the full canonical string in your value_maps.severity. The Issue model normalizes both to the canonical form automatically.

IssueStatus valid values:

4.3 Evidence → Evidence

Important behavior: RegScale Evidence is tenant-wide — it is not scoped to a security plan. The -id plan argument is accepted by sync_evidence for CLI consistency with the other sync commands, but it does not scope the evidence records created or updated. Evidence is deduplicated by title (per-item create-or-update). File attachments are not synced (future enhancement — metadata only).

5. Value Maps

The value_maps section in the mapping file translates Archer display values to RegScale field values. When a value_map exists for a field:

• If the Archer value is in the map, the mapped RegScale value is used.
• If the Archer value is not in the map, the record is logged and skipped — no default value is substituted.

When no value_map exists for a field (the key is absent from value_maps), the Archer value is passed through to RegScale unchanged.

Example: extending a value map

Suppose your Archer "Findings" application uses a severity field with values P1, P2, P3, P4. Add them to the value_maps.severity object:

"value_maps": {
  "severity": {
    "P1": "Critical",
    "P2": "High",
    "P3": "Medium",
    "P4": "Low"
  },
  "status": {"Open": "Open", "Closed": "Closed"}
}

Any Archer finding with a severity value not in the map (e.g. P5 or blank) will be logged as unmapped and skipped.

6. Commands

All Archer commands are under the archer group:

regscale archer login
regscale archer sync_controls  -id <plan_id>  [-m <mapping_file>]
regscale archer sync_issues    -id <plan_id>  [-m <mapping_file>]
regscale archer sync_evidence  -id <plan_id>  [-m <mapping_file>]

regscale archer login

Validates credentials by obtaining an Archer session token. Exits with an error message if authentication fails. Run this first to confirm configuration is correct before running sync commands.

regscale archer sync_controls

Options:
  -id, --regscale_ssp_id INTEGER  Target RegScale Security Plan ID.  [required]
  -m, --mapping_file TEXT         Path to a custom Archer mapping JSON (overrides default).

Reads control records from the Archer application named in mapping.controls.application, matches each to an existing ControlImplementation on the plan by control label, and updates its status. Prints a summary on completion:

Archer controls synced -- created=0, updated=12, skipped=3

created is always 0 for controls — this command updates only.

regscale archer sync_issues

Options:
  -id, --regscale_ssp_id INTEGER  Target RegScale Security Plan ID.  [required]
  -m, --mapping_file TEXT         Path to a custom Archer mapping JSON (overrides default).

Reads finding records from the Archer application named in mapping.issues.application. Routes each record to create (new Issue) or update (existing Issue) based on otherIdentifier = Archer record ID. Prints a summary:

Archer issues synced -- created=5, updated=18, skipped=2

regscale archer sync_evidence

Options:
  -id, --regscale_ssp_id INTEGER  Target RegScale Security Plan ID (context only — evidence is tenant-wide).  [required]
  -m, --mapping_file TEXT         Path to a custom Archer mapping JSON (overrides default).

Reads evidence records from the Archer application named in mapping.evidence.application. Creates or updates tenant-wide Evidence records deduplicated by title. Because Evidence has no batch endpoint, the create/update split is not reported — all submitted records appear under created:

Archer evidence synced -- created=8, updated=0, skipped=1

7. Worked Example

Scenario: Your Archer instance uses an application called "Findings" with field names "Finding Title", "Priority" (instead of "Severity"), "Resolution Status" (instead of "Status"), and "Due Date". Priority values are P1–P4; resolution status values are Active and Resolved.

Step 1: Copy the default mapping and customize.

Save the default JSON to ./my_archer.json and edit the issues section:

{
  "controls": {
    "application": "Controls",
    "fields": {
      "controlId": "Control ID",
      "title": "Control Name",
      "status": "Implementation Status",
      "description": "Control Description"
    },
    "value_maps": {
      "status": {
        "Implemented": "Fully Implemented",
        "Partial": "Partially Implemented",
        "Not Implemented": "Not Implemented"
      }
    }
  },
  "issues": {
    "application": "Findings",
    "fields": {
      "title": "Finding Title",
      "severity": "Priority",
      "status": "Resolution Status",
      "description": "Description",
      "dueDate": "Due Date"
    },
    "value_maps": {
      "severity": {
        "P1": "Critical",
        "P2": "High",
        "P3": "Medium",
        "P4": "Low"
      },
      "status": {
        "Active": "Open",
        "Resolved": "Closed"
      }
    }
  },
  "evidence": {
    "application": "Evidence",
    "fields": {"title": "Title", "description": "Description"},
    "value_maps": {}
  },
  "workflows": {
    "application": "Workflows",
    "fields": {"name": "Workflow Name", "status": "Status"},
    "value_maps": {}
  }
}

Step 2: Run the sync against plan 42.

regscale archer sync_issues -id 42 -m ./my_archer.json

Example output:

Archer issues synced -- created=5, updated=18, skipped=2

Skipped records (e.g. those with unmapped priority values) are logged at WARNING level with the Archer record ID for investigation.

8. Idempotency and Re-runs

The integration is safe to re-run. No records are deleted.