Share:|

BAO offers two web service interfaces in the 7.x Platform referred to as Legacy and ORCA.  The WSDL's for these web services can be located at the following paths (substitute your own server, port and grid names below):

 

So why are there two interfaces and what are the differences?

Legacy Web Services

As you can guess from the name, this API came first.  The workflow developer identifies which workflows they want to expose for web services via the "Expose Process: As SOAP" option on the workflows Edit Process Properties window.  Only the workflows that have this property set will be included in the WSDL.  The Grid Administrator can further restrict what users/groups can run these workflow with the Grid Manager \ Administration \ Permissions screen.

The WSDL will list synchronous operations for each exposed workflow, detailing the Input and Output Parameters with descriptions for the operations Input and Output message formats.

ws1.png

ws2.png

The following is the request and response received via soapUI for the example workflow Calculator that expects a Operation, Number1, Number2 and returns a Result.

REQUEST:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:realops.com:amp:workflow" xmlns:oas="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:web="Web_Service_Demo">
   <soapenv:Header>
      <urn:grid-name>GRID1</urn:grid-name>
      <oas:Security>
         <oas:UsernameToken>
            <oas:Username>aosoap</oas:Username>
            <oas:Password Type="?">Yde3kSt78392md20x20z</oas:Password>
         </oas:UsernameToken>
      </oas:Security>
   </soapenv:Header>
   <soapenv:Body>
      <web:Calculator-Request>
         <web:Operation>ADD</web:Operation>
         <web:Number1>5</web:Number1>
         <web:Number2>2</web:Number2>
      </web:Calculator-Request>
   </soapenv:Body>
</soapenv:Envelope>
RESPONSE:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <Calculator-Response xmlns="Web_Service_Demo">
         <Result>7</Result>
      </Calculator-Response>
   </soapenv:Body>
</soapenv:Envelope>

ORCA Web Services

This interface was developed to provide a more programatic capability against Atrium Orchestrator and exposes features to Query Modules, Workflows, and describe the various Input and Output Parameters for a given workflow .  It also allows for both the Synchronous and Asynchronous execution of a workflows.

 

This is the web services interface that Remedy uses by default when creating Filters to call Atrium Orchestrator.  It is how within the Remedy Development GUI the user is offered a Drop Down list of Modules, and upon Module Selection a list of Workflows, and finally when an individual Workflow is selected, is shown all the input and output fields for mapping to Remedy values.

 

The following XML Requests and Responses come from soapUI a great tool for generating test calls against the Atrium Orchestrator web service API's.  Note that the <soapenv:Header> section for the ORCA API has to be manually inserted/edited as per the examples below.  This step is covered in the official online documentation for the Atrium Orchestrator Web Services.

 

Query Modules Name Example

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 xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soapenv:mustUnderstand="1">
<wsse:UsernameToken>
<wsse:Username>aosoap</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">Yde3kSt78392md20x20z</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>

   <soapenv:Body>
      <soa:queryModuleNames>
         <soa:gridName>GRID1</soa:gridName>
         <soa:pattern></soa:pattern>
      </soa:queryModuleNames>
   </soapenv:Body>
</soapenv:Envelope>
RESPONSE:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns1:queryModuleNamesResponse xmlns:ns1="http://bmc.com/ao/xsd/2008/09/soa">
         <ns1:ModuleName>Web_Service_Demo</ns1:ModuleName>
      </ns1:queryModuleNamesResponse>
   </S:Body>
</S:Envelope>

 

Query Workflows in a Module

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 xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soapenv:mustUnderstand="1">
<wsse:UsernameToken>
<wsse:Username>aosoap</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">Yde3kSt78392md20x20z</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
   <soapenv:Body>
      <soa:queryProcessNames>
         <soa:gridName>GRID1</soa:gridName>
         <soa:moduleName>Web_Service_Demo</soa:moduleName>
         <soa:pattern></soa:pattern>
      </soa:queryProcessNames>
   </soapenv:Body>
</soapenv:Envelope>
RESPONSE:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns1:queryProcessNamesResponse xmlns:ns1="http://bmc.com/ao/xsd/2008/09/soa">
         <ns1:ProcessName>:Web_Service_Demo:Calculator</ns1:ProcessName>
      </ns1:queryProcessNamesResponse>
   </S:Body>
