Module Navigation

Troubleshooting CMiC Integration Error: Connector Configuration Missing or Invalid

This family of messages appears when the CMiC connector's own configuration is missing a value, holds a value CMiC cannot accept, or holds a value that is too long. Unlike most CMiC errors, these are almost never about a your employee data. They mean something on the connector's configuration page is blank, invalid, too long, or does not match how your CMiC companies are set up.

Two messages in this group are different from the rest. One is not a problem at all: it is expected when a sync is run in a mode that does not save changes. The other sits between this family and org structure: it occurs when an employee's work location does not match the companies configured on the connector.

Error Messages

Message textDirectionOccurs whenOutcomeFix
CMiC Provider could not read the configuration setting '[setting name]'. (constructor-read settings)Read and WriteOne of the connector's constructor-read settings is missing or blank. See the setting table below for the full list of names that can appear here.Recorded, not thrown immediately. Surfaces through connector validation: on Test Connection it comes back as a validation message. In a live sync run it is collected with any other validation issues and thrown together right after authentication succeeds, stopping the sync step before any employee is read or written.Fill in the named setting on the connector configuration, then re-run Test Connection.
CMiC Provider could not read the configuration setting '[setting name]'. (authentication settings)Read and WriteOne of the connector's authentication settings is missing or blank: CMiC Service URL always; OAuth URL, OAuth Client ID, and OAuth Secret for OAuth configurations; CMiC UserName and CMiC Password for Basic auth configurations.Raised immediately, before any credential exchange happens. On Test Connection, including the lightweight authentication-only check, the test fails outright with this message. In a live sync run this stops the sync step at authentication, before connector validation even runs and before any employee is read or written.Fill in the named authentication setting on the connector configuration, then re-run Test Connection.
The configured value '[configured value]' for field '[PYEmployee field name]' could not be converted to the expected type ([expected type]). Correct the mapping configuration.Read and WriteThe connector has a PYEmployee dynamic mapping override configured for a recognized field, and the configured constant value cannot convert to that field's expected type (decimal, whole number, or true/false; string fields always pass).Surfaces through connector validation, the same way as the missing-setting message above. On Test Connection it comes back as a validation message. In a live sync run it is collected with other validation issues and stops the sync step before any employee is processed.Open the connector's PYEmployee dynamic mapping configuration and correct the value for the named field so it matches the expected type.
The configured value '[configured value]' for field '[PYEmployee field name]' could not be converted to the expected type ([expected type]). The employee will not be sent to CMiC. Correct the mapping configuration and run the sync again.Write onlySame underlying condition as the connector-validation version above, evaluated again while building one employee's write payload during a live sync.The employee record is skipped for this run (not written). Because the mapping value is a fixed connector setting, not employee data, every employee in the same write step is expected to hit the same failure until the mapping is corrected.Open the connector's PYEmployee dynamic mapping configuration and correct the value for the named field so it matches the expected type.
The provider's security group name exceeds the maximum length of 200 characters supported and will not be synced.Write onlyThe connector's configured Security Group value is not blank and is longer than 200 characters.The employee record is skipped for this run (not written). This check runs against the connector's own configured value, not the employee's data, so every employee in the same write step is expected to be skipped until the value is shortened.Shorten the Security Group value on the connector configuration to 200 characters or fewer.
The provider's rate code exceeds the maximum length of 4 characters supported and will not be synced.Write onlyThe connector's configured Rate Code value is not blank and is longer than 4 characters. Rate Code is only read from the connector configuration on Enterprise configurations; Cloud configurations always use a fixed code and cannot trigger this.The employee record is skipped for this run (not written). This check runs against the connector's own configured value, not the employee's data, so every employee in the same write step is expected to be skipped until the value is shortened.Shorten the Rate Code value on the connector configuration to 4 characters or fewer.
Employee WorkLocation1 [employee's work location] does not match connector company configuration [configured Companies list]. Employee will not be sent to CMiC.Write onlyThe employee's work location value is not an exact, case-sensitive match to any code in the connector's configured Companies setting. This can appear alongside a separate required-work-location message when the employee's work location is blank, since that is a different check in the same validation pass.The employee record is skipped for this run (not written). Only employees whose work location does not match are affected; other employees in the same run are unaffected.Either correct the employee's work location so it matches a company code already configured on the connector, or add the missing company code to the connector's Companies setting if that location should legitimately sync. See the org structure article.
PersistMode.None so employee is not created and subsequent employee data must skip.Write onlyThe employee is new (being added, not updated) and the sync run's persist mode is set to the mode that saves nothing.The remainder of that employee's write is skipped for this run. Because the run is not saving changes, the connector has no real new employee record to attach further data to, so it stops that employee's write cleanly rather than attempting it against a record that was never created.Expected behavior for a run configured not to persist changes. If the intent was to actually create the employee in CMiC, re-run the sync with a persist mode that saves changes.

Connector Settings That Can Appear in the Missing-Configuration Message

Setting nameWhat it controlsBehavior when missing
CompaniesComma-separated list of CMiC company codes the connector syncs. Also checked against your live CMiC company list during connector validation, and checked per employee against the employee's work location.Recorded and surfaced through connector validation.
Security GroupDefault CMiC security group code applied to newly added employees. Also checked for a 200-character length limit at write time.Recorded and surfaced through connector validation.
Patch 21 or greater installedNon-cloud only. Tells the connector whether your on-premise CMiC has patch 21 or later, which determines whether the compensation history endpoint is used. Cloud configurations always use that endpoint and never read this setting.Recorded and surfaced through connector validation.
Use Legacy Deduction/Benefit EndpointsWhether the connector calls CMiC's legacy deduction and benefit endpoints instead of the newer benefit election endpoints.Recorded and surfaced through connector validation.
Pass Hourly Rate as Billing and Charge Out RateWhether an employee's hourly rate is also written to the billing rate and charge-out rate fields.Recorded and surfaced through connector validation.
Map Hire Date to Seniority DateWhether the employee's hire date is also written to CMiC's seniority date field.Recorded and surfaced through connector validation.
Rate CodeEnterprise configurations only. Default pay rate code written to employees. Cloud configurations do not read this setting and always use a fixed code.Recorded and surfaced through connector validation.
Federal Withholding Tax CodeEnterprise configurations only. Default federal withholding tax code. Cloud configurations do not read this setting and always use a fixed code.Recorded and surfaced through connector validation.
State Withholding Tax CodeEnterprise configurations only. Default state withholding tax code. Cloud configurations do not read this setting and always use a fixed code.Recorded and surfaced through connector validation.
CMiC Service URLBase URL of the your CMiC API. Used for every request the connector makes.Stops the run immediately during authentication.
OAuth URLOAuth configurations only. Token endpoint used to exchange credentials for an access token.Stops the run immediately during authentication.
OAuth Client IDOAuth configurations only. OAuth application client identifier.Stops the run immediately during authentication.
OAuth SecretOAuth configurations only. OAuth application secret.Stops the run immediately during authentication.
CMiC UserNameBasic auth configurations only (non-OAuth). Username used for the connector's Basic authentication header.Stops the run immediately during authentication.
CMiC PasswordBasic auth configurations only (non-OAuth). Password used for the connector's Basic authentication header.Stops the run immediately during authentication.

Note: the connector also has an OAuth Scope setting used for OAuth configurations, but it is read as optional and never produces this message.

Confirming the Error

  1. If the report is about setting up or testing the connector, open the connector's configuration page and run Test Connection (or the connector's authentication check, if that is what was run).
  2. Read the message returned. A message that starts with "CMiC Provider could not read the configuration setting" names the missing setting in quotes. A message that contains "could not be converted to the expected type" names a PYEmployee mapping field and the value that failed to convert.
  3. If the report is about a completed sync, open the sync execution in Sync History and find the step for this CMiC connector.
  4. Check the step-level Failures tab first. The missing-configuration messages and the connector-level PYEmployee mapping message stop the step before any employee is processed, so they appear as a step-level failure, not on an entity row.
  5. If the step ran and processed employees, open the People/Employees entity row and check its Errors column. Errors that occur while writing an individual employee, such as an invalid PYEmployee mapping value at write time, a work location mismatch, a too-long Security Group or Rate Code, or the persist-mode message, appear in that row's errors list.
  6. Match on the fixed part of the message text shown in the table above, not on the specific setting name, field name, or value inside the quotes, since those vary per connector and per employee.

