<directinvoke>

Use <directinvoke> to invoke services or web sites that are publically accessible on the Web. Web services must have a REST, SOAP or syndication (RSS/Atom) interface.

You can use a proxy server when mashups invoke services with <directinvoke>. This is determined by proxy server configuration for the EMML Reference Runtime Engine. See EMML Reference Runtime Engine Configuration for more information.

For examples, see <directinvoke> Basics, Passing Parameters in <directinvoke>, Adding HTTP Headers to <directinvoke> Requests, Getting Headers, Status Codes and Cookies from <directinvoke> Responses or Dynamic Endpoints or Parameters for <directinvoke>.

Can Contain	Empty
Allowed In	mashup, else, elseif, for, foreach, if, macro, operation, sequence, while,

Attributes

Name	Required	Description
endpoint	yes	The URI to the endpoint for the publicly accessible web service to invoke.
method		Either GET or POST.
requestbody		An optional attribute for the name of the variable containing the body of the request to send when `method = 'POST'`.
header		The name of a variable containing headers to use when this service is invoked. The payload in a headers variable must be in the form: <header> service-specific payload for headers </header>
feedtype		An optional attribute for syndication feeds identifying the protocol for normalization. Valid values include: rss = Normalizes the feed results to RSS 2.0. atom = Normalizes the feed results to Atom 1.0.
outputvariable	yes	The required variable to accept the output of this statement.
responseheader		An optional attribute for the name of the variable to receive HTTP headers from the response.
responsecode		An optional attribute for the name of the variable to receive the HTTP status code from the response.
cookies		An optional attribute for the name of the variable to receive cookies from the response.
bypassproxy		An optional attribute to have the invocation bypass the proxy server, if any. This is `false` by default.
timeout		The maximum number of minutes to wait for a response before terminating this service invocation. The default timeout is 5 minutes.
onerror		The behavior for the mashup script if errors occur when this service is invoked. Valid values include: abort = Stops all further mashup script processing after an invocation error. continue = Continues mashup script processing after an invocation error.

<directinvoke> Examples

<directinvoke> Basics

Add a <directinvoke> element to the mashup script. Identify the endpoint (the URL) to the service or web site, the HTTP method (GET or POST) to use to send the request and the outputvariable to receive the results from the web service or site.

Note: URLs sometimes include characters, such as & which must be escaped in XML. See XML Escaping in URLs and Expressions for more information.

If the HTTP method is POST, you must also put the body of the request in a variable and use the requestbody attribute to identify that variable. You can use other EMML statements to construct the request body or receive it as an input parameter.

You can also set bypassproxy to bypass the proxy server for this request.

If the endpoint is for a syndication service, you can also identify the format you want results normalized to in the feedtype attribute. Choose atom = ATOM 1.0, rss = RSS 2.0, or native = do not normalize the results.

Note: for Google News feeds, there is a known issue whenfeedtype = "atom". Simply remove the feedtype attribute to avoid this problem.

For example:

<directinvoke endpoint="http://www.myCompany.com/rest-services/getNames" 
    method="GET" outputvariable="$result"/> 
<directinvoke endpoint="http://www.AnotherSite.com/getInfo" 
    method="GET" bypassproxy="true" outputvariable="$result"/> 
<directinvoke endpoint="http://rss.news.yahoo.com/rss/topstories" 
    method="GET" feedtype="rss" outputvariable="$news"/> 
... 
<constructor outputvariable="xmlPost"> 
  <entry xmlns='http://www.w3.org/2005/Atom'> 
    <title type='text'>My First Blog</title> 
    <content type='xhtml'> 
      <div xmlns="http://www.w3.org/1999/xhtml"> 
        <p>This is my first blog and I’m not sure what to say.</p> 
        <p>"Hello World!" just seems silly.</p> 
      </div> 
    </content> 
    <author> 
      <name>Mia</name> 
      <email>mia@xyz.com</email> 
    </author> 
  </entry> 
</constructor> 
 
<directinvoke endpoint="$bloggerURL" outputvariable="$blogresult" 
    method="post" requestbody="$xmlPost" />