</S:Envelope>

 

Get Process Description

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 xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soapenv:mustUnderstand="1">
<wsse:UsernameToken>
<wsse:Username>aosoap</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">Yde3kSt78392md20x20z</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
   <soapenv:Body>
      <soa:getProcessDescription>
         <soa:gridName>GRID1</soa:gridName>
         <soa:processName>:Web_Service_Demo:Calculator</soa:processName>
      </soa:getProcessDescription>
   </soapenv:Body>
</soapenv:Envelope>
RESPONSE:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns1:getProcessDescriptionResponse xmlns:ns1="http://bmc.com/ao/xsd/2008/09/soa">
         <ns1:Description>
            <ns1:Name>:Web_Service_Demo:Calculator</ns1:Name>
            <ns1:PeerLocation>ANY</ns1:PeerLocation>
            <ns1:Description>A Simple Calculator that takes in an Operation and two numbers and returns the result.  Operations Supported are Addittion, Subtraction, Multiplication and Division.</ns1:Description>
            <ns1:Parameters>
               <ns1:Input>
                  <ns1:Parameter>
                     <ns1:Name required="true">Number1</ns1:Name>
                     <ns1:Description>The First number in the operation</ns1:Description>
                  </ns1:Parameter>
                  <ns1:Parameter>
                     <ns1:Name required="true">Number2</ns1:Name>
                     <ns1:Description>The Second number in the operation</ns1:Description>
                  </ns1:Parameter>
                  <ns1:Parameter>
                     <ns1:Name required="true">Operation</ns1:Name>
                     <ns1:Description>ADD, DELETE, MULTIPLY,DIVIDE</ns1:Description>
                  </ns1:Parameter>
               </ns1:Input>
               <ns1:Output>
                  <ns1:Parameter>
                     <ns1:Name required="false">Result</ns1:Name>
                     <ns1:Description>Result of the mathematical operation</ns1:Description>
                  </ns1:Parameter>
               </ns1:Output>
            </ns1:Parameters>
         </ns1:Description>
      </ns1:getProcessDescriptionResponse>
   </S:Body>
</S:Envelope>

 

Now lets see a call to the Calculator operation

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 xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soapenv:mustUnderstand="1">
<wsse:UsernameToken>
<wsse:Username>aosoap</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">Yde3kSt78392md20x20z</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
   <soapenv:Body>
      <soa:executeProcess>
         <soa:gridName>GRID1</soa:gridName>
         <soa:processName>:Web_Service_Demo:Calculator</soa:processName>
         <soa:parameters>
            <soa:Input>
               <soa:Parameter>
                  <soa:Name required="true">Number1</soa:Name>
                  <soa:Value soa:type="string">
                     <soa:Text>144</soa:Text>
                  </soa:Value>
               </soa:Parameter>
               <soa:Parameter>
                  <soa:Name required="true">Number2</soa:Name>
                  <soa:Value soa:type="string">
                     <soa:Text>6</soa:Text>
                  </soa:Value>
               </soa:Parameter>
               <soa:Parameter>
                  <soa:Name required="true">Operation</soa:Name>
                  <soa:Value soa:type="string">
                     <soa:Text>DIVIDE</soa:Text>
                  </soa:Value>
               </soa:Parameter>
            </soa:Input>
            <soa:Output soa:type="anyType" />
         </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:type="anyType">
               <ns1:Parameter>
                  <ns1:Name>Result</ns1:Name>
                  <ns1:Value ns1:type="xs:anyType">
                     <ns1:XmlDoc>
                        <value>24</value>
                     </ns1:XmlDoc>
                  </ns1:Value>
               </ns1:Parameter>
            </ns1:Output>
         </ns1:Output>
      </ns1:executeProcessResponse>
   </S:Body>
</S:Envelope>

 

Calling Calculator from Visual Basic

The following example visual basic script can be executed from the Windows Server 2003 and 2008 R2 Command Line utilizing the Microsoft CSCRIPT program as per the runtime example output.

