improve documentation for subnet filter usage

README.md

@@ -1,43 +1,33 @@
-phpIPAM Integration for vRealize Automation 8.x
-============
-
+# phpIPAM Integration for vRealize Automation 8.x
 This integration allows vRealize Automation 8.x to use [phpIPAM](https://phpipam.net) for assigning static IP addresses to provisioned virtual machines. Built against vRA 8.2.0.12946 and phpIPAM 1.5.
 
 Details on how I built this (as well as notes on how I configured phpIPAM to work correctly with this plugin) can be found here:
 https://virtuallypotato.com/integrating-phpipam-with-vrealize-automation-8
 
-Prerequisite:
-===============
+## Prerequisites
 
-phpIPAM 1.5 must be [installed, configured, and available over HTTPS](https://virtuallypotato.com/integrating-phpipam-with-vrealize-automation-8#step-0-phpipam-installation-and-base-configuration). Subnets [must be defined in phpIPAM](https://virtuallypotato.com/integrating-phpipam-with-vrealize-automation-8#step-2-configuring-phpipam-subnets), and those which should be available to vRA can be marked as an IP pool (marking as pool is optional as of [v1.0.6](https://github.com/jbowdre/phpIPAM-for-vRA8/releases/tag/v1.0.6)). A trusted SSL certificate is not required; vRA will prompt to confirm the certificate when the connection is initially validated.
-
-Usage
-===============
-
-From the phpIPAM web interface:
+- phpIPAM 1.5 must be installed, configured, and available over HTTPS
+  - Consult the [phpIPAM installation docs](https://phpipam.net/documents/installation/)
+- Subnets [must be defined in phpIPAM](https://virtuallypotato.com/integrating-phpipam-with-vrealize-automation-8#step-2-configuring-phpipam-subnets).
+- (Optional) A [Custom Field](docs/custom_field.md) defined to identify subnets which should be available to vRA.
+  - Note: I previously used the built-in `isPool` field, but this is not ideal with versions of phpIPAM 1.5 since a [change on April 4, 2022](https://github.com/phpipam/phpipam/commit/7de080b8) which made the subnet and broadcast addresses (`x.x.x.0` and `x.x.x.255`) assignable on networks with this field set. Use a [Custom Field](docs/custom_field.md) instead. 
+- A trusted SSL certificate is not required; vRA will prompt to confirm the certificate when the connection is initially validated.
 
+## Usage
+### From the phpIPAM web interface:
 1. **Administration > phpIPAM Settings > Feature Settings** and enable the **API** option.
-
 2. **Administration > phpIPAM Settings > Users** and create a new user to be used by vRA.
-
 3. **Administration > phpIPAM Settings > API** and create a new API key with *Read/Write* permissions and *SSL with User Token* security. Make a note of the selected *App ID* field (not the auto-generated *App Code*).
 
-In vRealize Automation:
-
+### In vRealize Automation:
 1. Go to **Cloud Assembly > Infrastructure > Integrations** and **Add Integration**.
-
 2. Select the **IPAM** integration type.
-
 3. Give it a name, then click **Manage IPAM Providers > Import Provider Package**.
-
 4. Upload `phpIPAM.zip` (get it [here](https://github.com/jbowdre/phpIPAM-for-vRA8/releases/latest)).
-
 5. Back at the **New Integration** page, click the **Provider** dropdown and select *phpIPAM*.
-
 6. Enter the **API App ID**, **Username**, **Password**, and **Hostname** of the phpIPAM server (fully-qualified name or IP address).
-
+7. (Optional) [Configure the subnet filter](docs/custom_field.md#configure-integration).
 7. Click **Validate** to verify the information. It may take a minute or two for the validation to complete.
-
 8. Once validated, click **Add**.
 
 You can then learn how to utilize the new IPAM integration [here](https://docs.vmware.com/en/vRealize-Automation/8.2/Using-and-Managing-Cloud-Assembly/GUID-9AE32BD7-2D1B-4FEE-881F-A0EDE5907D10.html)

docs/custom_field.md

@@ -0,0 +1,39 @@
+# Custom Fields in phpIPAM
+In environments with a large number of monitored subnets, it may be desirable to only tell vRA about those which will actually be used for deployments. This can be accomplished by applying a Custom Field to the selected subnets, and configuring the IPAM integration to filter on that field.
+
+In my environments, I have defined a boolean named `vRA_Range`, though you can of course use whatever name sounds good to you.
+
+## Create a Custom Field
+1. Log in to your phpIPAM instance and navigate to **Administration -> IP Related Management -> Custom fields**.
+2. Click on the **+** button under the *Custom Subnets fields* section.
+3. Populate the fields as you see fit. Here's how I configured mine:
+
+    ![Sample configuration](edit_custom_field.png)
+
+    | Parameter | Value |
+    |:--- |:--- |
+    | Name | `vRA_Range` |
+    | Description | `vRA deployment range` |
+    | Type | `boolean` |
+    | Size/Length | `1` |
+    | Default value | `0` |
+    | Required field | (unchecked) |
+
+4. Click **Add**.
+
+## Apply a Custom Field to a Subnet
+1. Navigate to a subnet you'd like to use for vRA deployments.
+2. On the *Actions* row, click the pencil icon to edit the subnet.
+    
+    ![Edit subnet properties](edit_subnet_properties.png)
+3. At the bottom of the properties window, select **VRA_Range** and set it to *Yes*.
+
+    ![Configure vRA_Range](vra_range.png)
+4. Click **Edit** to save the change.
+5. Repeat for other vRA subnets.
+
+## Configure integration
+![Configure the filter](configure_filter.png)
+1. When you configure this integration in vRA, tick the *Subnets must match filter* box.
+2. Enter the name of your Custom Field, *prefixed with `custom_` (ex: `custom_vRA_Range`).
+3. Enter the value to match on (`1`=="Yes"; `0`=="No").

pom.xml

@@ -23,7 +23,7 @@ conditions of the subcomponent's license, as noted in the LICENSE file.
     <properties>
         <provider.name>phpIPAM</provider.name>
         <provider.description>phpIPAM integration for vRA</provider.description>
-        <provider.version>1.0.8</provider.version>
+        <provider.version>1.0.9</provider.version>
 
         <provider.supportsAddressSpaces>false</provider.supportsAddressSpaces>
         <provider.supportsUpdateRecord>true</provider.supportsUpdateRecord>

src/main/resources/CHANGELOG.md

@@ -1,3 +1,6 @@
+# v1.0.9
+Improve documentation on subnet filter usage
+
 # v1.0.8
 Fix gateway check logic
 

src/main/resources/endpoint-schema.json

@@ -108,7 +108,7 @@
             "dataType":"string"
          },
          "label":"Field for filter",
-         "signpost":"'isPool' to match subnets marked as IP Pools. See the <a href='https://phpipam.net/api/api_documentation/'>phpIPAM API documentation</a>.",
+         "signpost":"'custom_vRA_Range' to match subnets with custom field 'vRA_Range'. See the <a href='https://github.com/jbowdre/phpIPAM-for-vRA8'>integration documentation</a>.",
          "constraints":{
             "required":[{
                "equals":{