[BUG]: Unchanged businessPhones property updates on every run

[RobertKlohr]

On every run of the application the businessPhones field reports in the log that it needs to be updated. I don't have the solution but I think I can identify the problem. In Onspring the Phone field is a string and in MS Graph the businessPhones property is an array of strings. The comparison of "(555) 678-1212" to ["(555) 678-1212"] is not matching.

Configuration:

"UsersFieldMappings": {
	"4792": "id",
	"35": "jobTitle",
	"2": "city",
	"34": "businessPhones",
	"1642": "employeeType",
	"10": "state"
},

Log Entry:

{"@t":"2025-03-20T06:08:23.9911044Z","@mt":"Field {FieldId} needs to be updated. Onspring value: {CurrentValue}. Azure AD value: {NewValue}","@l":"Debug","FieldId":34,"CurrentValue":"(555) 678-1212","NewValue":["(555) 678-1212"]}

[StevanFreeborn]

Will take a gander. Thanks for the heads up!

[StevanFreeborn]

Writing to think a little here...

This is difficult...I'm not sure how to go about fixing it in a way that doesn't require special casing the phone number field.

But maybe the special case is worth it in this instance?

Basically, I'd need to check if the target field is the Onspring phone number field, but also check if the mapped property is the businessPhones property then perhaps scrub all special characters and just compare digits???

But does that make sense to always do that?

I think so if the most common case is we are actually mapping phone number data into the Onspring phone number field we should cater to that.

Need to think on this one for a bit... 🤔

[RobertKlohr]

Part of the problem with doing this for just the phone field is that there is no why to accurately determine which field or fields is the phone field in Onspring.
 
In this use case phone has the Onspring type of text while the businessPhones property has a type of array of strings (not sure if or how this compares to a string collection in this context) and this is a mismatch that should fail the validation. However you are already doing some work to convert the type into a string so it can be written into Onspring. My guess is you are concatenating values of the array, and in my environment since there is only one value it basically works except that the brackets for the array are still present during the comparison, hence it fails, but are removed before or as the value is saved in Onspring. In the documentation you list the Type Compatibility to include String Collection | Text which is maybe where this issue comes from. I would argue that a String Collection is compatible with the Onspring "multiplicity": "MultiSelect" and not Text.

I think a better way is during the field validation step we determine if there is a set of mapped fields where a type conversion does not match but could be made to match if converted. There could be a flag in the config file "ForceConversion": "True" that allows this to happen versus having the validation step fail. If I try to map a String Collection to a Text field and have "ForceConversion" is set to "True" then the application would take the first value of the collection and put that in the string field. Doing this should then allow the values to match on comparison. A more specific configuration option might be "TruncateCollection" that would be used to determine if just the first value of a collection is written to a text field.

If we go the route of allowing the user to choose if how items are converted the flow could be to compare the field types and if they do not match either:

1. Throw an exception and stop.
2. Show and log a warning and continue if "ForceConversion" is set to "True".

On continue we would have a set of functions that would attempt to convert to or from strings, numbers and dates using Convert.ToString. DateTime.TryParseExact. or Decimal.TryParse. The last use case, and the one for the businessPhones property, is to truncate an array of strings to a single string.

Taking this approach future proofs the application and eliminates the need for any property specific checks.

I re-typed this about a dozen times trying to make it clear and concise. Hopefully it makes some sense. ;-)

[RobertKlohr]

On a related note, I did several runs tonight to test configurations and timed each one.

What I discovered, at least according to the audit logs, is that even when OnspringAzureADSyncer stated it is updating the phone field that Onspring does not appear to be actually updating the field. If it is actually changing the field then Onspring is not logging the change to the audit log. As you can see from the sample data the runs where I set the config to update the phone field were the same as when it was set to not update that field. I would expect the updating run to be a bit slower. Could the message in the log about the field being updated not actually be accurate?

If we are certain that the field is being updated then there is a bug in the Onspring audit logging, which would not surprise me as I have found at least two other repeatable bugs in the logging tonight that I am going to open support tickets on. I just don't know if it should be three. ;-)

Here is raw data from the test runs.

• Total number of test runs: 7
• Users being synced: 6183
• Time (single run) to create 6183 users: 16:36
• Average Time (6 runs) to sync 6183 users: 7:30
  -- Half of the 6 runs were set to update the phone field and half were not updating. The run times were all within 45 seconds of each other with no pattern as to which one was faster.
  -- There was one slow outlier at 9:44, and it was a non-updating run, and if removed the average drops to 6:40.

