Selecting stubs to be published

You can use various options to select stubs to be published.

Specifying a stub filter

To control which stubs are published, use the stubFilter option. By default, all stubs within the project are published. Stub filters can be used to identify the stub or stubs you want to publish. There are two ways of identifying stubs. The first is to specify the names of the components, operation, and folders where the stub resides or to specify the name of the stub. The second is to use the unique identifier of the stub or stubs.

Using names

To specify the information on the command line, you specify XML-like tags with an appropriate name. For example, to publish all stubs under a component that is called Test Component, the following stub filter is sufficient:

 --stubFilter "<C>Test Component</C>"

Here, the tag <C> denotes filtering by a component name. In this context, a component refers to any top-level node that acts as a container for stubs. Examples are service component, database server, WebSphere® Application Server component, WSDL component.

You can specify the following tags:

 <C> or <c> - for Component path
 <O> or <o> - for Operation name
 <F> or <f> - for Folder path
 <S> or <s> - for Stub name

All tags are optional and can be defined in any order. If a tag value is not supplied, it defaults to accepting any value for that component, operation, or folder filter. The following filter publishes all stubs that belong to an operation called Send Message no matter what component and folder structure they belong to:

 --stubFilter "<O>Send Message</O>"

The following filter publishes a stub that is named StubA that is available under an operation Op1 and service component SC1:

 -stubFilter "<C>SC1</C><O>Op1</O><S>stubA</S>"

If multiple instances of the same tag are included in the filter, only the last tag is used. To publish to multiple components, operations or folders, you define multiple filters on the command by separating each one with a semi-colon (;). For example, the following filter publishes all stubs under the component Component 1 that belong to the Buy operation and also publishes all stubs under the Big Database component that are included under the myFolder folder:

 --stubFilter "<C>Component 1</C><O>Buy</O>;<C>Big Database</C><F>/myFolder</F>"

There is no limit to the number of filters that you can specify this way.

Because components and folders can be nested, the component and folder tags specify a component or folder hierarchy by separating each one by a forward slash (/). A preceding and terminating slash is not required though supported. For example, to publish only StubC in the following project hierarchy, the following filter is sufficient:

Test Factory.
 --stubFilter "<C>CompA/CompC</C><O>OpB</O><F>FolderA/FolderB</F>"

Instead of specifying the value of a tag, you can use the wildcard character, an asterisk (*). This filter accepts any value for a node that is represented by that tag. For example, to publish all stubs under the Send Message operation in any component, the following filter is sufficient:

 --stubFilter "<C>*</C><O>Send Message</O>"

A wildcard is the default value when not specified as part of the filter. If a stub filter contains invalid content such as incorrectly closed tags or data that does not match one of the supported tags, stub publishing fails and you are informed that your filter definition contains invalid data.

Note: This syntax contains special characters so, in the context of Ant tasks, they must be escaped, or be loaded from a file by using the property file tag:
 <property file="stub_publish.properties"/>

Using identifiers

If the identifier of the stub is known, the stub filter can simply specify the identifier, for example:
 --stubFilter -7d2c40d7:154befaa75f:-7d17
Note: You can find the identifier by opening the stub and looking at the Internal ID field in the Stub Documentation tab.

Specifying publish versions

There are several options available for specifying the version at which to publish the stubs at. First, if no major or minor value is specified, the latest value on the server is used, thus overwriting the most recent publish. If this is the first publish, the publish fails and you are asked to specify a concrete version. For example, to specify a specific version value to publish, enter the value on the command line:
--majorVersion 3 --minorVersion 1
A special value of ++ can be assigned as a version value, which increments the latest publish version of the server by 1. For example, if the latest version of the project on the server is 3.1, the following settings publish at version 3.2:
--minorVersion ++

updateMode

