Configuration methods

Overview

CAUTION

Service Disruption

Configuration and deletion methods may have unintended side effects.

For example, modifying some port configurations may result in services being deleted if they are no longer supported by the new configuration. It is recommended that testing be performed so that the OSS developer fully understands what side effects may happen and to ensure that side effects are handled appropriately.

CAUTION

Service Disruption

The messages in this section are examples of the SOAP XML request format.

Use the sample as a base to build your request. Ensure that you test your request before network deployment.

The XML API uses the generic package to define methods that are applicable to all objects. Methods for object configuration (create, modify, delete) are provided by the generic.GenericObject class. The most commonly used configuration methods from this class are described in the following table.

Table 15-1: Object configuration methods using the generic.GenericObject class

Method	Description
generic.GenericObject.configureInstance	Modifies an existing object and associated children. Not recommended for OSS clients as there are no return parameters.
generic.GenericObject.configureInstanceWithResult	Modifies an existing object and associated children. The method returns the newly configured parameters on the object and child, including parameters set due to associated conditions. See the XML API Reference for input parameters. See Figure 15-4, Port configuration response example for an example of the method.
generic.GenericObject.configureChildInstance	Creates a child of the object with the desired configuration values for the child or children objects, and optional grandchildren. See the XML API Reference for input parameters.
generic.GenericObject.configureChildInstanceWithResult	Creates a child of an existing object. The method returns the newly configured parameters on the child object and grandchildren, including parameters set due to associated conditions. See the XML API Reference for input parameters. See Figure 15-5, Epipe creation request example for an example of the method.
generic.GenericObject.deleteInstance	Delete an existing object. See Figure 15-7, Epipe deletion request example for an example of the method.

The configureInstanceWithResult and configureChildInstanceWithResult methods accept the resultFilter tag as an input parameter. See Result filtering for more information about result filtering in the XML API.

The resultFilter tag can be used to return only a subset of attributes for the newly configured object, its children, and grandchildren. The resultFilter returns only four attributes of the created epipe.Epipe service object instead of every attribute.

Figure 15-1: Epipe service creation example using configureChildInstanceWithResult

<generic.GenericObject.configureChildInstanceWithResult xmlns="xmlapi_1.0">

   <deployer>immediate</deployer>

   <distinguishedName>svc-mgr</distinguishedName>

   <childConfigInfo>

      <epipe.Epipe>

         <actionMask>

            <bit>create</bit>

         </actionMask>

         <id>70000</id>

         <displayedName>Epipe Example 1</displayedName>

         <description>Epipe Example 1</description>

         <subscriberPointer>subscriber:1</subscriberPointer>

      </epipe.Epipe>

   </childConfigInfo>

   <resultFilter>

      <attribute>objectFullName</attribute>

      <attribute>administrativeState</attribute>

      <attribute>displayedName</attribute>

      <attribute>olcState</attribute>

   </resultFilter>

</generic.GenericObject.configureChildInstanceWithResult>

<generic.GenericObject.configureChildInstanceWithResultResponse xmlns="xmlapi_1.0">

   <childConfigInfo>

      <epipe.Epipe>

         <displayedName>Epipe Example 1</displayedName>

         <administrativeState>up</administrativeState>

         <olcState>maintenance</olcState>

         <objectFullName>svc-mgr:service-70000</objectFullName>

         <children-Set/>

      </epipe.Epipe>

   </childConfigInfo>

</generic.GenericObject.configureChildInstanceWithResultResponse>

The following figure shows the modification of a VPLS site name. The includeChildren tag equal true returns all children of the configured object. The nested resultFilter limits the number of returned attributes for the vpls.Site and nested child objects.

Figure 15-2: VPLS site name modification example using configureChildInstanceWithResult

