Working with Variables

A variable can be a String, String list, String table, document, document list, document reference, document reference list, Object, or Object list. Variables are used to declare the expected content and structure of service signatures, document contents, and pipeline contents. In addition to specifying the name and data type of a variable, you can set properties that specify an XML namespace, indicate whether the variable is required at runtime, and indicate whether the variable can be null at runtime.

Select a variable in the editor to set general properties and constraints for the variable. Specific properties in the Properties view are enabled or disabled, depending on the type of variable you have selected.

Note: Do not use the % symbol in variable names. The % symbol is a reserved character because it is used in expressions for BRANCH steps and trigger filters.
Note: Be careful when renaming variables. If a variable is used in pipeline mapping, renaming the variable might result in the pipeline containing a variable with the new name and a variable with the old name. In this situation, the variable with the old name would retain the pipeline mapping. To avoid this, refactor the variable instead. For more information about refactoring, see Refactoring Variable Names in Elements.

Creating a Document Reference or a Document Reference List Variable

About this task

You can use an IS document type (including a publishable document type) to build a document reference or document reference list field. By referencing an IS document type instead of creating a new one, you can reduce the time required to create fields and maintain better consistency for field names. You might find referencing fields especially useful for information that is repeated over and over again, such as address information.

Keep the following points in mind when using IS document types to create document references or document reference lists.

  • If you are creating a document reference or document reference list field based on an IS document type, you cannot directly add, delete, or modify its members in the Input/Output tab. To edit the referenced document or document list, select it in the Package Navigator view, lock it, and then edit its fields in the editor.
  • You can also add a document reference by dragging an IS document type from the Package Navigator view to the Document Type editor.

To use a document type to build a document reference or document reference list

Procedure

  1. In Package Navigator view, open the document type that you want to reference.
  2. On the editor palette, click and drag one of the following into the editor window:
    Click and drag... To...
    Document Reference Create a document field based on an IS document type.
    Document Reference List Create a document list field based on an IS document type.
  3. In the Element Name field, type the fully qualified name of the IS document type or select it from the list.
  4. Click OK.
  5. Type the name of the field.
  6. Click File > Save.

Using XML Namespaces and Namespace Prefixes with Variables

You can assign an XML namespace and prefix to a variable by specifying a URI for the XML namespace property and by using the following format for the variable name:

prefix:variableName

This creates a QName for the variable in which portions of the variable name are used as the prefix and local name and the value of the XML namespace property is the namespace name. For example, suppose that a variable is named eg:account and the XML namespace property is set to http://www.example.com. The prefix is eg, the localname is account and the namespace name is http://www.example.com.

When generating XML Schema definitions and WSDL documents, Integration Server uses the value of the XML Namespace property along with the variable name (the prefix and local name) to create a qualified name (QName) for the variable.

Integration Server also uses namespace prefixes assigned to variables in an IS document type when converting an XML document or XML node to a document (IData object). Integration Server obtains the namespace prefix to be used in the resulting document (IData) from the variable name in the document type rather than relying on the prefix present in the actual XML node. For example, suppose that Integration Server converts an XML node to a document (IData) using a document type to specify the structure to be imposed on the resulting document (IData). The document type contains a field named eg:account for which the XML Namespace property is set to www.example.com. The XML node contains an element named otherPrefix:account in which otherPrefix is defined to represent the namespace http://www.example.com. The resulting document (IData) contains a field named eg:account based on the document type field instead of otherPrefix:account as it appears in the original XML node.

Note: Integration Server automatically assigns an XML namespace to a variable when it creates a provider web service descriptor WSDL or a consumer web service descriptor from an existing WSDL. Integration Server also assigns an XML namespace from a schema when it creates a document type from an existing XML schema definition.

Guidelines for Using XML Namespaces and Prefixes with Web Service Descriptors

