When Micetro Central runs an external script associated with a change event, it sends an XML structure as an argument to the script being called. The XML structure contains information about all custom properties that are defined for the object type. The XML structure also contains the login name of the user that initiated the script.
The XML structures differ a little depending on the type of script (property change, zone contents change, DNS record change, scope monitoring).
externalScriptParameters.Standard script interface
The XML schema for all objects is as follows:
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="externalScriptParameters" type="externalScriptParametersType"/>
<xs:complexType name="objectType">
<xs:sequence>
<xs:element type="xs:string" name="id"/>
<xs:element type="xs:string" name="type"/>
<xs:element type="xs:string" name="name" minOccurs="0" maxOccurs="1"/>
<xs:element type="xs:string" name="addressSpace" minOccurs="0" maxOccurs="1"/>
<xs:element type="xs:string" name="server" minOccurs="0" maxOccurs="1"/>
<xs:element type="xs:string" name="view" minOccurs="0" maxOccurs="1"/>
<xs:element type="xs:string" name="zone" minOccurs="0" maxOccurs="1"/>
<xs:element type="xs:string" name="fqName" minOccurs="0" maxOccurs="1"/>
<xs:element type="xs:string" name="zoneType" minOccurs="0" maxOccurs="1"/>
<xs:element type="xs:string" name="dynamic" minOccurs="0" maxOccurs="1"/>
<xs:element type="xs:string" name="adIntegrated" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="customFieldType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute type="xs:string" name="customFieldID"/>
<xs:attribute type="xs:string" name="customFieldName"/>
<xs:attribute type="xs:string" name="objectID"/>
<xs:attribute type="xs:string" name="objectType"/>
<xs:attribute type="xs:string" name="value"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="customFieldsType">
<xs:sequence>
<xs:element type="customFieldType" name="customField"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="propertyType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute type="xs:string" name="propertyName"/>
<xs:attribute type="xs:string" name="objectID"/>
<xs:attribute type="xs:string" name="objectType"/>
<xs:attribute type="xs:string" name="value"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="propertiesType">
<xs:sequence>
<xs:element type="propertyType" name="property" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="externalScriptParametersType">
<xs:sequence>
<xs:element type="objectType" name="object"/>
<xs:element type="customFieldsType" name="customFields" minOccurs="0" maxOccurs="1"/>
<xs:element type="propertiesType" name="properties" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
<xs:attribute type="xs:string" name="userName"/>
</xs:complexType>
</xs:schema>Change request script interface
The following example shows the XML structure for a change request script:
<?xml version="1.0" encoding="ISO-8859-1"?>
<externalScriptParameters userName="administrator">
<object>
<id>18</id>
<type>28</type>
<name>18</name>
</object>
<customFields>
<customField customFieldID="7" customFieldName="customRequestProp" objectID="18" objectType="28" value="testing"></customField>
</customFields>
<properties></properties>
</externalScriptParameters>Zone content change script interface
The XML structure for a DNS zone change script differs depending on whether the zone is or is not in a view.
Zone that exists in a view: The following example shows the XML structure for a zone change script for a zone that exists in a view:
<?xml version="1.0" encoding="ISO-8859-1"?>
<externalScriptParameters userName="administrator">
<object>
<id>2534</id>
<type>13</type>
<server>bind1.corp.net.</server>
<view>internal</view>
<zone>my.zone.com.</zone>
<fqName>bind1.corp.net.:internal:zone.com.</fqName>
</object>
</externalScriptParameters>Zone not in a view: The following example shows the XML structure for a zone change script for a zone that is not in a view:
<?xml version="1.0" encoding="ISO-8859-1"?>
<externalScriptParameters userName="administrator">
<object>
<id>2635</id>
<type>13</type>
<server>dns1.corp.net.</server>
<view />
<zone>my.zone.com.</zone>
<fqName>dns1.corp.net.::my.zone.com.</fqName>
</object>
</externalScriptParameters>DNS record change: The following example shows the XML structure for a DNS record change script:
<?xml version="1.0" encoding="ISO-8859-1" ?>
<externalScriptParameters userName="administrator">
<object>
<id>1</id>
<type>13</type>
<server>dns1.corp.net.</server>
<view />
<zone>my.zone.com</zone>
<fqName>dns1.corp.net.::my.zone.com.</fqName>
</object>
</externalScriptParameters>Workflow change script interface
The following XML structure is used for changes to a workflow:
<?xml version="1.0" encoding="ISO-8859-1"?>
<externalScriptParameters userName="administrator">
<object>
<id>14</id>
<type>13</type>
<name>gaman7</name>
<addressSpace>1</addressSpace>
<server>bind1.corp.net.</server>
<view></view>
<fqName>bind1.corp.net.:internal:zone.com.</fqName>
<zoneType>master</zoneType>
<dynamic>0</dynamic>
<adIntegrated>0</adIntegrated>
</object>
<customFields>
<customField customFieldID="5" customFieldName="myCustomRecordProp" objectID="14" objectType="13" value="test"></customField>
</customFields>
<properties>
<property propertyName="someName" objectID="2580" objectType="10" value="someValue"></property>
</properties>
</externalScriptParameters>Data returned by change event scripts
Micetro Central uses the information in the XML structure to either update other
custom properties or display an error message if the success attribute on the result
element is set to 0. The following XML example shows how an error
message can be returned by the change event script:
<?xml version="1.0"?><result success="0"><error code="1"message="The error message."></error></result>The XML structure is not required to return information about all custom properties, only fields that the script has changed. Unknown property fields are ignored by Micetro Central.
Example Python script for a custom property change
country and
city using a location code. The intended use is to mark the locations of
servers.import sys
import xml.etree.ElementTree as ET
def get_custom_field_element(custom_fields, name):
element = custom_fields.find(f"./customField[@customFieldName='{name}']")
if element is None:
raise KeyError(f"Custom property '{name}' was not found.")
return element
def get_result(root):
# username variable is not used but this is how to get the username
username = root.get('userName')
custom_fields = root.find("./customFields")
result = ET.Element("result", {"success": "0"})
try:
location_element = get_custom_field_element(custom_fields, 'Location')
country_element = get_custom_field_element(custom_fields, 'Country')
city_element = get_custom_field_element(custom_fields, 'City')
except KeyError as e:
ET.SubElement(result, "error", {"code": "1", "message": str(e)})
return result
location = location_element.get('value')
# A database could be queried instead here
LOCATION_MAP = {
'l1': ('USA', 'Washington'),
'l2': ('UK', 'London')
}
if location not in LOCATION_MAP:
ET.SubElement(result, "error", {"code": "1", "message": "Unknown location."})
return result
result.set("success", "1")
country, city = LOCATION_MAP[location]
country_element.set('value', country)
city_element.set('value', city)
result.append(custom_fields)
return result
# Read all input and parse as XML
root = ET.fromstring(sys.stdin.read())
result = get_result(root)
print('<?xml version="1.0"?>')
# This will write the generated result xml to standard output
ET.dump(result)The script in this example requires that all input is read and parsed as XML, and the results will be written as a standard XML output.