Re: Onboarding api - Add vm's to plan

Commens · ‎11-02-2022

Hoping to find someone that can help me here. We're in the process of migrating off vRA 7 to 8. But we need to move our VM's over. We have a lot of servers to bring over, and I'd rather not have to manually touch every one. However I'm struggling to find documentation on doing this. I am reviewing the swagger api page, but it's very limited on using this. We'd like to assign an owner to teach one as well. This is a long shot, so I'm just hoping someone can point me in the right direction here.

emacintosh · ‎11-03-2022

So you are looking to create/populate/run the plan via the API, instead of doing that manually? If so, then probably review the Onboarding section of the swagger docs.

We do this today as one-offs when needed and these are the corresponding endpoints:

Create a plan: relocation/onboarding/plan
Create a rule (we do this for one vm): relocation/onboarding/task/create-rule
Run a plan: relocation/api/wo/execute-plan
Delete a plan: relocation/onboarding/plan/<planId>

If you want to set an owner, you can do that after the deployment is onboarded: deployment/api/deployments/<deploymentId>/requests (with actionId set to "Deployment.ChangeOwner").

Hope that helps and at least gets you started down a path.

Commens · ‎11-03-2022

There is no onboarding rules in my 8.9 swagger ui. That's what's giving me so much trouble, how to add vm's to a plan.

emacintosh · ‎11-03-2022

Hmm...I see the Onboarding section in our on-prem API docs (8.4.2) as well as in the SaaS offering. Seems odd that it would be missing for just 8.9.

Are you hitting this link for the swagger docs? <your vra site>/automation-ui/api-docs/

You should see something this....

Commens · ‎11-03-2022

Yep that's where I'm at. This is what I see.

https://www.mgmt.cloud.vmware.com/relocation/api/swagger/ui/index.html

emacintosh · ‎11-03-2022

Oh ok, I'm sorry. I thought you meant you didn't see any Onboarding endpoints at all. It looks like the API has changed a bit - they don't seem to be using rules anymore. I may have to run the developer tools while adding machines to a plan to see which endpoints they're hitting. Although I do think some others out here may have done this more recently than me.

I could share our code for creating a rule if it helps, but don't want to give you something that may no longer be supported or is an out-dated approach.

emacintosh · ‎11-04-2022

When adding machines to an existing plan, it seems to be using the bulk request endpoint, was just watching the Network tab in the developer tools. I didn't try hitting it via the API directly myself yet.

uri: relocation/onboarding/task/create-deployment-bulk

method: Post

Payload: looks like you can multiple vms to a deployment if you'd like. or you could add multiple deployments, each with their own resource....or both of course.

{
    "deployments": [
        {
            "resources": [
                {
                    "link": "/resources/compute/11111111-2222-3333-4444-555555555555",
                    "name": "ServerABC",
                    "tagLinks": [
                        "/resources/tags/22222222-3333-4444-5555-666666666666",
                        "/resources/tags/33333333-4444-5555-6666-777777777777"
                    ]
                }
            ]
        }
    ],
    "planLink": "/relocation/onboarding/plan/44444444-5555-6666-7777-888888888888"
}

Commens · ‎11-04-2022

Thank you, that is helpful. I guess i'm just a little confused how I'm supposed to find the /resource/compute and what are the tags?

Commens · ‎11-04-2022

So i've gotten farther, I'll have to find a way to query servers in vcenter to get their id for the /resources/compute/xxx

{
  "planLink": "/relocation/onboarding/plan/11111111-2222-3333-4444-555555555555",
  "name": "deployment-test
  "description": "test-api",
  "owner": "test"
  "resources": [
    {
      "link": "/resources/compute/11111111-2222-3333-4444-555555555555",
      "name": test
      "tagLinks": [],
    }
  ],
  "createBlueprint": false
}

This adds the vm, creates deployment, sets owner. However it gives me an error on deployment

Cannot read properties of undefined (reading 'autoGenerate')

emacintosh · ‎11-04-2022

you may be able to get them from /iaas/api/machines (or something like that).

But there was also this enpoint being called i think too, maybe while filtering machines. so maybe it will return the server matching the filters, including the fields listed in the expandFields section?

relocation/api/wo/query-unmanaged-machine

with a payload like this:

{
    "planLink": "/relocation/onboarding/plan/<plan id>",
    "expandFields": [
        "id",
        "documentSelfLink",
        "name",
        "powerState",
        "address",
        "creationTimeMicros",
        "expandedTags",
        "tagLinks",
        "endpointLinks"
    ],
    "optionExcludePlanMachines": true,
    "filters": [
        {
            "field": "ANY",
            "values": [
                "serverABC"
            ]
        }
    ]
}

Commens · ‎11-04-2022

So I was able to actually do a search using vraurl.com/deployment/api/resources?search=servername