Use the following guidelines for assigning XML namespaces and prefixes to variables that will be used with web service descriptors:

  • If an IS service signature contains a variable name in the format prefix:localName, you must specify a URI as the value of the XML namespace property for that variable.
  • If an IS service is exposed as an RPC/Literal or RPC/Encoded web service operation, then the top-level field name in the service signature should not be in the format prefix:localName and should not be associated with an XML namespace.
  • If an IS service is exposed as a Document/Literal web service operation, then any field name in the service signature can be in the format prefix:localName, but it must also be associated with an XML namespace.

Assigning XML Namespaces and Prefixes to Variables

About this task

Use the XML Namespace property to assign a namespace name to a variable. If you intend to use the variable with a web service descriptor (for example, in the signature of a service used as an operation or in an IS document type used for a header or fault), review the information described in Guidelines for Using XML Namespaces and Prefixes with Web Service Descriptors before assigning XML namespaces and namespace prefixes to a variable.

Keep the following points in mind when assigning XML namespaces and prefixes to a variable:

  • The variable name must be in the format: prefix:variableName
  • You must specify a URI in the XML namespace property.
  • Do not use the same prefix for different namespaces in the same document type, input signature, or output signature.

To assign an XML namespace and prefix to a variable

Procedure

  1. In the editor, select the variable to which you want to assign an XML namespace.
  2. In the Properties view, click the XML namespace browse button () and then enter a value for the XML namespace.
  3. To assign a prefix to a variable, rename the variable to use the following format in which the namespace prefix precedes the variable name: prefix:variableName.
  4. Click OK.
  5. Click File > Save.

Assigning Display Types to String Variables

About this task

Assign a string display type to the string variable to define how you want to input data for the field.

To assign a string display type to a String variable

Procedure

  1. In the editor, select the String variable to which you want to assign properties.
  2. In the Properties view, under General, assign one of the following values to the String display type field:
    Select... If you want the input...
    Text Field (default) Entered in a text field
    Password Entered as a password, with asterisks reflected instead of characters
    Large Editor Entered in a large text area instead of a text field. This is useful if you expect a large amount of text as input for the field, or you need to have TAB or new line characters in the input
    Pick List To be limited to a predefined list of values

    Next to Pick list choices, click to define the values that will appear as choices when Designer prompts for input at run time.

    Note: These options are not available for Objects and Object lists.
  3. Click File > Save.

About Variable Constraints

In pipeline, document, and input/output validation, the blueprint used for data validation requires constraints to be applied to its variables. Constraints are the restrictions on the structure or content of variables. You can apply the following types of constraints to variables:

  • Structural constraints specify the existence and structure of variables at run time. For example, if the flow service in which you are validating the pipeline processes a purchase order, you might want to check that values for the purchaseOrderNumber, accountNumber, and customerName variables exist at run time.

    For document and document list variables, you can also specify the structure of the variable; that is, you can specify what variables can be contained in the document (IData object) or document list (IData[ ] object) at run time. For example, you could specify that the lineItem document variable must contain the child variables itemNumber, quantity, size, color, and unitPrice. You could also specify that the lineItem document can optionally contain the child variable specialInstructions.

  • Content constraints describe the data type for a variable and the possible values for the variable at run time. You can apply content constraints to String, String list, String table, Object, and Object list variables.

    When you specify a content constraint for a String, String list or String table variable, you can also apply a constraining facet to the content. A constraining facet places limitations on the content (data type). For example, for a String variable named itemQuantity, you might apply a content constraint that requires the value to be an integer. You could then apply constraining facets that limit the content of itemQuantity to a value between 1 and 100.

    You can use simple types from an IS schema as content constraints for String, String list, or String table variables.

For pipeline and document validation, the IS document type used as the blueprint needs to have constraints applied to its variables. For input/output validation, constraints need to be applied to the declared input and output parameters of the service being validated. For more information about data validation, see Performing Data Validation.

Note: When you create an IS document type from an XML Schema or a DTD, the constraints applied to the elements and attributes in the original document are preserved in the new IS document type. For more information about creating IS document types, see Creating an IS Document Type.