' Author: Robin Elliott
' Date: 10/24/2009
' Warranty: This code example comes with no warranty whatsoever.  Please use it as a basis for your own script development

Wscript.echo("")

Const URL = "http://192.168.1.51:38080/baocdp/orca"

' Create the input parameter array
Dim parameters(3,2)
parameters(0,0) = "Number1"
parameters(0,1) = "string"
parameters(0,2) = "5"
parameters(1,0) = "Number2"
parameters(1,1) = "string"
parameters(1,2) = "2"
parameters(2,0) = "Operation"
parameters(2,1) = "string"
parameters(2,2) = "ADD"

' Create the http request text
Dim strSoapReq
strSoapReq = GenerateSoapBodyStart("aosoap", "Yde3kSt78392md20x20z")
strSoapReq = strSoapReq + generateStaticBody("GRID1", ":Web_Service_Demo:Calculator", parameters)
strSoapReq = strSoapReq + GenerateSoapBodyEnd()

' Just for debug show the request to the screen
rem Wscript.echo("SOAP Request: " + strSoapReq )
rem Wscript.echo("")

Dim oHttp
Dim strResult

' Call the BAO orca Web Service and get the result
Set oHttp = CreateObject("Msxml2.XMLHTTP")
oHttp.open "POST", URL, false
oHttp.setRequestHeader "Content-Type", "text/xml"
oHttp.setRequestHeader "SOAPAction", URL
oHttp.send strSoapReq
strResult = oHttp.responseText

' Just for debug show the response to the screen
Wscript.echo("SOAP Response: " + strResult )
REM Wscript.echo("DONE")

' Just for debug show a element from the result accessed via xPath
'Wscript.echo("value Response: " + GetResult(oHttp.responseText, "//*/value") )

' Function that applies an xPath statment to the result and assumes it will result in a single node.
' For more info on what you could do against this Msxml2.DOMDocument look here http://msdn.microsoft.com/en-us/library/ms757828%28VS.85%29.aspx
Function GetResult(byval responseText, byval resultParam)

    Dim oXml
    Set oXml = CreateObject("Msxml2.DOMDocument")
    oXml.Async = true
    oXml.LoadXml responseText

    Dim strPath
    strPath = "//*" + resultParam
    Dim oNode
    Set oNode = oXml.documentElement.SelectSingleNode(strPath)
    GetResult = oNode.Text

End Function 

' Builds our SOAP header including the required Security section
Function GenerateSoapBodyStart(byval username, byval password)

    Dim strSoap
    strSoap = "<?xml version=""1.0"" encoding=""utf-8""?>"
    strSoap = strSoap + "<soapenv:Envelope "
    strSoap = strSoap + "xmlns:soapenv=""http://schemas.xmlsoap.org/soap/envelope/""> "
    strSoap = strSoap + "<soapenv:Header> "
    strSoap = strSoap + "<wsse:Security xmlns:wsse=""http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"" soapenv:mustUnderstand=""1""> "
    strSoap = strSoap + "<wsse:UsernameToken> "
    strSoap = strSoap + "<wsse:Username>"+username+"</wsse:Username> "
    strSoap = strSoap + "<wsse:Password Type=""http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"">" + password + "</wsse:Password> "
    strSoap = strSoap + "</wsse:UsernameToken> "
    strSoap = strSoap + "</wsse:Security> "
    strSoap = strSoap + "</soapenv:Header> "
    strSoap = strSoap + "<soapenv:Body>"
    GenerateSoapBodyStart = strSoap

End Function

' Closes out the Body of the soap call
Function GenerateSoapBodyEnd()

    Dim strSoap
    strSoap = "</soapenv:Body>"
    strSoap = strSoap + "</soapenv:Envelope>"
    GenerateSoapBodyEnd = strSoap

End Function