That gives me the resourceId needed, however I'm still getting the error "Cannot read properties of undefined (reading 'AutoGenerate') under the deployment.

It almost seems like I'm maybe missing a parameter, I just don't know which one

Commens · ‎11-08-2022

So I still get the error under deployments: "Cannot read properties of undefined (reading 'autoGenerate')"

I have no idea what this is relating to. I'm using the create-deployment api.

I tested running the onboarding plan and it brings the server over fine, however it does not change the owner. So that's a problem.

{
  "planLink": "/relocation/onboarding/plan/55555555555555555555555555555",
  "name": "deployment-testserver",
  "description": "test-api",
  "owner": "testuser",
  "resources": [
    {
      "link": "/resources/compute/5555555555555555555555555",
      "name": "testserver",
      "tagLinks": [],
      "customProperties": {
        "testorprod": "Test",
        "osType": "Windows"
        }
    }
  ],
  "createBlueprint": false
}

emacintosh · ‎11-10-2022

Really wish I would have put more cycles to trying to help figure this out. We are in the process of onboarding thousands of servers today and the web interface is simply awful. Not sure if the API is any better.

If I can find sometime in the next week or so, I'll try to revisit this to try to figure out how it's supposed to work.

Commens · ‎11-18-2022

So I still have the error under deployments, but I can still run the onboarding fine actually. I found my issue with changing owner is a known issue from what I've seen. When onboarding and setting the owners, you cannot assign an owner that has been added to permissions to the project via a group. I had to manually add each user I needed to assign the owner to, to the project. Then when I onboarded the servers, the owners were changed.

Thankfully I found this out.

emacintosh · ‎11-18-2022

The change owner functionality has been pretty bad in 8.x. I think they fixed it at one point, then maybe broke it again (my experience at least)

Also, I thought that I responded here with how to find the machines/tags but I'm not seeing it. Probably just losing my mind. So if I'm repeating myself here, I apologize.

Endpoint: /relocation/api/wo/query-unmanaged-machine

Payload:

{
    "planLink": "/relocation/onboarding/plan/<plan id>",
    "expandFields": [
        "name",
        "tagLinks"
    ],
    "optionExcludePlanMachines": true,
    "filters": [
        {
            "field": "NAME",
            "values": [
                "MyServer"
            ]
        }
    ]
}

Response:

{
    "page": {
        "documentLinks": [
            "/resources/compute/<1st compute id>",
            "/resources/compute/<2nd compute id>",
            "/resources/compute/<3rd compute id>",
            "/resources/compute/<4th compute id>"
        ],
        "documents": {
            "/resources/compute/<1st compute id>": {
                "name": "MyServer10",
                "tagLinks": [
                    "/resources/tags/<some tag id>",
                    "/resources/tags/<some tag id>",
                    "/resources/tags/<some tag id>"
                ]
            },
            "/resources/compute/<2nd compute id>": {
                "name": "MyServer17",
                "tagLinks": [
                    "/resources/tags/<some tag id>",
                    "/resources/tags/<some tag id>"
                ]
            },
            "/resources/compute/<3rd compute id>": {
                "name": "MyServer23",
                "tagLinks": [
                    "/resources/tags/<some tag id>",
                    "/resources/tags/<some tag id>"
                ]
            },
            "/resources/compute/<4th compute id>": {
                "name": "MyServer25",
                "tagLinks": [
                    "/resources/tags/<some tag id>",
                    "/resources/tags/<some tag id>",
                    "/resources/tags/<some tag id>"
                ]
            }
        },
        "documentCount": 4,
        "queryTimeMicros": 170996,
        "documentVersion": 0,
        "documentUpdateTimeMicros": 0,
        "documentExpirationTimeMicros": 0,
        "documentOwner": "<some owner id>
    },
    "totalCount": 4
}

That endpoint mimics the Add Machines tab on your plan. The response will have a documentLinks array and documents dictionary. The links in the array are the keys for the object. So you can look through the array, and then access the id, tags, name for each machine. And those are the fields you need to when adding resources to the plan.

antonioaraujo · ‎03-29-2024

Hi Guys,

Thanks for sharing your comments on how to use onboarding API.

I would like to understand better how Run a plan works: relocation/api/wo/execute-plan.

According to the documentation, it seems planLink is the mandatory field:

Execute the given onboarding plan

Is this correct?

I have tested this and the plan is run but sometimes I get errors like "RuntimeException: Validation failed". Do you know how validation works?

If I wanted to check if the execute-plan has finished properly, what should I check? subStage, taskInfo?

subStage fields has 12 different values and taskInfo also has 5 different stages as shown below:

PlanExecutionResponse schema

An additional question: Do I have to use /relocation/api/wo/execute-plan/{id} after calling execute-plan to check if the process finished properly?

I would appreciate any comments on this.

Best regards

Antonio

All

Onboarding api - Add vm's to plan