Considerations for Object Constraints

Constraints for Object and Object list variables correspond to Java classes, whereas constraints for String variables correspond to simple types in XML schemas. When you apply constraints to Objects and perform validation, the data is validated as being of the specified Java class. For details on the Java classes you can apply to an Object or Object list, see Java Classes for Objects.

A constrained Object is validated when one of the following occur:

  • A service runs with the Validate input or Validate output check box selected on the Input/Output tab.
  • A service runs via the INVOKE step in a flow service with the Validate input or Validate output properties set on the INVOKE step.
  • The pub.schema:validate service runs.
  • A document is published. When this occurs, the contents of the document are validated against the specified document type.
  • During debugging, when you enter values for a constrained Object or Object list in the Input dialog box.
  • When you assign a value to an Object or Object list variable in the Pipeline view using on the toolbar.

Applying Constraints to a Variable

About this task

Keep the following points in mind when applying constraints to a variable:
  • The Required property appears for variables in document types if one or more of the following are true:
    • The document type was created using a version of Integration Server prior to version 8.2.
    • The document type was created using Developer.
    • The Model type property of the document type is Unordered.
  • The Min occurs, Max occurs, and Model type variable properties are display-only. These properties appear only for a variable in an IS document type with a Model type property value of Sequence, Choice, or All.
  • Variables defined in an IS document type with a Model type property value other than “Unordered” cannot be modified.

To apply constraints to a variable

Procedure

  1. Select the variable to which you want to apply constraints.

    You can apply constraints to variables in IS document types, variables in a specification, and variables declared on the Input/Output tab.

  2. In the Properties view, under Constraints, define the following properties:
    Property Description
    Required Specifies whether the selected variable is required to exist at run time.
      Select... To...
      True Require the selected variable to exist at run time.
      False Make the existence of the variable optional at run time.
    Allow null Specifies whether a variable is allowed to have a null value.
      Select... To...
      True Allow the variable to have a null value.
      False Have the validation engine generate an error when the variable has a null value.
    Allow unspecified fields If the variable is a document or document list, specifies whether the variable can contain undeclared child variables.
      Select... To...
      True Allow the variable to contain undeclared child variables.
      False Treat any child variables that exist in the pipeline but do not appear in the declared document field as errors at run time.
     
    Note: The state of the Allow unspecified fields property determines whether the document is open or closed. An open document permits undeclared fields (variables) to exist at run time. A closed document does not allow undeclared fields to exist at run time. Integration Server considers a document to be open if the Allow unspecified fields property is set to True and considers a document to be closed if the Allow unspecified fields property is set to False.
  3. If the selected variable is a String, String list, or String table, and you want to specify content constraints for the variable, click and then do one of the following:
    • If you want to use a content type that corresponds to a built-in simple type in XML Schema, in the Content type list, select the type for the variable contents. To apply the selected type to the variable, click OK.

      If you want to customize the content type by changing the constraining facets applied to the type, see Customizing a String Content Type.

    • If you want to use a simple type from an IS schema as the content constraint, click Browse. In the Browse dialog box, select the IS schema containing the simple type you want to apply. Then, select the simple type you want to apply to the variable. To apply the selected type to the variable, click OK.
      Note: A content type corresponds to a simple type from an XML Schema definition. All of the choices in the Content type list correspond to simple types defined in XML Schema Part 2: Datatypes.
  4. If the selected variable is an Object or Object list, for the Java wrapper type property, select the Java class for the variable contents. If you do not want to apply a Java class or if the Java class is not listed, select UNKNOWN.

    For more information about supported Java classes for Objects and Object lists, see Java Classes for Objects.

  5. Repeat this procedure for each variable to which you want to apply constraints in the IS document type, specification, service input, or service output.
  6. Click File > Save.

Customizing a String Content Type

About this task

