Bookmark and Share Share

Declaring Mashup Variables and Parameters

Typically, mashups, operations and macros have one output parameter to hold the mashup or macro result. You can also declare any number of input parameters to pass data to mashups, operations or macros.

Note: only one <output> declaration can occur in a mashup, operation or macro. Validation for mashup scripts or macro libraries will not flag multiple <output> declarations as an error. You will, however, receive an error when debugging the mashup script.

You can also declare variables in mashups, operations, macros or other control statements that allow nested EMML statements in order to work with data in the mashup or macro. For example, you can declare variables within <foreach>.

You must declare parameters explicitly. With variables, you can declare them explicitly or you can create variables implicitly by assigning a name to the outputvariable attribute for any statement. Variables and parameters must be declared (explicitly or implicitly) before they are used in any other EMML statement.

Variables and parameters all have a name, a datatype, data (a value) and a scope. They may also have a default value. See Valid Names for Variables and Parameters, Datatypes for Variables and Parameters, Default and Constructed Values, Variable and Parameter Scopes and Referencing Parameters and Variables for more information and examples.

Valid Names for Variables and Parameters

Variable and parameter names must follow these rules to be valid:

  • They cannot use the following reserved names:

    • fault

    • faultcode

    • faultexception

    • faultmessage

    These reserved names are used for service invocation error handling.

  • They can use the reserved name httpResponse.header-name to define standard or custom HTTP headers for the mashup result. For custom HTTP headers, header-name must begin with x-.

  • They must be unique within the scope that they are declared in. However, local variables can use the same name as global variables. See Variable and Parameter Scopes for more information.

  • They must start with an ASCII letter.

  • They can contain ASCII letters, numbers, dashes (-) or underscores (_). Do not use any other symbols or punctuation.

Datatypes for Variables and Parameters

Variable and parameter data can be scalar values or complex objects:

Scalar Types string
number
data
boolean
Complex Types (objects) document

Any token that identifies a named type from a specific service. The service attribute must be used with named types.

With this complex type, service metadata provides type information for the token.

Variables that are implicitly declared always have a document type. See also Valid Date Formats for Mashup Scripts for more information on support for date formats.

For example: 

<output name="result" type="document"/> 
<input name="securityType" type="svc:certType" service="Credentials"/> 
<input name="previousDays" type="boolean"/> 
 
<variables> 
  <variable name="loops" type="number"/> 
  <variable name="amznResult" type="document"/> 
  <variable name="user.email" type="string"/> 
</variables>

Document type variables are represented in XML. The EMML Reference Runtime Engine automatically converts the results of component services to XML for any variable that holds complex objects.

You can also construct complex data for variables or parameters as literal XML. See Default and Constructed Values for information and examples on constructing data.

Default and Constructed Values

Most parameters and variables are assigned data by an EMML statement or as parameters passed into the mashup when it is invoked.

You can define default values for variables and parameters with a scalar datatype. Use the default attribute. You cannot set a default for variables or parameters with a complex datatype. For example: 

<input name="queryDate" type="date" default="2007-03-01"/> 
... 
<variables> 
  <variable name="key" type="string" default="1SF8BTKBTXN6XP68BY02"/> 
  <variable name="httpResponse.Content-type" type="string" 
        default="text/csv; charset=UTF-8" 
</variables>

You can, however, construct the data for a variable or parameter that has a complex datatype by defining the XML and data literally within <variable>, <input> or <output>.

Note: if you define the content of <output> using literal XML, this is the only output for the mashup or macro.

Add the XML within <variable>, <input> or <output>. It is a good practice to define a separate namespace for this literal XML to clearly differentiate from EMML. Enter any literal data you want or use Dynamic Mashup Expressions to provide the data dynamically. For example: 

<inputparam name="query"> 
  <svc:query> 
    <svc:category>books</svc:category> 
    <svc:ranking>allResults<svc:ranking> 
    <svc:date>{$queryDate}</svc:date> 
    <svc:maximum>100</svc:maximum> 
  </svc:query> 
</inputparam> 
<variables> 
  <variable name="header" type="document"> 
    <header> 
      <Authorization>GoogleLogin auth={$auth}</Authorization> 
      <Content-Type>application/atom+xml</Content-Type> 
    </header> 
  </variable> 
  <variable name="soapRequest" type="document"> 
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                   xmlns:enc="http://schemas.xmlsoap.org/soap/encoding" > 
      <soap:Header>{$soapHeader}</soap:Header> 
      <soap:Body>{$soapBody}</soap:Body> 
    </soap:Envelope> 
  </variable> 
</variables>

You can also construct variables using some EMML statements. See Constructing the Mashup Result, Input or Intermediate Variables for links and information.

Variable and Parameter Scopes

Variables may have a global scope or a local scope. Variables that have a global scope can be used in any statement in the mashup after they have been declared (explicitly or implicitly). Variables with a local scope are only valid within the statement where they are declared or any descendant statements. They are not valid until they have been declared.

If both global and local variables use the same name, the local variable is used within its scope and the global variables is used everywhere else.

Input and output parameters have a global scope when they are declared in <mashup> or <operation>. Parameters declared in <macro> are only valid within the macro itself. Mashups that use macros, however, do have access to the macro result. See Calling a Macro in a Mashup Script for more information.

Variables declared explicitly in <mashup> or <operation> or declared implicitly by any statement that is a direct child of <mashup> or <operation> have a global scope. Variables declared explicitly within EMML statements or declared implicitly by nested statements have a local scope of that containing statement.

Referencing Parameters and Variables

You refer to parameters or variables in mashup scripts within XPath expressions or in dynamic mashup expressions in the form:

$parameter-or-variable-name

This is also true for variables that you declare implicitly.

In this first example, an existing parameter or variable named variableA is used in an XPath expression to assign a portion of this variable to a new, implicitly declared variable named implicitVar.

<assign fromexpr="$variableA/item/name" outputvariable="$implicitVar"/> 
... 
<assign fromvar="$inputParamA" outputvariable="$declaredVariable"/>

The second example simply refers to an existing input parameter, inputParamA, and an existing variable, declaredVariable.