Unsupported content This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

ORCA web service example use case

This example use case demonstrates how you can use the BMC Atrium Orchestrator ORCA web service interface to execute the ls operating system command by remotely invoking the Command Line workflow.

Solution design

The workflow to be executed is located in the Auto-Pilot-AD-Utilities module, which is delivered with BMC Atrium Orchestrator content. This module contains workflows designed to enable the execution of operating system commands. The invocation of the workflow is performed using the SOAP UI tool. The SOAP UI tool is used to submit requests using the SOAP messages.

  1. Find the WSDL for the grid instance.
  2. Get the process description for the workflow to be invoked.
  3. Fill in the parameters.
  4. Execute the process.

Solution demonstration

The implementation of this integration begins by using WSDL for the instance of the grid to obtain the process description of the Command Line workflow. The SOAP message used is the getProcessDescription message type. The workflow process description is then used with the executeProcess message type to execute the ls command.

Note

The  Username and Password values in the examples on this page are example values. Use valid user name and password credentials for a user with workflow execution permissions.

  1. Get the process description:
    1. Download and install a SOAP UI tool.
    2. Start a new project in the SOAP UI tool.

    3. Using the following syntax example, enter the WSDL into the SOAP UI tool, and click OK  (use the appropriate protocol for your installation: https or http).

      WDSL syntax
      http(s)://<cdpHostName>:<port>/baocdp/orca?wsdl

      As shown in the following figure, the SOAP UI tool returns a tree view that contains the message types available in ORCA API.
      Screen shot 2011-06-01 at 5.48.33 PM.png

    4. Select getProcessDescription to display the message request details, as shown in the following figure:
      Screen shot 2011-06-01 at 10.38.57 PM.png
    5. Use Request 1 to create the ORCA request:
      1. Add the <wsse:Security> element to the <soapenv:Header> element.
      2. Add the username and password for your grid.
    6. To create the SOAP UI request for the getProcessDescription request, add the grid name to <soa:gridName>?</soa:gridName> and the process name to <soa:processName>?</soa:processName>.

    7. Submit the request to the CDP.

      Input to SOAP UI

      <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soa="http://bmc.com/ao/xsd/2008/09/soa">
         <soapenv:Header>
            <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
               <wsse:UsernameToken>
                  <wsse:Username>aoadmin</wsse:Username>
                  <wsse:Password>admin123</wsse:Password>
               </wsse:UsernameToken>
            </wsse:Security>
         </soapenv:Header>
         <soapenv:Body>
            <soa:getProcessDescription>
               <soa:gridName>Example_GRID</soa:gridName>
               <soa:processName>: AutoPilot-AD-Utilities:Terminal:Command Line</soa:processName>
            </soa:getProcessDescription>
         </soapenv:Body>
      </soapenv:Envelope>


      Response from SOAP UI

      <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soa="http://bmc.com/ao/xsd/2008/09/soa">
         <soapenv:Body>
            <soa:executeProcess>
               <soa:gridName>Example_Grid</soa:gridName>
               <soa:processName>:AutoPilot-AD-Utilities:Terminal:Command Line</soa:processName>
               <soa:parameters>
                  <!--Optional:-->
                  <soa:Input>
                     <!--Zero or more repetitions:-->
                     <soa:Parameter>
                        <soa:Name required="true">adapter name</soa:Name>
                        <!--Optional:-->
                        <!--Optional:-->
                        <soa:Value soa:type="xs:string">
                           <!--Optional:-->
                           <!--Optional:-->
                           <soa:Text></soa:Text>
                        </soa:Value>
                     </soa:Parameter>
                     <soa:Parameter>
                        <soa:Name required="true">command</soa:Name>
                        <soa:Value soa:type="xs:string">
                           <soa:Text></soa:Text>
                        </soa:Value>
                     </soa:Parameter>
                  </soa:Input>
                  <!--Optional:-->
               </soa:parameters>
            </soa:executeProcess>
         </soapenv:Body>
      </soapenv:Envelope>

  2. Using the response from step 1, add values for the following parameters: adapter name and command.

    <soa:parameters>
                <!--Optional:-->
                <soa:Input>
                   <!--Zero or more repetitions:-->
                   <soa:Parameter>
                      <soa:Name required="true">adapter name</soa:Name>
                      <!--Optional:-->
                      <!--Optional:-->
                      <soa:Value soa:type="xs:string">
                         <!--Optional:-->
                         <!--Optional:-->
                         <soa:Text>CMD_CDP</soa:Text>
                      </soa:Value>
                   </soa:Parameter>
                   <soa:Parameter>
                      <soa:Name required="true">command</soa:Name>
                      <soa:Value soa:type="xs:string">
                         <soa:Text>ls</soa:Text>
                      </soa:Value>
                   </soa:Parameter>
                </soa:Input>
                <!--Optional:-->
             </soa:parameters>

  3. Use the modified response as input to the executeProcess message.

    This XML document is the request that the external program must construct to communicate with the AutoPilot-AD-Utilities:Terminal:Command Line workflow. As shown in the following sample request, the <soa:Parameter> element is modified to include the command input attribute:

    <soa:Parameter>
            <soa:Name required="true">command</soa:Name>
            <soa:Value soa:type="xs:string">
            <soa:Text>ls</soa:Text>
            </soa:Value>
    </soa:Parameter>

    Complete request

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soa="http://bmc.com/ao/xsd/2008/09/soa">
       <soapenv:Header>
          <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
             <wsse:UsernameToken>
                <wsse:Username>aoadmin</wsse:Username>
                <wsse:Password>admin123</wsse:Password>
             </wsse:UsernameToken>
          </wsse:Security>
       </soapenv:Header>
       <soapenv:Body>
          <soa:executeProcess>
             <soa:gridName>IMWGrid</soa:gridName>
             <soa:processName>:AutoPilot-AD-Utilities:Terminal:Command Line</soa:processName>
             <soa:parameters>
                <!--Optional:-->
                <soa:Input>
                   <!--Zero or more repetitions:-->
                   <soa:Parameter>
                      <soa:Name required="true">adapter name</soa:Name>
                      <!--Optional:-->
                      <!--Optional:-->
                      <soa:Value soa:type="xs:string">
                         <!--Optional:-->
                         <!--Optional:-->
                         <soa:Text>CMD_CDP</soa:Text>
                      </soa:Value>
                   </soa:Parameter>
                   <soa:Parameter>
                      <soa:Name required="true">command</soa:Name>
                      <soa:Value soa:type="xs:string">
                         <soa:Text>ls</soa:Text>
                      </soa:Value>
                   </soa:Parameter>
                </soa:Input>
                <!--Optional:-->
             </soa:parameters>
          </soa:executeProcess>
       </soapenv:Body>
    </soapenv:Envelope>

    Response

    <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
       <S:Body>
          <ns1:executeProcessResponse xmlns:ns1="http://bmc.com/ao/xsd/2008/09/soa">
             <ns1:Output>
                <ns1:Output>
                   <ns1:Parameter>
                      <ns1:Name>adapter response</ns1:Name>
                      <ns1:Value ns1:type="xs:anyType">
                         <ns1:XmlDoc>
                            <command-result>
                               <metadata>
                                  <status>success</status>
                               </metadata>
                               <targets-output>
                                  <target-output>
                                     <metadata>
                                        <os-id>Linux</os-id>
                                        <os-version>2.6.9-55.0.2.ELsmp</os-version>
                                        <os-arch>i386</os-arch>
                                        <status>success</status>
                                     </metadata>
                                     <commands-output>
                                        <command-output>
                                           <metadata>
                                              <command>ls</command>
                                              <working-dir/>
                                              <command-dir/>
                                              <line-count>4</line-count>
                                              <execution-milliseconds>120</execution-milliseconds>
                                              <exit-code>0</exit-code>
                                              <status>success</status>
                                           </metadata>
                                           <output>
                                              <line index="1">bao.sh</line>
                                              <line index="2">fix_perm.sh</line>
                                              <line index="3">server.pid</line>
                                              <line index="4">server.sh</line>
                                           </output>
                                        </command-output>
                                     </commands-output>
                                  </target-output>
                               </targets-output>
                            </command-result>
                         </ns1:XmlDoc>
                      </ns1:Value>
                   </ns1:Parameter>
                </ns1:Output>
             </ns1:Output>
          </ns1:executeProcessResponse>
       </S:Body>
    </S:Envelope>

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*