Instead of applying an existing content type or simple type to a String, String list, or String table variable, you can customize an existing type and apply the new, modified type to a variable. You customize a content type or simple type by changing the constraining facets applied to the type.

When you customize a type, you actually create a new content type. Designer saves the changes as a new content type named contentType_customized. For example, if you customize the string content type, Designer saves the new content type as string_customized.

When customizing a content type, keep the following points in mind:

  • When you edit the constraining facets, you can only make the constraining facet values more restrictive. The constraining facets cannot become less restrictive.
  • The constraining facets you can specify depend on the content type. Note that content types and constraining facets correspond to datatypes and constraining facets defined in XML Schema. For more information about constraining facets for a datatype, see the specification XML Schema Part 2: Datatypes (http://www.w3.org/TR/xmlschema-2/).
  • The customized content type applies only to the selected variable. To make changes that affect all variables to which the content type is applied, edit the content type in the IS schema. (String content types are simple types from IS schemas.) For more information about editing simple type definitions, see About Editing Simple Type Definitions.

To customize a content type

Procedure

  1. Select the variable to which you want to apply a customized content type.
  2. In the Constraints category on the Properties view, click the Content type browse button () and then do one of the following to select the content type you want to customize:
    • In the Content type list, select the content type you want to customize.
    • If you want to customize a simple type from an IS schema, click Browse. In the Browse dialog box, select the IS schema containing the simple type. Then, select the simple type you want to customize and apply to the variable. Click OK.
  3. Click Customize. Designer makes the constraining facet fields below the Content type list available for data entry (that is, changes the background of the constraining facet fields from grey to white). Designer changes the name of the content type to contentType_customized.
  4. In the fields below the Content type list, specify the constraining facet values you want to apply to the content type.
  5. Click OK. Designer saves the changes as a new content type named contentType_customized.
    Note: The constraining facets displayed below the Content type list depend on the primitive type from which the simple type is derived. Primitive types are the basic data types from which all other data types are derived. For example, if the primitive type is string, Designer displays the constraining facets enumeration, length, minLength, maxLength, and pattern. For more information about primitive types, refer to XML Schema Part 2: Datatypes at http://www.w3.org/TR/xmlschema-2/.

Viewing the Constraints Applied to Variables

Designer displays small symbols next to a variable icon to indicate the constraints applied to the variable. Designer displays variables in the following ways:

Variable Constraint status Variable Properties
Required field. The Required property is set to True.
Optional field. The Required property is set to False.
Required field with content type constraint. The Content type property specifies an IS schema or XML schema.
Optional field with content type constraint The Required property is set to False and the Content type property specifies an IS schema or XML schema.
Required field with default value. The Required property is set to True. The variable has a default value, but you can override this default value with any other valid values while executing the service or mapping the variables.
Required field with fixed default value of null. The Required property is set to True. You cannot override the default null value assigned to the variable by mapping it to another variable or by assigning any input values to this variable during service execution.
Note: By default, Designer hides the variables with this constraint. To display these variables in the content and structure of service signatures, document and pipeline contents, and in the Run Configurations, Enter Input for serviceName, and Enter Input for variableName dialog boxes, select the Show variables with fixed values property on the Service Development Preferences page.
Required field with fixed default value. The Required property is set to True. You cannot override the default value assigned to the variable by mapping it to another variable or by assigning any input values to this variable during service execution.
Note: By default, Designer hides the variables with this constraint. To display these variables in the content and structure of service signatures, document and pipeline contents, and in the Run Configurations, Enter Input for serviceName, and Enter Input for variableName dialog boxes, select the Show variables with fixed values property on the Service Development Preferences page.
Note: Designer displays the ‡ symbol next to String, String List, and String table variables with a content type constraint only. Designer does not display the ‡ symbol next to Object and Object list variables with a specified Java class constraint. Object and Object lists with an applied Java class constraint have a unique icon. For more information about icons for constrained Objects, see Java Classes for Objects.