<generic.GenericObject.configureInstanceWithResult xmlns="xmlapi_1.0">

   <deployer>immediate</deployer>

   <distinguishedName>svc-mgr:service-25:198.51.100.71</distinguishedName>

   <includeChildren>true</includeChildren>

   <configInfo>

      <vpls.Site>

         <actionMask>

            <bit>modify</bit>

         </actionMask>

         <displayedName>Example Site A-9</displayedName>

      </vpls.Site>

   </configInfo>

   <resultFilter>

      <attribute>name</attribute>

      <attribute>objectFullName</attribute>

      <attribute>serviceName</attribute>

      <attribute>siteId</attribute>

      <children>

         <resultFilter class="vpls.SiteMldSnooping">

            <attribute>administrativeState</attribute>

            <attribute>reportSrcAddressType</attribute>

         </resultFilter>

         <resultFilter class="vpls.L2AccessInterface">

            <attribute>ingressPolicyName</attribute>

            <attribute>egressPolicyName</attribute>

            <attribute>name</attribute>

            <children>

               <resultFilter class="vpls.L2AccessInterfaceMldSnpgCfg">

                  <attribute>genQueryInterval</attribute>

                  <attribute>serviceId</attribute>

                  <attribute>lastMemberInterval</attribute>

               </resultFilter>

            </children>

         </resultFilter>

      </children>

   </resultFilter>

</generic.GenericObject.configureInstanceWithResult>

<generic.GenericObject.configureInstanceWithResultResponse xmlns="xmlapi_1.0">

   <configInfo>

      <vpls.Site>

         <serviceName>Service Name Change2</serviceName>

         <siteId>198.51.100.71</siteId>

         <objectFullName>svc-mgr:service-25:198.51.100.71</objectFullName>

         <name>Example Site A-9</name>

         <children-Set>

            <vpls.SiteMldSnooping>

               <administrativeState>disabled</administrativeState>

               <reportSrcAddressType>ipv6</reportSrcAddressType>

               <children-Set/>

            </vpls.SiteMldSnooping>

            <vpls.L2AccessInterface>

               <ingressPolicyName>Access Ingress-1</ingressPolicyName>

               <egressPolicyName>Access Egress-1</egressPolicyName>

               <name>Port 1/1/3:4.6</name>

               <children-Set>

                  <vpls.L2AccessInterfaceMldSnpgCfg>

                     <serviceId>10</serviceId>

                     <genQueryInterval>125</genQueryInterval>

                     <lastMemberInterval>10</lastMemberInterval>

                     <children-Set/>

                  </vpls.L2AccessInterfaceMldSnpgCfg>

               </children-Set>

            </vpls.L2AccessInterface>

         </children-Set>

      </vpls.Site>

   </configInfo>

</generic.GenericObject.configureInstanceWithResultResponse>

The following section provides XML sample requests to perform the following.

Configure an existing port.
Create an Epipe service.
Delete an Epipe service.

See the XML API SDK Sample Code Navigator for sample XML scripts.

To compose a configuration command that modifies, creates, or deletes an existing object, you need the following information:

the appropriate generic configuration method
the class of the object you want to configure (not required if deleting)
the full name of the object you want to configure
the deployment type (typically immediate). See Deployments for more information about deployments.

Modify example: To configure an existing port

The following example outlines the parameters required for an XML request to set the description on a port.

To compose a modification command, the key input parameters include:

method—generic.GenericObject.configureInstanceWithResult
class—equipment.PhysicalPort
full name—network:198.51.100.40:shelf-1:cardSlot-1:card:daughterCardSlot-1:daughterCard:port-10

Figure 15-3: Port configuration request example

<SOAP:Body>

   <generic.GenericObject.configureInstanceWithResult xmlns="xmlapi_1.0">

      <deployer>immediate</deployer>

      <distinguishedName>network:198.51.100.40:shelf-1:cardSlot-1:card:daughterCardSlot-1:daughterCard:port-10</distinguishedName>

      <includeChildren>false</includeChildren>

      <configInfo>

         <equipment.PhysicalPort>

            <actionMask>

               <bit>modify</bit>

            </actionMask>

            <description>to Mumbai</description>

         </equipment.PhysicalPort>

      </configInfo>

   </generic.GenericObject.configureInstanceWithResult>

</SOAP:Body>

For this sample request, other key input parameters include:

includeChildren - set to false, means do not include child info in the results
configInfo - desired values to which to configure object, and optionally children
- actionMask - specifies the modify operation
- description - specifies the attribute and value of the equipment.PhysicalPort class that is being modified

The results of the command are shown in the following figure. Results include all of the port attributes, but no children (as per includeChildren) in the configInfo parameter.

Figure 15-4: Port configuration response example