[StevanFreeborn]

Part of the problem with doing this for just the phone field is that there is no why to accurately determine which field or fields is the phone field in Onspring.   In this use case phone has the Onspring type of text while the businessPhones property has a type of array of strings (not sure if or how this compares to a string collection in this context) and this is a mismatch that should fail the validation. However you are already doing some work to convert the type into a string so it can be written into Onspring. My guess is you are concatenating values of the array, and in my environment since there is only one value it basically works except that the brackets for the array are still present during the comparison, hence it fails, but are removed before or as the value is saved in Onspring. In the documentation you list the Type Compatibility to include String Collection | Text which is maybe where this issue comes from. I would argue that a String Collection is compatible with the Onspring "multiplicity": "MultiSelect" and not Text.

I think a better way is during the field validation step we determine if there is a set of mapped fields where a type conversion does not match but could be made to match if converted. There could be a flag in the config file "ForceConversion": "True" that allows this to happen versus having the validation step fail. If I try to map a String Collection to a Text field and have "ForceConversion" is set to "True" then the application would take the first value of the collection and put that in the string field. Doing this should then allow the values to match on comparison. A more specific configuration option might be "TruncateCollection" that would be used to determine if just the first value of a collection is written to a text field.

If we go the route of allowing the user to choose if how items are converted the flow could be to compare the field types and if they do not match either:

1. Throw an exception and stop.
2. Show and log a warning and continue if "ForceConversion" is set to "True".

On continue we would have a set of functions that would attempt to convert to or from strings, numbers and dates using Convert.ToString. DateTime.TryParseExact. or Decimal.TryParse. The last use case, and the one for the businessPhones property, is to truncate an array of strings to a single string.

Taking this approach future proofs the application and eliminates the need for any property specific checks.

I re-typed this about a dozen times trying to make it clear and concise. Hopefully it makes some sense. ;-)

I can detect the Onspring phone number field just using it's name. That field in Onspring is special like the Username field. It's name can't be changed.

List of strings from azure can be mapped to text fields, and I just turn them into comma separated values. I don't think I want to go much more down the rabbit hole on that one myself at the moment.

For this fix I'm planning to special case the value equality check for the phone number field in Onspring and compare the values by digits only to detect if an update is needed. The businessPhones property coming from Azure will only ever have a single value in it based on MS documentation.

The telephone numbers for the user. NOTE: Although it's a string collection, only one number can be set for this property. Read-only for users synced from the on-premises directory.

So this fix - while not the most elegant - should address the actual use case of wanting to map an azure user's phone number to their onspring user record.

If someone decides they want to map data other than a single phone number into that field I'm okay with passing the downside on to them.

[StevanFreeborn]

On a related note, I did several runs tonight to test configurations and timed each one.

What I discovered, at least according to the audit logs, is that even when OnspringAzureADSyncer stated it is updating the phone field that Onspring does not appear to be actually updating the field. If it is actually changing the field then Onspring is not logging the change to the audit log. As you can see from the sample data the runs where I set the config to update the phone field were the same as when it was set to not update that field. I would expect the updating run to be a bit slower. Could the message in the log about the field being updated not actually be accurate?

If we are certain that the field is being updated then there is a bug in the Onspring audit logging, which would not surprise me as I have found at least two other repeatable bugs in the logging tonight that I am going to open support tickets on. I just don't know if it should be three. ;-)

Here is raw data from the test runs.

• Total number of test runs: 7
• Users being synced: 6183
• Time (single run) to create 6183 users: 16:36
• Average Time (6 runs) to sync 6183 users: 7:30
  -- Half of the 6 runs were set to update the phone field and half were not updating. The run times were all within 45 seconds of each other with no pattern as to which one was faster.
  -- There was one slow outlier at 9:44, and it was a non-updating run, and if removed the average drops to 6:40.

This is interesting I can take a look at this while I'm working on the fix and see what I find. I'm pretty sure the app is making a request when the phone numbers don't match, but I'll verify. I'd agree I'd expect the runs that involve updates to be slower compared to runs that don't involve any updates, but maybe that one request to Onspring to update the user represents a very small amount of time of the overall process.

[RobertKlohr]

I'm OK with your proposed fix and I believe it has the best effort for result ratio. This is especially true since, as I was unaware, the phone field in Onspring is a protected "system" field that can't be altered.