The updateMode option can be specified to further control which stubs are published. This command can take two values:
all
The default value. Any stubs that are matched by the stubFilter are published.
latest
Before you publish to the server, the command queries the server for information about the latest version of the project previously published. After the stubs are matched by the stubFilter, this update mode publishes only those stubs that were present in the most recent version. This method effectively limits the command so that no new stubs are published according to the latest version of the server.
For example, assume that a server has the following publish history for a project that contains three stubs: StubA, StubB, and StubC.
Version Published Stubs
1 StubA, StubB, and StubC
2 StubA and StubB
By specifying an updateMode value of latest, the command is limited to publish only StubA and StubB because these are the only stubs present in the most recent published version on the server. If a stub filter was specified that matched all stubs, StubC cannot be published due to the updateMode.

The Options file

The options file can be used to pass both simple and complex options to the command interfaces. This method is available for any interface, which supports the optionsFile option.

Table 1. Example Options file
<?xml version="1.0" encoding="UTF-8"?>
<publishStubs>
    <serverUrl>https://localhost:5443/RTCP</serverUrl>
    <project>C:\PublishDemo\PublishDemo.ghp</project>
    <domain>dev</domain>
    <environment>env</environment>
    <updateMode>all</updateMode>
    <majorVersion increment="true" />
    <securityToken>ABCDEFG</securityToken>
    <stubFilter>
        <component name="component">
            <operation name="operation">
                <folder name="folder1">
                    <folder name="folder2"/>
                </folder>
            </operation>
            <operation name="operation2"/>
            <component name="nestedComponent">
                <component name="nestedComponent2">
                    <folder name="folder3"/>
                    <folder name="folder4"/>
                        <stub name="stubX"/>
                </component>
            </component>
        </component>
    </stubFilter>
    <stubFilter>
        <component name="otherComponent"/>
        <component name="otherOtherComponent"/>
        <identifier value="-8dsde0d7:144bfcea75f:-4e12"/>
    </stubFilter>
</publishStubs>
where:
publishStubs
The containing element. Its name must match with the command it is being used for.
To specify a publish-stubs command option in the file, you add an XML element under the publishStubs root with a name corresponding to the name of the option on the command line. If an element is not present in the file for a non-mandatory option, the default value for that option is used. If you do not specify a mandatory option in the file, you must override it on the command line otherwise the publish operation fails.

Specifying publishing versions

Rather than specifying a concrete version value to use for the publish, you can set the 'increment' attribute to true or false for the majorVersion and minorVersion elements. This setting causes the command to get the latest version value of the project on the server for the given domain and environment. If increment is set to true, the latest version value on the server is incremented by one and used as the version value for the current publish.

Specifying a stub filter

You specify a stub filter to select which stubs are published by the command. If a filter is not specified, all stubs found in the project are published by default.

In the options file, you specify a stub filter by adding component, operation, folder, stub, or identifier XML elements as child elements of the stubFilter element. The component, operation, folder, and stub elements must include a name attribute and the hierarchy of these elements must match the path to one or more stubs to be published in the Test Factory perspective within HCL DevOps Test Integrations and APIs (Test Integrations and APIs).

For example, given the following hierarchy:

Test Factory.

the following stubFilter entry in the options file can be used to publish only StubC.

<stubFilter>
   <component name="CompA">
      <component name="CompC">
         <operation name="OpB">
           <folder name="FolderA">
              <folder name="FolderB"/>
           </folder>
         </operation>
      </component>
   </component>
</stubFilter>

the following stubFilter entry in the options file can be used to publish only StubB.

<stubFilter>
   <component name="CompA">
      <component name="CompC">
         <operation name="OpB">
           <folder name="FolderA">
              <stub name="StubB"/>
           </folder>
         </operation>
      </component>
   </component>
</stubFilter>

Alternatively, rather than using a hierarchy, if the identifier of StubA is -7d2c40d7:154befaa75f:-7d17 then the following stubFilter can be used to publish only StubA.

<stubFilter>
   <identifier value="-7d2c40d7:154befaa75f:-7d17"/>
</stubFilter>
Note: The identifier element must be a direct child of the stubFilter element. It must specify a value attribute.