<generic.GenericObject.configureInstanceWithResultResponse xmlns="xmlapi_1.0">

   <configInfo>

      <equipment.PhysicalPort>

         <usedAsSyncReference>none</usedAsSyncReference>

         <cardSlotId>1</cardSlotId>

         <daughterCardSlotId>1</daughterCardSlotId>

         <specificCardType>

            <bit>mda_m60_faste_tx</bit>

         </specificCardType>

         <description>to Mumbai</description>

         <selfAlarmed>true</selfAlarmed>

      </equipment.PhysicalPort>

      <children-Set>

   </configInfo>

</generic.GenericObject.configureInstanceWithResultResponse>

Create example: To create an Epipe object

The following example outlines what is required for an XML request to create an Epipe object. The example only shows object creation, and does not include all of the child objects required to create a working service.

To compose a creation command, the key input parameters include:

method - generic.GenericObject.configureChildInstanceWithResult
class - epipe.Epipe
parent - svc-mgr. The fully distinguished name of the parent can be determined by looking at the Parent Hierarchy of the class to be created in the XML API Reference.

Figure 15-5: Epipe creation request example

<SOAP:Body>

   <generic.GenericObject.configureChildInstanceWithResult xmlns="xmlapi_1.0">

      <deployer>immediate</deployer>

      <synchronousDeploy>true</synchronousDeploy>

      <distinguishedName>svc-mgr</distinguishedName>

      <childConfigInfo>

         <epipe.Epipe>

            <actionMask>

               <bit>create</bit>

            </actionMask>

            <displayedName>Epipe Example 1</displayedName>

            <description>Epipe Example 1</description>

            <subscriberPointer>subscriber:1</subscriberPointer>

         </epipe.Epipe>

      </childConfigInfo>

   </generic.GenericObject.configureChildInstanceWithResult>

</SOAP:Body>

For this request, other key input parameters include:

distinguishedName - set to svc-mgr, this is the pointer to the parent object
childConfigInfo - desired values to configure the children information, in this case the child object is epipe.Epipe
- actionMask - set to create, specifies the creation operation
- displayedName, description, and subscriberPointer - these are the attributes and associated values that are set on the epipe.Epipe object

The results of the command are shown in the following figure. Results include all of the default Epipe attributes including the displayedName, description, and subscriberPointer that were set in the request.

Figure 15-6: Epipe creation response example

<generic.GenericObject.configureChildInstanceWithResultResponse xmlns="xmlapi_1.0">

   <childConfigInfo>

      <epipe.Epipe>

         <lastCacTime>0</lastCacTime>

         <cacStatus>notApplicab.e</cacStatus>

         <cacProbableCause>notApplicable</cacProbableCause>

         <defaultVcId>49</defaultVcId>

         <topologyAutoCompletion>false</topologyAutoCompletion>

         <transportPreference>any</transportPreference>

         <useBwReservedPath>noPreference</useBwReservedPath>

         <objectFullName>svc-mgr:service-10907</objectFullName>

         <displayedName>Epipe Example 1</displayedName>

         <description>Epipe Example 1</description>

         <subscriberPointer>subscriber:1</subscriberPointer>

         <selfAlarmed>false</selfAlarmed>

         <children-Set/>

      </epipe.Epipe>

   </childConfigInfo>

</generic.GenericObject.configureChildInstanceWithResultResponse>

Delete example: To delete an Epipe object

CAUTION

Service Disruption

Deleting an object deletes all of its child objects, so deleting the wrong object could delete an entire tree of objects.

The following example outlines what is required for an XML request to delete an Epipe service.

To compose a deletion command, the key input parameters include:

method - generic.GenericObject.deleteInstance
full name - svc-mgr:service-10907, from the creation example in Figure 15-5, Epipe creation request example

Figure 15-7: Epipe deletion request example

<SOAP:Body>

   <generic.GenericObject.deleteInstance xmlns="xmlapi_1.0">

      <deployer>immediate</deployer>

      <synchronousDeploy>true</synchronousDeploy>

      <distinguishedName>svc-mgr:service-10907</distinguishedName>

   </generic.GenericObject.deleteInstance>

</SOAP:Body>

The results of the command is in the following figure. An exception-free response indicates that the request was received and validated.

Figure 15-8: Epipe deletion response example

<generic.GenericObject.deleteInstanceResponse xmlns="xmlapi_1.0"/>