' Generates the start and populates the Input paramters into the Body.  Also writes the output section.
Function generateStaticBody(byval gridname, byval processname, byval parameters)
    Dim strSoap
    strSoap = strSoap + "<soa:executeProcess xmlns:soa=""http://bmc.com/ao/xsd/2008/09/soa""> "
    strSoap = strSoap + "<soa:gridName>" + gridname + "</soa:gridName> "
    strSoap = strSoap + "<soa:processName>" + processname + "</soa:processName> "
    strSoap = strSoap + "<soa:parameters> "
           strSoap = strSoap + "<soa:Input> "
    For i = 0 To UBound(parameters, 1) 
               strSoap = strSoap + GenerateSoapParameter(parameters(i,0), parameters(i,1), parameters(i,2))
    Next
    strSoap = strSoap + "</soa:Input> "
    strSoap = strSoap + "<soa:Output soa:type=""xs:anyType"" /> "
    strSoap = strSoap + "</soa:parameters> "
    strSoap = strSoap + "</soa:executeProcess> "
    generateStaticBody = strSoap
End Function

' Adds a input parameter to the string being built
Function GenerateSoapParameter(byval strParamName, byval strType, byval strValue)
    Dim strSoap
    strSoap = "<soa:Parameter> "
    strSoap = strSoap + "<soa:Name required=""true"">" + strParamName + "</soa:Name> "
    strSoap = strSoap + "<soa:Value soa:type=""xs:" + strType + """> "
    strSoap = strSoap + "<soa:Text>" + strValue + "</soa:Text> "
    strSoap = strSoap + "</soa:Value> "
    strSoap = strSoap + "</soa:Parameter> "
    GenerateSoapParameter = strSoap
End Function

 

ws3.png

 

Calling Calculator form Perl

 

I am going to cross link to a great utility called iCommand that was written by Richard de Vries which utilizes Perl and the ORCA API to run workflows iCommand (beta) - Command Line Interface into AO

 

ws6.png

 

Also find below a quick and specific example Perl script that utilizes the ORCA API to execute the Calculator workflow synchronously.


#######################################
#
# BMC Software, Inc.
# No Warranty is expressed or implied in this code example 
#
# Created by Stathy G. Touloumis
# Edited by Robin Elliott
#
#######################################

use strict;
use warnings;

use LWP::UserAgent;
use HTTP::Request::Common;

my $host = q(192.168.1.51);
my $port = 38080;
my $user = q(aosoap);
my $pwd = q(Yde3kSt78392md20x20z);
my $module = q(Web_Service_Demo);
my $process = q(Calculator);
my $grid = q(GRID1);

my $soap_req = <<SOAP;
      <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
        <soapenv:Header>
          <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soapenv:mustUnderstand="1">
            <wsse:UsernameToken>
              <wsse:Username>${user}</wsse:Username>
              <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">${pwd}</wsse:Password>
            </wsse:UsernameToken>
          </wsse:Security>
        </soapenv:Header>
        <soapenv:Body>
          <soa:executeProcess xmlns:soa="http://bmc.com/ao/xsd/2008/09/soa">
            <soa:gridName>${grid}</soa:gridName>
            <soa:processName>:${module}:${process}</soa:processName>
            <soa:parameters>
          <soa:Input>
               <soa:Parameter>
                  <soa:Name required="true">Number1</soa:Name>
                  <soa:Value soa:type="string">
                     <soa:Text>5</soa:Text>
                  </soa:Value>
               </soa:Parameter>
               <soa:Parameter>
                  <soa:Name required="true">Number2</soa:Name>
                  <soa:Value soa:type="string">
                     <soa:Text>12</soa:Text>
                  </soa:Value>
               </soa:Parameter>
               <soa:Parameter>
                  <soa:Name required="true">Operation</soa:Name>
                  <soa:Value soa:type="string">
                     <soa:Text>SUBTRACT</soa:Text>
                  </soa:Value>
               </soa:Parameter>
            </soa:Input>
              <soa:Output soa:type="xs:anyType" />
            </soa:parameters>
          </soa:executeProcess>
        </soapenv:Body>
      </soapenv:Envelope>
SOAP

# Uncomment the following line to debug and print the SOAP request
# print $soap_req;

my $ua = LWP::UserAgent->new(agent=> 'bao soap');
my $res = $ua->request(
  POST qq(http://${host}:${port}/baocdp/orca)
  , Content_Type=> 'text/xml'
  , Content=> $soap_req
);

print $res->error_as_HTML unless $res->is_success;

print $res->as_string;

1;

 

ws4.png