Passing Parameters in <directinvoke>

You can pass parameters to the service or web site using any attribute name that is not defined in EMML. These attributes can also have a namespace, if needed.

In the following example, the attributes query and appID are not defined in EMML. These will be passed as parameters to the service.

<directinvoke endpoint="http://www.myCompany.com/rest-services/getItems" 
    method="GET" outputvariable="$result" query="items=all" 
    appID="67GYH30N25" /> 
<directinvoke endpoint="http://www.svcsltd.com/getReservation" 
    method="GET" outputvariable="$news" xmlns:sc="http://www.svcltd.com/" 
    sc:date="20070515" sc:nights="3"/>

The second example shows the use of a namespace with additional attributes for request parameters. This namespace must be defined on the <mashup> element or on <directinvoke> itself.

Adding HTTP Headers to <directinvoke> Requests

You can define HTTP headers in variables and pass them in the request to the service or web site using the header attribute. The variable for the header must be a document type with a <headers> root node. Each HTTP header is an XML element child and the value for that header is the content of the XML element.

Note: you can use this syntax to pass basic HTTP authentication headers to a service.

For example:

<operation name="directWithHeaders"> 
  <variable name="httpHeader"> 
    <headers> 
      <Content-type>application/x-www-form-urlencoded</Content-type> 
    </headers> 
  </variable> 
... 
  <directinvoke endpoint="http://www.myCompany.com/rest-services/getItems" 
    method="GET" outputvariable="$result" header="$httpHeader" /> 
...

Getting Headers, Status Codes and Cookies from <directinvoke> Responses

The body of the response from the web service or web site is placed in the output variable you specify. You can use the following attributes in <directinvoke> to define variables to hold header and other information from the response:

responseheader = a variable to hold the HTTP headers from the response.
responsecode = a variable to hold the HTTP status code from the response.
cookies = a variable to hold any cookies returned by the response.

This example checks for the HTTP redirect status and invokes the service if it is detected:

<operation name="directWithCookiesEtc"> 
  <variables> 
    <variable name="result" type="document" /> 
    <variable name="redirecturl" type="string" /> 
    <variable name="responseHeader" type="document" /> 
    <variable name="responseCode" type="string" /> 
    <variable name="cookies" type="document" /> 
  </variables> 
  <directinvoke endpoint="http://myCompany.com/some-service/getDoc" 
    method="POST" outputvariable="$result" 
    responseheader="$responseHeader" responsecode="$responseCode" 
    cookies="$cookies" /> 
  <display message="Headers are" variable="$responseHeader" /> 
  <display message="Cookies are" variable="$cookies" /> 
  <display message="ResponseCode is" variable="$responseCode" /> 
  <if condition="number($responseCode)=302"> 
    <assign fromexpr="$responseHeader//Location/string()" 
      outputvariable="$redirecturl" /> 
    <display message="Redirect to " variable="$redirecturl" /> 
    <directinvoke endpoint="$redirecturl" method="GET" 
      responseheader="$responseHeader" outputvariable="$result" 
      responsecode="$responseCode" cookies="$cookies" /> 
  </if> 
...

Dynamic Endpoints or Parameters for <directinvoke>

You can use the <template> declaration to allow the endpoint or parameters for <directinvoke> to be set dynamically. This technique uses dynamic mashup expressions to resolve the URL. For example:

... 
  <!-- allow users to select a symbol --> 
  <input name="ticker" type="string" default="GOOG"/> 
  <!-- variable used to construct the dynamic endpoint --> 
  <variables> 
    <variable name="result" type="document" /> 
    <variable name="wholeURL" type="string" /> 
  </variables> 
  <!-- template to construct dynamic endpoint --> 
  <template expr="http://finance.yahoo.com/q/pr?s={$ticker}" 
    outputvariable="$wholeURL"/> 
  <directinvoke endpoint="$wholeURL" method="POST" outputvariable="$result" /> 
...

See Dynamic Mashup Syntax for more information and example on using <template>.

Enterprise Mashup Markup Language (EMML) Documentation is licensed
under a Creative Commons Attribution-Share Alike 3.0 United States License.