Settings API: how can externalId be updated on an object

[Bert_VanderHeyd]

Using monaco v2 now which supports settings API.

I want to update existing configurations (starting with management zones) which were configured manually.
According to the documentation the {{.name}} is used to make the comparison (check if it is already there). However, although the names are the same monaco complains...

2023/02/23 16:31:16 ERROR failed to deploy config global:builtin:management-zones:nasca-300REL: failed to upsert dynatrace obj: failed to upsert config "nasca-300REL" after 3 retries: (HTTP 400)!
    Response was: [{"code":400,"error":{"code":400,"message":"Validation failed for 1 Validators.","constraintViolations":[{"path":"builtin:management-zones/7/name","message":"Management zone with this name already exists. Please provide a different one."

I found out that actually the externalId is used of a settings object is used. When I change the name of my config it works and we see this via the API

"externalId": "monaco:YnVpbHRpbjptYW5hZ2VtZW50LXpvbmVzJG5hc2NhLTMwMFJFTA==",
      "value": {
        "name": "NASCA-301REL",
...

The value after monaco: is actually base64 encoded and corresponds with the monaco id. (builtin:management-zones$nasca-300REL)

So, if I could update the externalId via the PUT api it would be solved. However, that does not seem to be supported.

On the other hand, this is a very complex way of dealing with this. I think it should just work "by name" like documented with a fallback to externalId

[nico_riedmann · Accepted solution]

Hi @Bert_VanderHeyd, 

According to the documentation the {{.name}} is used to make the comparison (check if it is already there). 
[...]
I found out that actually the externalId is used of a settings object is used.
[...]
On the other hand, this is a very complex way of dealing with this. I think it should just work "by name" like documented with a fallback to externalId

---

The externalId is indeed what is used to identify Settings objects.
Unlike the previous Config APIs, a Setting does not necessarily have a unique name, or even any name property at all.

Thus external IDs were added to Settings to allow identifying them by something else than their Dynatrace generated object ID.

This does make things a lot more complex than the original matching by name, but that complexity is sadly just the cost of the freedom that the general-solution Settings framework brings to configuration.

Apparently we fail to mention this in documentation at the moment, sorry for that!
The next part is also still missing from documentation, we'll make sure to add it ASAP!

How it should work:

As the name is gone and the externalId is something monaco (or other tools, or you) has to set, a monaco config can contain an expected objectId in the field

originObjectId

if an object with this ID is found in the environment, monaco will attach an externalID for it.

If you've downloaded an environment using monaco you should see these originObjectIDs in your config YAML files, and the first deploy to the same environment should "onboard" existing configuration to be controlled by monaco.

Note that updating the externalID should be possible via the POST endpoint if you supply it with both an existing objectID and an externalID, so it would also be possible manually.

⚠️ Big caveat:

The Settings framework itself had to be adapted recently to fully allow attaching externalIDs to existing Settings objects.

As such only the upcoming Dynatrace version 1.262 will fully support this "onboarding" of existing Settings.

What can you do right now?

If possible remove the existing Setting and recreate it with monaco - updating Settings that originated from monaco works without limitation.

If you can not accept temporarily removing a Setting you could fall-back to using an equivalent Config v1 API to manage it if it exists. In the case of management zones that is possible.