Resolving the Error

A Connector Setting Is Missing or Blank

  1. Identify the setting name from the message.
  2. Open the connector's configuration page in Arcoro.
  3. Using the setting table above, enter a valid value for that setting.
  4. Save the connector configuration.
  5. Run Test Connection again to confirm the message no longer appears, then re-run the affected sync step if needed.

A PYEmployee Dynamic Mapping Value Does Not Match Its Expected Type

  1. Identify the field name and expected type from the message.
  2. Open the connector's PYEmployee dynamic mapping configuration.
  3. Correct the configured value so it matches the expected type, for example a numeric value for a decimal or whole-number field, or true/false for a true/false field.
  4. Save the connector configuration and run Test Connection to confirm, then re-run the sync if the message had appeared during a live write.

The Connector’s Security Group or Rate Code Value Is Too Long

  1. Open the connector's configuration page.
  2. Shorten Security Group to 200 characters or fewer, or shorten Rate Code to 4 characters or fewer (Enterprise configurations only).
  3. Save the connector configuration and re-run the sync.
  4. Confirm the entity row's Errors count drops for the employees that previously failed, since this was affecting every employee in the write step.

An Employee’s Work Location Does Not Match the Connector’s Configured Companies

  1. Compare the employee's work location value against the codes listed in the connector's Companies setting.
  2. If the employee's work location is wrong, correct it in the source of that data so it matches an existing company code on the connector.
  3. If the work location is correct and that company should legitimately sync to CMiC, add the missing company code to the connector's Companies setting instead.
  4. Re-run the sync and confirm the employee's entity row no longer shows this error. See the org structure article for related location and facility mapping issues.

The Persist-Mode Message Appears

  1. Confirm which run mode was selected for that sync run.
  2. If the run was intentionally set to not persist changes, this message is expected for any new employee in that run. No fix is needed.
  3. If an actual employee creation in CMiC was intended, re-run the sync with a persist mode that saves changes.

When to Escalate

If any of the following occur, you may need to reach out to Arcoro support for additional assistance.

  • A missing-setting message persists after the value has been entered and saved on the connector configuration: escalate, since this points to a configuration or product issue beyond a simple missing value.
  • A PYEmployee dynamic mapping message appears but the mapping configuration already looks correct for the named field and type: escalate.
  • The Security Group or Rate Code length message appears for every employee in a write step and the connector's value is already within the stated limits: escalate, this is an Arcoro-side configuration or product problem, not a data problem.
  • The work location mismatch message appears and it is unclear whether the fix should be correcting the employee's data or adding a company to the connector: confirm which is correct before making a change, and escalate if that is not clear from the ticket.
  • The persist-mode message appears on a run that was not configured for the no-save mode: escalate as an unexpected result.
Was this article helpful?
0 out of 0 found this helpful