Update enrollment rules

You can update an enrollment rule or change its type. Updating an enrollment rule does not affect the configuration of existing agents.

Prerequisites

Your NXLog Platform organization ID.
An NXLog Platform API Personal Access Token (PAT).

About updating enrollment rules

A PATCH request to the enroll-rules endpoint updates an existing enrollment rule. You can execute the request for all or selected rules by specifying a filter. The following enrollment rule properties can be updated: name, optionsJson, selector, priority, automatic, and comment.

$ curl --verbose --request PATCH \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/enroll-rules/*/?filter=({QUERY})" \
       --header "Authorization: Bearer {TOKEN}" \
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{OBJECT}'

If matching enrollmentg rules exist, the command returns 200 OK with the following JSON body. Otherwise, it returns an empty JSON array.

[
  {
    "id": "{RULE_UUID}",
    "status": "success"
  }
]

Update an enrollment rule by name

This example uses a filter to update an enrollment rule by its name. Enrollment rule names are not unique. Therefore, if there is more than one rule with the same name, the request updates all of them.

The enrollment rule name is case-sensitive.

PATCH /enroll-rules/*/?filter=(name LIKE "New agents")

PATCH /enroll-rules/*/?filter=(name LIKE "New agents")
Entity type	`enroll-rules`
Entity UUID	`*`
Filter	`(name LIKE "New agents")`
Request body	`{ "automatic": true, "comment": "Last updated by John Smith" }`

Entity type

enroll-rules

Entity UUID

*

Filter

(name LIKE "New agents")

Request body

{
  "automatic": true,
  "comment": "Last updated by John Smith"
}

Try it

Execute the following curl command or Python script to update an enrollment rule by its name.

curl

$ curl --verbose --request PATCH \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/enroll-rules/*/?filter=(name+LIKE+%22New+agents%22)" \(1)
       --header "Authorization: Bearer {TOKEN}" \(2)
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"automatic": true, "comment": "Last updated by John Smith"}'

1	Replace `example.com` with the NXLog Platform domain you specified when installing NXLog Platform and `{ORG_ID}` with your organization ID.
2	Replace `{TOKEN}` with your API token. See Generating a token for instructions.

Python

'''
Requires Python 3.x
'''

import requests
import json

# Set these variables for your environment
api_token = '<API_TOKEN>' (1)
base_url = 'https://agents.<DOMAIN>/api' (2)
org = '<ORG_ID>' (3)
rule_name = '<RULE_NAME>' (4)

endpoint = 'api/v1/enroll-rules'
url = '{}/{}/{}'.format(base_url, org, endpoint)
headers = {
    'Authorization': 'Bearer {}'.format(api_token),
    'Content-Type': 'application/json',
    'Accept': '*/*'
}

query = '*/?filter=(name LIKE "{}")'.format(rule_name)
payload = {'automatic': True, 'comment': 'Last updated by John Smith'}
r = requests.patch('{}/{}'.format(url, query), headers=headers, data=json.dumps(payload))

if r.status_code == 200:
    print('Status: {}'.format(r.status_code))
    print(json.dumps(r.json(), indent=2))
else:
    print('Error: {} {}'.format(r.status_code, r.text))

1	Replace `<API_TOKEN>` with your API token. See Generating a token for instructions.
2	Replace `<DOMAIN>` with the NXLog Platform domain you specified when installing NXLog Platform.
3	Replace `<ORG_ID>` with your organization ID.
4	Replace `<RULE_NAME>` with your enrollment rule name.

Example response

Status: 200
[
  {
    "id": "3cae6955-abeb-11ef-8004-3c2d91911792",
    "status": "success"
  }
]

Change the enrollment rule type

You can update an enrollment rule to either set connection settings or assign a configuration template by specifying the corresponding options field. The connection and templateId fields are mutually exclusive. Therefore, specifying one field in an update request overwrites the other field.

Specifying both the connection and templateId properties returns an error status and the message failed to parse options: please provide either connection parameters or a configuration id.

This example changes an enrollment rule from setting connection options to assigning a configuration template.