Configuration methods

Overview
CAUTION 

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 

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.

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:

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:

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:

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:

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:

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 

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:

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"/>

© 2023 Nokia. Nokia Confidential Information

Use subject to agreed restrictions on disclosure and use.