Reporting Server > Using the Adapter for Web Services > Managing Web Services Metadata

Managing Web Services Metadata

Topics:

When the server accesses a Web Services provider, it needs to know how to pass parameters to and accept responses from the Web service operation. For each operation the server will access, you create a synonym that describes the operation and the server mapping, which is provided through the WSDL file for the Web Service.

Creating Synonyms

How to:

Reference:

x

A synonym defines a unique logical name (also known as an alias) for each Web Services operation. Synonyms are useful because:

  • They insulate client applications from changes to the location and identity of a request. You can move or rename a request without modifying the client applications that use it. You need make only one change, redefining the request synonym on the server.
  • They provide support for the extended metadata features of the server, such as virtual fields and security mechanisms.

Creating a synonym generates a Master File and an Access File. These are metadata that describe the Web Services request to the server.

Each synonym you create represents a single operation.

Note: Each synonym describes the Web Services operations of a particular provider. If the operation parameters are changed, the synonym must be recreated.

Procedure: How to Create a Synonym

  1. From the Web Console sidebar, click Applications or Connect to Data.

    The Applications page opens.

  2. If you started from the Applications page, right-click an application folder, point to New, and click Synonym on the context menu.

    The Connect to Data page opens.

  3. On the Configured list, click the down arrow next to a connection for the configured adapter, or right-click a connection.

    Depending on the type of adapter you chose, one of the following options appears on the context menu.

    • Show DBMS objects. This opens the page for selecting synonym objects and properties.
    • Create metadata objects. This opens the page for selecting synonym objects and properties.
    • Show files. This opens a file picker. After you choose a file of the correct type, the page for selecting synonym objects and properties opens.
    • Show local files. This opens a file picker. After you choose a file of the correct type, the page for selecting synonym objects and properties opens.
    • Show topics. This opens the page for selecting synonym objects and properties for topics within the Kafka environment.
  4. Enter values for the parameters required by the adapter as described in the chapter for your adapter.
  5. After entering the parameter values, click the highlighted button on the ribbon.

    The button may be labeled Next, Create Synonym, Create Base Synonyms, Create Cluster Synonym, or Update Base Synonyms.

    The synonym creation process for most adapters has been consolidated so that you can enter all necessary parameters on one page. However, for some adapters such as LDAP, you must click Next buttons until you get to a page that has a Create Synonym button.

The synonym is created and added under the specified application directory.

Note: When creating a synonym, if you choose the Validate check box (where available), the server adjusts special characters and checks for reserved words. For more information, see Validation for Special Characters and Reserved Words.

Reference: Synonym Creation Parameters for Web Services

The following list describes the parameters for which you will need to supply values, and related tasks you will need to complete in order to create a synonym for the adapter. These options may appear on multiple panes. To advance from pane to pane, click the buttons provided, ending with the Create Synonym button, which generates the synonym based on your entries.

Filter Operations by Name

Leave this check box blank if you do not wish to filter the operations for which to create synonyms.

Select the check box to filter the operations. You are prompted an operation name. Enter a string for filtering the operations, inserting the wildcard character (%) as needed at the beginning and/or end of the string.

For example, enter: ABC% to select all operations whose names begin with the letters ABC; %ABC to select operations whose names end with the letters ABC; %ABC% to select operations whose names contain the letters ABC at the beginning, middle, or end.

Select Operations button

Click this button to select all or filtered operations.

Validate

Select the Validate check box if you wish to convert all special characters to underscores and perform a name check to prevent the use of reserved names. (This is accomplished by adding numbers to the names.) This parameter ensures that names adhere to specifications. See Validation for Special Characters and Reserved Words for more information.

When the Validate option is unchecked, only the following characters are converted to underscores: '-'; ' '; ' \'; '/'; ','; '$'. No checking is performed for names.

Make unique

Select the Make unique check box if you wish to set the scope for field and group names to the entire synonym. This ensures that no duplicate names are used, even in different segments of the synonym. When this option is unchecked, the scope is the segment.

Strict SOAP data type

By default, a SOAP request generated from a table request omits all elements tags for which screening values are not provided. If this is the behavior you want, leave the Strict SOAP data type box unchecked.

If you wish to pass empty element tags as well as those that contain values, click the Strict SOAP data type check box.

This option applies to both the body and header in a SOAP request.

Application

Select an application directory. The default value is baseapp.

Prefix/Suffix

If you have tables with identical table names, assign a prefix or a suffix to distinguish them. For example, if you have identically named human resources and payroll tables, assign the prefix HR to distinguish the synonyms for the human resources tables. Note that the resulting synonym name cannot exceed 64 characters.

If all tables and views have unique names, leave the prefix and suffix fields blank.

Overwrite Existing Synonyms

To specify that this synonym should overwrite any earlier synonym with the same fully qualified name, select the Overwrite existing synonyms check box.

Note: The connected user must have operating system write privileges in order to recreate a synonym.

Default Synonym Name

This column displays the name that will be assigned to each synonym. To assign a different name, replace the displayed value.

To create synonyms

For all operations in the list, select the check box to the left of the Default Synonym Name column.

For specific operations, select the corresponding check boxes.

Reference: Managing Synonyms

Once you have created a synonym, you can right-click the synonym name in the Adapter navigation pane of either the Web Console or the Data Management Console to access the available options.

For a list of options, see Synonym Management Options.

Reference: Master File Attributes

Attribute

Description 

PROPERTY

Indicates whether the field corresponds to an XML attribute or an XML element. 

REFERENCE

Identifies the parent element of the field in the XML hierarchy, as defined by the Web Services XML schema document.

The format is

segmentname.fieldname

where:

segmentname

Is the name of the Master File segment in which the field resides.

fieldname

Is the name of the field that corresponds to the parent element.

Reference: Access File Attributes

Attribute

Description 

SEGNAME

Value must be identical to the SEGNAME value in the Master File. 

CONNECTION

Indicates a previously declared connection. The syntax is: 

CONNECTION=connection                      
VERSION

Web Services version being used. The adapter supports Version 1.1. 

ACTION

Web service operation being described. 

OBJECT

Fully-qualified name of the Web Services request. 

ENCODING

URL of the encoding schema. 

TARGETNS

Target name space specified in the WSDL description of the operation. (This will either be global to the Web Service WSDL, or unique to the operation WSDL.) 

STYLE

Value of the Web Services document WSDL style element (RPC or Document). 

HEADER

Header group in the Master File, if one exists. 

HEADERNS

Header namespace.

 
EMPTYTAGS

If ON, passes empty element tags, as well as those for which values have been provided. If OFF, the default, and element tags with values are passed.

Applies to both the body and header in a SOAP request.

Using Static Joins

Reference:

You can describe various views of the same physical XML document using Master Files and Access Files.

  • In the Master File, you use REFERENCE attributes in field definitions to reflect physical relationships between tags in XML document hierarchies and PARENT attributes, which establish logical hierarchical relationships.
  • In the Access File, you use the KEYFLD and IXFLD attributes to identify the XML tags that act as primary/foreign keys in the XML document hierarchies, which establish the logical join relationships. The parent field (foreign key) defined in KEYFLD supplies the value for cross-referencing; the descendant field (primary key) defined in IXFLD contains the corresponding value.

The adapter implements join matching values at run time.

You can use static Joins to create join relationships between hierarchically unrelated integral schema ComplexType definitions using any combination of data nodes.

Any XML tags belonging to these definitions can be used to create join pairs. In addition, you can multiply instances of the same physical segment to reflect logical join relationships as needed.

Using a Join can also provide a way to produce multiple executions of a Web service. However, the user cannot change the properties of the fields that describe the Web service input message. The original WSDL controls the acceptable data types for both the input and output. The Join must be to fields belonging to the root segment, and the ACCESS_PROPERTY parameter must be set to NEED_VALUE. The Join must also be unique to avoid looping.

Note: Static (embedded) Joins are not directly supported by the Create Synonym facility. To take advantage of this feature, after a synonym is generated you must modify its Master and Access Files. The Data Management Console Synonym Editor is the recommended tool for such modifications since it provides an easily identifiable segments hierarchy with drag and drop capability and a visual calculator for KEYFLD/IXFLD modifications. Using the DMC, you can quickly add all duplicate segments to the Master File, then delete any unneeded segments.

In some cases, schemas (such as those produced by Microsoft tools and reflecting relationships between the original MS SQL Server database tables) contain proper XML constraints (unique/key/keyref) for describing joins. You can use this information to modify the Master File:

  • The elements unique and key define the primary key for the element (segment).
  • The element keyref defines the foreign key for the element (segment).

For an example of how to use the Data Management Console to modify the Master File, see Adding a Static Join From the Data Management Console Synonym Editor.

Example: Adding a Static Join From the Data Management Console Synonym Editor

This example displays a fragment of the WSDL code from which a synonym called GetAllEmployees will be generated.

The schema shows a Constraint relationship between the Employee segment, keyed on the EID field, and the Employee Relative segment, keyed on ERID field. 

<xs:unique msdata:PrimaryKey="true" name="Constraint1">
<xs:selector xpath=".//Employee" /> 
<xs:field xpath="EId" /> 
</xs:unique>
 
<xs:unique msdata:ConstraintName="Constraint1" msdata:PrimaryKey="true"
     name="EmployeeRelative_Constraint1">
  <xs:selector xpath=".//EmployeeRelative" />
  <xs:field xpath="ErId" />
  </xs:unique>
<xs:keyref msdata:ConstraintOnly="true"
     name="EmployeeRelative_Employee_EId_EId"
refer="mstns:Constraint1">
<xs:selector xpath=".//EmployeeRelative" /> 
<xs:field xpath="EId" />
</xs:keyref>

Working in the Data Management Console, you can quickly establish a Join relationship between the Employee and EmployeeRelative Segments in the synonym in order to be able to report against both segments at the same time.

  1. Open the DMC and open the Application Directory folder where the synonym is located.
  2. Double-click the synonym GetAllEmployees - Web Services in the navigation pane, then click the Modeling View tab. The segment relationships are initially represented as follows:

    Notice that both Employee and EmployeeRelative are children of the Response segment in the generated synonym.

    Your goal is to report against both segments at the same time, which is not something you can do using this structure. To accomplish that task, you must first make the EmployeeRelative segment a child of the Employee segment, an easy adjustment using the DMC Segment View.

  3. Click the Segment View tab. You will see the following pane, in which Employee and Employee Relative are both children of segment Response, as shown in Modeling View:
  4. Drag the EmployeeRelative segment and drop it onto the Employee segment. EmployeeRelative is now a child of Employee, as shown in the revised Tree pane.
  5. Next, you must set up the relationship that shows how the two segments are joined. Remember that in the schema the Employee segment and the EmployeeRelative segment are joined where EID = ERID.

    To mirror this relationship, click the Ellipsis (...) for Keyfld in the EmployeeRelative segment on the right pane. The Join Properties dialog box opens. This is where you will define the nature of the join relationship between the two segments.

  6. In the Venn Diagram box at the bottom left, click the outer portion of the left circle to specify a Left Outer Join. This option retrieves all records from the left-hand data source, along with any matching records from the right-hand data source. In this example, that means you will be able to display Employee values in the report even when the employees do not have any relatives.

    Tip: For definitions of other Join configurations that are available through the DMC, see Join Options.

  7. At the top of the dialog box, the Left Source Column displays fields from the Employee segment and the Right Source Column displays fields from the EmployeeRelative segment.

    Select EID from the left side and ERID from the right side, then click the = sign between them.

  8. Click OK to complete the Join and close the Join Properties dialog box.
  9. Click the Modeling View tab to verify the modified structure in which EmployeeRelative is a child of Employee, providing the relationship you need to meet your reporting requirements.

Reference: Join Options

This chart defines the Join options that are available in the Venn Diagram box in the Data Management Console.

Inner Join indicates that two data sources are connected by an inner join and that only rows that appear in both tables used in the Join are extracted.

Left Outer Join indicates that two data sources are connected by a left outer join and that all rows are extracted from the left data source, as well as the columns from the right source that match.

Right Outer Join indicates that two data sources are connected by a right outer join and that all rows are extracted from the right data source, as well as the columns from the left source that match.

Full Outer Join indicates that two data sources are connected by a full outer join and that all rows are extracted from both data sources.

Cross Join indicates that two data sources are connected by a cross join, or Cartesian product of two tables. It consists of all possible pairs of rows between the two tables.

What Is a WSDL File?

Reference:

A Web Services Description Language (WSDL) file is an XML document that describes a Web Service. A WSDL file contains the following key elements:

WSDL Element

Definition

definitions

Root element of all WSDL documents. It defines the name of the web service, declares multiple namespaces used throughout the remainder of the document, and contains all the service elements described here.

types

Describes all the data types used between the client and server. WSDL is not tied exclusively to a specific typing system, but it uses the W3C XML Schema specification as its default choice. If the service uses only XML Schema built-in simple types, such as strings and integers, the types element is not required.

message

Describes a one-way message, whether it is a single message request or a single message response. It defines the name of the message and contains zero or more message part elements, which can refer to message parameters or message return values.

portType

Combines multiple message elements to form a complete one-way or round-trip operation. For example, a portType can combine one request and one response message into a single request/response operation, most commonly used in SOAP services. Note that a portType can (and frequently does) define multiple operations.

binding

Describes the concrete specifics of how the service will be implemented on the wire. WSDL includes built-in extensions for defining SOAP services, and SOAP-specific information therefore goes here.

service

Defines the address for invoking the specified service. Most commonly, this includes a URL for invoking the SOAP service.

Example: WSDL Segment for Generating a Master File for FindAddress Web Service

The following shows the elements for the input and output for the FindAddress Web Service function: 

<!-- edited with XMLSPY v5 rel. 3 U (http://www.xmlspy.com)-->
<wsdl:definitions
   xmlns:tns="http://arcweb.esri.com/v2"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
   xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
   xmlns="http://schemas.xmlsoap.org/wsdl/"
   xmlns:tme="http://www.themindelectric.com/"
xmlns:ns11="http://www.themindelectric.com/package/
com.esri.is.services.common.v2.geom/"
xmlns:ns12="http://www.themindelectric.com/package/com.esri.is.services.common.v2/"
xmlns:ns13="http://www.themindelectric.com/package/
com.esri.is.services.glue.v2.addressfinder/"
   xmlns:ns14="http://www.themindelectric.com/package/java.lang/"
   targetNamespace="http://arcweb.esri.com/v2" name="AddressFinder">
 <wsdl:types>
     <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.themindelectric.com/package/
com.esri.is.services.glue.v2.addressfinder/">
   <xsd:complexType name="Address">
    <xsd:sequence>
     <xsd:element name="houseNumber" nillable="true" type="xsd:string"/>
     <xsd:element name="street" nillable="true" type="xsd:string"/>
     <xsd:element name="intersection" nillable="true" type="xsd:string"/>
     <xsd:element name="city" nillable="true" type="xsd:string"/>
     <xsd:element name="state_prov" nillable="true" type="xsd:string"/>
     <xsd:element name="zone" nillable="true" type="xsd:string"/>
     <xsd:element name="country" nillable="true" type="xsd:string"/>
    </xsd:sequence>
   </xsd:complexType>
   <xsd:complexType name="AddressFinderOptions">
    <xsd:sequence>
     <xsd:element name="dataSource" nillable="true" type="xsd:string"/>
    </xsd:sequence>
   </xsd:complexType>
  </xsd:schema>
  <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.themindelectric.com/package/ 
com.esri.is.services.common.v2.geom/">
  <xsd:complexType name="Point">
   <xsd:sequence>
     <xsd:element name="x" type="xsd:double"/>
     <xsd:element name="y" type="xsd:double"/>
   <xsd:element name="coordinateSystem" nillable="true"        
type="ns11:CoordinateSystem"/>
   </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="CoordinateSystem">
   <xsd:sequence>
     <xsd:element name="projection" nillable="true" type="xsd:string"/>
     <xsd:element name="datumTransformation" nillable="true" type="xsd:string"/>
   </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="Envelope">
   <xsd:sequence>
     <xsd:element name="minx" type="xsd:double"/>
     <xsd:element name="miny" type="xsd:double"/>
     <xsd:element name="maxx" type="xsd:double"/>
     <xsd:element name="maxy" type="xsd:double"/>
     <xsd:element name="coordinateSystem" nillable="true"          
type="ns11:CoordinateSystem"/>
   </xsd:sequence>
  </xsd:complexType>
 </xsd:schema>
 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.themindelectric.com/package/       
com.esri.is.services.common.v2/">
  <xsd:import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
  <xsd:import namespace="http://www.themindelectric.com/package/       
com.esri.is.services.common.v2.geom/"/>
  <xsd:complexType name="LocationInfo">
   <xsd:sequence>
    <xsd:element name="matchType" nillable="true" type="xsd:string"/>
    <xsd:element name="candidates" nillable="true" type="ns12:ArrayOfLocation"/>
    <xsd:element name="hasMore" type="xsd:boolean"/>
    <xsd:element name="errorCode" nillable="true" type="xsd:string"/>
   </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="Location">
    <xsd:sequence>
     <xsd:element name="point" nillable="true" type="ns11:Point"/>
     <xsd:element name="description1" nillable="true" type="xsd:string"/>
     <xsd:element name="description2" nillable="true" type="xsd:string"/>
     <xsd:element name="score" type="xsd:double"/>
     <xsd:element name="matchType" nillable="true" type="xsd:string"/>
     <xsd:element name="type" nillable="true" type="xsd:string"/>
     <xsd:element name="locationExtent" nillable="true" type="ns11:Envelope"/>
    </xsd:sequence>
  </xsd:complexType>
   <xsd:complexType name="ArrayOfLocation">
    <xsd:complexContent>
     <xsd:restriction base="soapenc:Array">
       <xsd:attribute ref="soapenc:arrayType" wsdl:arrayType="ns12:Location[]"/>
     </xsd:restriction>
    </xsd:complexContent>
   </xsd:complexType>
  </xsd:schema>
  <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.themindelectric.com/package/java.lang/">
     <xsd:import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
     <xsd:complexType name="ArrayOfstring">
      <xsd:complexContent>
       <xsd:restriction base="soapenc:Array">
         <xsd:attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:string[]"/>
       </xsd:restriction>
      </xsd:complexContent>
     </xsd:complexType>
  </xsd:schema>
 </wsdl:types>
   <message name="getAddress0In">
     <part name="point" type="ns11:Point"/>
     <part name="addressFinderOptions" type="ns13:AddressFinderOptions"/>
     <part name="token" type="xsd:string"/>
   </message>
   <message name="getAddress0Out">
     <part name="Result" type="ns13:Address"/>
   </message>
  <portType name="IAddressFinder">
     <operation name="getAddress" parameterOrder="point addressFinderOptions token">
       <documentation>Returns an address from an x,y-coordinate.</documentation>
        <input name="getAddress0In" message="tns:getAddress0In"/>
        <output name="getAddress0Out" message="tns:getAddress0Out"/>
     </operation>
  </portType>
  <binding name="IAddressFinder" type="tns:IAddressFinder">
    <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
  <operation name="getAddress">
    <soap:operation soapAction="getAddress" style="rpc"/>
     <input>
      <soap:body use="encoded" encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/" 
     namespace="http://arcweb.esri.com/v2"/>
     </input>
     <output>
      <soap:body use="encoded" encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/" 
  namespace="http://arcweb.esri.com/v2"/>
     </output>
  </operation>
  </binding>
  <service name="AddressFinder">
    <port name="IAddressFinder" binding="tns:IAddressFinder">
      <soap:address location="http://arcweb.esri.com/services/v2/AddressFinder"/>
    </port>
  </service>
</wsdl:definitions>

The following Master File is generated from the Create Synonym process: 

FILENAME=M6ILO, SUFFIX=SOAP    , $
  SEGMENT=GETADDRESS, SEGTYPE=S0, $
   GROUP=POINT, ALIAS=point, USAGE=A76, ACTUAL=A100, $
    FIELDNAME=X, ALIAS=x, USAGE=D20.2, ACTUAL=A20, ACCESS_PROPERTY=(NEED_VALUE), $
    FIELDNAME=Y, ALIAS=y, USAGE=D20.2, ACTUAL=A20, ACCESS_PROPERTY=(NEED_VALUE), $
   GROUP=COORDINATESYSTEM, ALIAS=coordinateSystem, USAGE=A60, ACTUAL=A60, $
    FIELDNAME=PROJECTION, ALIAS=projection, USAGE=A30, ACTUAL=A30,
      MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), $
    FIELDNAME=DATUMTRANSFORMATION, ALIAS=datumTransformation, USAGE=A30, ACTUAL=A30,
      MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), $
   GROUP=ADDRESSFINDEROPTIONS, ALIAS=addressFinderOptions, USAGE=A30, ACTUAL=A30, $
    FIELDNAME=DATASOURCE, ALIAS=dataSource, USAGE=A30, ACTUAL=A30,
      MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), $
    FIELDNAME=TOKEN, ALIAS=token, USAGE=A30, ACTUAL=A30, 
      ACCESS_PROPERTY=(NEED_VALUE), $
    FIELDNAME=__RESPONSE, USAGE=TX80L, ACTUAL=TX, ACCESS_PROPERTY=(INTERNAL), $
  SEGMENT=RESPONSE, SEGTYPE=S0,SEGSUF=XML     , PARENT=GETADDRESS, 
POSITION=__RESPONSE, $
    FIELDNAME=RESPONSE, ALIAS=getAddress0Out, USAGE=A1, ACTUAL=A1, 
ACCESS_PROPERTY=(INTERNAL), $
  SEGMENT=RESULT, SEGTYPE=S0, PARENT=RESPONSE, $
    FIELDNAME=RESULT, ALIAS=Result, USAGE=A1, ACTUAL=A1, 
ACCESS_PROPERTY=(INTERNAL),
      REFERENCE=RESPONSE, PROPERTY=ELEMENT,  $
    FIELDNAME=HOUSENUMBER, ALIAS=houseNumber, USAGE=A30, ACTUAL=A30,
      MISSING=ON,
      REFERENCE=RESULT, PROPERTY=ELEMENT,  $
    FIELDNAME=STREET, ALIAS=street, USAGE=A30, ACTUAL=A30,
      MISSING=ON,
      REFERENCE=RESULT, PROPERTY=ELEMENT,  $
    FIELDNAME=INTERSECTION, ALIAS=intersection, USAGE=A30, ACTUAL=A30,
      MISSING=ON,
      REFERENCE=RESULT, PROPERTY=ELEMENT,  $
    FIELDNAME=CITY, ALIAS=city, USAGE=A30, ACTUAL=A30,
      MISSING=ON,
      REFERENCE=RESULT, PROPERTY=ELEMENT,  $
    FIELDNAME=STATE_PROV, ALIAS=state_prov, USAGE=A30, ACTUAL=A30,
      MISSING=ON,
      REFERENCE=RESULT, PROPERTY=ELEMENT,  $
    FIELDNAME=ZONE, ALIAS=zone, USAGE=A30, ACTUAL=A30,
      MISSING=ON,
      REFERENCE=RESULT, PROPERTY=ELEMENT,  $
    FIELDNAME=COUNTRY, ALIAS=country, USAGE=A30, ACTUAL=A30,
      MISSING=ON,
      REFERENCE=RESULT, PROPERTY=ELEMENT,  $

The following Access File is generated from the Create Synonym process: 

SEGNAME=GETADDRESS, CONNECTION=CON06, VERSION=1.1, OBJECT=getAddress,
  ACTION=getAddress, ENCODING=http://schemas.xmlsoap.org/soap/encoding/,
  TARGETNS=http://arcweb.esri.com/v2, STYLE=RPC, $
 ID=ns11, NS=http://www.themindelectric.com/package/
    com.esri.is.services.common.v2.geom/   , $
  FIELD=point, TYPE=Point, NS_ID=ns11, $
  FIELD=coordinateSystem, TYPE=CoordinateSystem, NS_ID=ns11, $
 ID=ns13, NS=http://www.themindelectric.com/package/
    com.esri.is.services.glue.v2.addressfinder/   , $
  FIELD=addressFinderOptions, TYPE=AddressFinderOptions, NS_ID=ns13, $

You can use the following procedure to retrieve data from the FindAddress Master File: 

SET ALL=ON
TABLE FILE FINDADDRESS
PRINT LOCATION.X LOCATION.Y
WHERE FINDADDRESS.HOUSENUMBER EQ '27'
WHERE FINDADDRESS.STREET EQ 'Stevenson Drive'
WHERE FINDADDRESS.ZONE EQ '07746'
WHERE FINDADDRESS.DATASOURCE EQ 'GDT.Streets.US'
END

Example: WSDL Document With SOAP Header

The Create Synonym process generates an extra group in the root segment to describe the SOAP HEADER layout, as defined in the WSDL document.

The following WSDL describes a SOAP header:

Binding section: 

<input>
  <soap:body use="literal"/>
  <soap:header part="header" message="tns:jobsHeader" use="literal"/>
</input>

Message description: 

<message name="jobsHeader">
  <part element="tns:ibsinfo" name="header"/>
</message>

Types section: 

<xs:element name="ibsinfo">
  <xs:complexType>
      <xs:sequence>
          <xs:element type="xs:string" name="service"/>
          <xs:element type="xs:string" name="method"/>
          <xs:element type="xs:string" name="license"/>
          <xs:element type="xs:string" minOccurs="0" name="disposition"/>
          <xs:element type="xs:string" minOccurs="0" name="Username"/>
          <xs:element type="xs:string" minOccurs="0" name="Password"/>
          <xs:element type="xs:string" minOccurs="0" name="language"/>
      </xs:sequence>
  </xs:complexType>
</xs:element>

The resulting Master File contains: 

SEGMENT=LOCATION, SEGTYPE=S0, $
  GROUP=HEADER, ALIAS=Header, USAGE=A210, ACTUAL=A210, $
  GROUP=IBSINFO, ALIAS=ibsinfo, USAGE=A210, ACTUAL=A210, $
   FIELDNAME=SERVICE, ALIAS=service, USAGE=A30, ACTUAL=A30,
      ACCESS_PROPERTY=(NEED_VALUE), $
   FIELDNAME=METHOD, ALIAS=method, USAGE=A30, ACTUAL=A30,
      ACCESS_PROPERTY=(NEED_VALUE), $
   FIELDNAME=LICENSE, ALIAS=license, USAGE=A30, ACTUAL=A30,
      ACCESS_PROPERTY=(NEED_VALUE), $
   FIELDNAME=DISPOSITION, ALIAS=disposition, USAGE=A30, ACTUAL=A30,
     ACCESS_PROPERTY=(NEED_VALUE), $
   FIELDNAME=USERNAME, ALIAS=Username, USAGE=A30, ACTUAL=A30,
     ACCESS_PROPERTY=(NEED_VALUE), $
   FIELDNAME=PASSWORD, ALIAS=Password, USAGE=A30, ACTUAL=A30,
     ACCESS_PROPERTY=(NEED_VALUE), $
   FIELDNAME=LANGUAGE, ALIAS=language, USAGE=A30, ACTUAL=A30,
     ACCESS_PROPERTY=(NEED_VALUE), $

The resulting Access File contains: 

SEGNAME=LOCATION, CONNECTION=PSIBS, VERSION=1.1, OBJECT=LOCATION,
  ACTION=EFREM.LOCATIONRequest@test@@, HEADER=HEADER,
  TARGETNS=urn:iwaysoftware:ibse:jul2003:LOCATION,
  HEADERNS=urn:schemas-iwaysoftware-com:iwse, STYLE=DOCUMENT, $

Note that the SOAP header is generated in the SOAP request if a value is provided (either explicitly in the request or implicitly via default values in the Master File) for at least one of the header components. If no header values are available, the SOAP header is not generated.

Example: WSDL Document With Output Headers

The Create Synonym process generates extra output segment(s) to describe the header data returned by a SOAP request. Segments describing the header and body parts of the SOAP response become children of the response segment and siblings to each other.

WSDL fragment 

<operation name="TrackMessagesBulk">
< soap:operation soapAction="http://www.strikeiron.com/TrackMessagesBulk"
       style="document" />
  <input>
    <soap:body use="literal" />
  </input>
 <output>
   <soap:body use="literal" />
    <soap:header message="s0:TrackMessagesBulkResponseInfo"
          part="ResponseInfo" use="literal" />
  </output>
</operation>

Generated Master File 

SEGMENT=RESPONSE, SEGTYPE=S0, SEGSUF=XML , PARENT=TRACKMESSAGESBULK
      POSITION=__RESPONSE, $
  FIELDNAME=RESPONSE, ALIAS=Envelope, USAGE=A1, ACTUAL=A1,
      ACCESS_PROPERTY=(INTERNAL), $
  FIELDNAME=HEADER, ALIAS=Header, USAGE=A1, ACTUAL=A1,
      ACCESS_PROPERTY=(INTERNAL), $
  FIELDNAME=BODY, ALIAS=Body, USAGE=A1, ACTUAL=A1,
      ACCESS_PROPERTY=(INTERNAL), $
SEGMENT=HEADER, SEGTYPE=S0, PARENT=RESPONSE, $
  FIELDNAME=RESPONSE, ALIAS=ResponseInfo, USAGE=A1, ACTUAL=A1,
      ACCESS_PROPERTY=(INTERNAL), REFERENCE=HEADER, $
  FIELDNAME=RESPONSECODE, ALIAS=ResponseCode, USAGE=I11, ACTUAL=A11,
      REFERENCE=HEADER.RESPONSE, PROPERTY=ELEMENT,  $
  FIELDNAME=RESPONSE1, ALIAS=Response, USAGE=A30, ACTUAL=A30,
      REFERENCE=HEADER.RESPONSE, PROPERTY=ELEMENT,  $
SEGMENT=BODY, SEGTYPE=S0, PARENT=RESPONSE, $
  FIELDNAME=RESPONSE, ALIAS=TrackMessagesBulkResponse, USAGE=A1,
      ACTUAL=A1, ACCESS_PROPERTY=(INTERNAL), REFERENCE=BODY, $
  FIELDNAME=TRACKMESSAGESBULKRESULT, ALIAS=TrackMessagesBulkResult,
      USAGE=A1, ACTUAL=A1, ACCESS_PROPERTY=(INTERNAL),
      REFERENCE=BODY.RESPONSE, PROPERTY=ELEMENT,  $

Reference: Multiple Headers

The Adapter for Web Services converts multiple header body definitions in the WSDL document into Master File components. Each input header body becomes a separate GROUP description for the input SOAP segment. For each output header body, a special field description is created in the response segment.

Example: WSDL Document With Mixed Content

Complex data types with the MIXED property are supported in the SOAP response document. 

<xsd:element name="letterBody">
    <xsd:complexType mixed="true">
        <xsd:sequence>
            <xsd:element name="salutation">
                <xsd:complexType mixed="true">
                    <xsd:sequence>
                        <xsd:element name="name" type="xsd:string"/>
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>
            <xsd:element name="quantity" type="xsd:positiveInteger"/>
            <xsd:element name="productName" type="xsd:string"/>
            <xsd:element name="shipDate" type="xsd:date" minOccurs="0"/>
        </xsd:sequence>
    </xsd:complexType>
</xsd:element>

The resulting Master File contains: 

SEGMENT=LETTERBODY, SEGTYPE=S0, $
 FIELDNAME=LETTERBODY, ALIAS=letterBody, USAGE=A50, ACTUAL=A50, $
 FIELDNAME=SALUTATION, ALIAS=salutation, USAGE=A50, ACTUAL=A50,
  REFERENCE=LETTERBODY, PROPERTY=ELEMENT, $
 FIELDNAME=NAME, ALIAS=name, USAGE=A50, ACTUAL=A50,
  REFERENCE=SALUTATION, PROPERTY=ELEMENT, $
 FIELDNAME=QUANTITY, ALIAS=quantity, USAGE=P32, ACTUAL=A32,
  REFERENCE=LETTERBODY, PROPERTY=ELEMENT, $
 FIELDNAME=PRODUCTNAME, ALIAS=productName, USAGE=A50, ACTUAL=A50,
  REFERENCE=LETTERBODY, PROPERTY=ELEMENT, $
 FIELDNAME=SHIPDATE, ALIAS=shipDate, USAGE=YYMD, ACTUAL=A10, MISSING=ON,
  REFERENCE=LETTERBODY, PROPERTY=ELEMENT, $

The Adapter for Web Services does not preserve the original sequence of text components and descendant elements. The following SOAP response document and report illustrate this limitation: 

<letterBody>
    <salutation>Dear Mr.
        <name>Robert Smith</name>.
    </salutation>
    Your order of 
    <quantity>1</quantity>
    <productName>BabyMonitor</productName> 
    shipped from our warehouse on
    <shipDate>1999-05-21</shipDate>.
</letterBody>
 
LETTERBODY       SALUTATION NAME           QUANTITY PRODUCTNAME SHIPDATE
----------       ---------- ----           -------- ----------- --------
 
Your order of shipped from our warehouse on .  Dear Mr. . Robert Smith
1        BabyMonitor 1999/05/21

Example: WSDL Document With Abstract Input Data Type

The adapter generates an input field with ACTUAL and USAGE formats of A1. The ACCESS property for this field is initially set to INTERNAL to prevent a front-end tool from requesting an input value. A user can modify the definition manually, if necessary.

Message description: 

<message name="ivpIn">
    <part element="m1:ivp" name="parameters"/>
</message>
Input message definition:
<xs:element name="ivp">
    <xs:complexType>
        <xs:sequence/>
    </xs:complexType>
</xs:element>

The resulting Master File contains: 

FIELDNAME=IVP, ALIAS=ivp, USAGE=A1, ACTUAL=A1, ACCESS_PROPERTY=(INTERNAL), $

Mapping Attributes and Default Values

Element attributes are supported as part of the service input message definition:

  • Restriction values are stored in the corresponding field definition of the Master File as an ACCEPT list.
  • The default value is stored in the XDEFAULT parameter.

Example: WSDL Document With Mapped Attributes and Default Values 

<xs:element name="component">
  <xs:complexType>
     <xs:simpleContent>
        <xs:extension base="xs:string">
            <xs:attribute use="optional" default="browse" name="perform">
             <xs:simpleType>
               <xs:restriction base="xs:string">
                   <xs:enumeration value="browse"/>
                   <xs:enumeration value="insert"/>
                   <xs:enumeration value="update"/>
                </xs:restriction>
              </xs:simpleType>
            </xs:attribute>
        </xs:extension>
     </xs:simpleContent>
  </xs:complexType>
</xs:element>

The resulting Master Files contains: 

FIELDNAME=COMPONENT, ALIAS=component, USAGE=A30, ACTUAL=A30,
 ACCESS_PROPERTY=(NEED_VALUE), $
 
FIELDNAME=PERFORM, ALIAS=perform, USAGE=A6, ACTUAL=A6,
 ACCESS_PROPERTY=(NEED_VALUE),
 
XDEFAULT='browse',
ACCEPT='browse' OR 'insert' OR 'update',
REFERENCE=COMPONENT, PROPERTY=ATTRIBUTE, $

Note that if no explicit value is provided for the field, the XDEFAULT value is used when the SOAP request is generated.

Using Arrays as Input Values

The Adapter for Web Services supports the use of arrays as input values. An array is described in the Master File using the GROUP definition with ACCESS_PROPERTY=ARRAY_ITEM. GROUP describes one instance of an object. You can provide input values for the array of objects using the following methods:

  • Specify lazy OR screening conditions for individual fields in a GROUP.
  • Specify lazy OR screening conditions for the GROUP itself. (Values for the individual GROUP fields must be separated by /).
  • Read values from a file specified as follows: 
    (IF group EQ (ddname))

    Only the GROUP describing an array can be used in an in-file construct. For example: 

    FILEDEF CARRAY DISK C:\Users\.........\countryarray.ftm
.
.
.
IF COUNTRY  EQ (CARRAY)

Note that only the last screening value is reported for an input array component.

Example: Using Arrays as Input Values

In the following example a segment defining the structure of an ESRI SOAP request retrieves a list of coordinates for the set of addresses. GROUP ADDRESSES are used to define one object item from the ADDRESSES array. The GROUP definition is extended by adding ACCESS_PROPERTY=ARRAY_ITEM and providing input values for the fields that comprise the array.

Master File 

SEGMENT=FINDADDRESS, SEGTYPE=S0, $
 GROUP=ADDRESSES, ALIAS=addresses, USAGE=A210, ACTUAL=A210,
 ACCESS_PROPERTY=ARRAY_ITEM, $ 
   FIELDNAME=HOUSENUMBER, ALIAS=houseNumber, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='2815', $
   FIELDNAME=STREET, ALIAS=street, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='PRAIRIE AVE.', $
   FIELDNAME=INTERSECTION, ALIAS=intersection, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), $
   FIELDNAME=CITY, ALIAS=city, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='MIAMI BEACH', $
   FIELDNAME=STATE_PROV, ALIAS=state_prov, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='FL', $
   FIELDNAME=ZONE, ALIAS=zone, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='33140', $
   FIELDNAME=COUNTRY, ALIAS=country, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='US', $
 GROUP=ADDRESSFINDEROPTIONS, ALIAS=addressFinderOptions, USAGE=A30,
 ACTUAL=A30, $
   FIELDNAME=DATASOURCE, ALIAS=dataSource, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE),
     XDEFAULT='GDT.Streets.US', $
   FIELDNAME=TOKEN, ALIAS=token, USAGE=A120, ACTUAL=A120,
     ACCESS_PROPERTY=(NEED_VALUE, AUTHTOKEN), $
   FIELDNAME=__RESPONSE, USAGE=TX80L, ACTUAL=TX,
     ACCESS_PROPERTY=(INTERNAL), $

Note: Although not illustrated in this example, you can use the ACCESS_PROPERTY=ARRAY_ITEM value to create nested GROUP definitions in which an inner GROUP object serves as an array inside an array. Using nested arrays, you can describe virtually any hierarchical object.

Screening on Leaf Components

Following are illustrations of the two variations on lazy OR screening on leaf components.

Note that it is not necessary to provide values for all fields in a GROUP since XML array item objects can be built with the subset of object components. However, the two screening methods have different conventions for dealing with missing values, as illustrated in the following examples.

Both of these requests produce identical elements in the MATCH array.

Explicit screening by field

When you are specifying lazy OR screening conditions for individual fields in a GROUP, the number of values and their positions must be the same for all field in the array GROUP.

Notice that each field below has three values. When an array is generated from this input, the first values in each line will be aligned, the seconds values will be aligned, and the third values will be aligned. Therefore, if values are omitted or misplaced, the alignment will be incorrect. 

IF HOUSENUMBER EQ '2815' OR 'Two' OR '1250'
IF STREET EQ 'PRAIRIE AVE.' OR 'Penn Plaza' OR 'Broadway'
IF CITY EQ 'MIAMI BEACH' OR 'NY' OR 'NY'
IF STATE_PROV EQ 'FL' OR 'NY' OR 'NY'
IF ZONE EQ '33140' OR '10121' OR '10001'
IF COUNTRY EQ 'US' OR 'US' OR 'US'

Note that there are no values for the INTERSECTION field in this screening request. When specifying individual fields explicitly you can simply omit any fields you are not interested in including in the array.

Screening for a whole group

When you specify lazy OR screening conditions for the GROUP, values for individual fields in the GROUP must be separated by a slash (/). Missing values like INTERSECTION must be accounted for using two consecutive slashed (//) on each line of the screening request. 

IF COUNTRY EQ '2815/PRAIRIE AVE.//MIAMI BEACH/FL/33140/US' OR 
              'Two/Penn Plaza//NY/NY/10121' OR 
              '1250/Broadway//NY/NY/10001'

In this example, INTERSECTION is represented by // after STREET and before CITY.

Using Arrays as Input Values for XML Elements and Their Attributes

You can apply standard Web Services array methodology to XML attribute values that are associated with parent XML array element values. The Parent array element is described with the ARRAY_ITEM value in the ACCESS_PROPERTY parameter. Associated attributes are linked to the parent element using the REFERENCE parameter, with the PROPERTY parameter set to ATTRIBUTE. You can supply input values for the element and attributes as you would for a regular array.

Example: Using Arrays as Input Values for an XML Element and its Attributes

Master File fragment: 

FIELDNAME=KEY, ALIAS=key, USAGE=A30, ACTUAL=A30,
  ACCESS_PROPERTY=(ARRAY_ITEM), $
FIELDNAME=NAME, ALIAS=name, USAGE=A30, ACTUAL=A30,
  ACCESS_PROPERTY=(NEED_VALUE), REFERENCE=KEY, PROPERTY=ATTRIBUTE,  $

Request fragment with screening statements: 

IF KEY EQ 'SHARE' OR 'BAE01A'
IF NAME EQ 'Setid' OR 'Location'

Generated SOAP request:

The screening statements yield an array of key/name occurrences in the soap request: 

<SOAP-ENV:Body>
    <m:GetQuote xmlns:m="http://ws.cdyne.com/">
       <m:key xsi:type="xsd:string" name="Setid"  >SHARE</m:key>
       <m:key xsi:type="xsd:string" name="Location" >BAE01A</m:key> 
   </m:GetQuote>
</SOAP-ENV:Body>

Modifying Namespace Qualifiers in WSDL Schemas

Namespace qualifiers are generated in the SOAP request document in accordance with the WSDL schemas. You can modify qualification rules in the Access File to affect how the SOAP XML request is built.

Qualification control information is stored in the Access File on the segment, namespace (Id), and element/attribute (Master File field) levels.

  • Segment level qualification governs qualifiers for all element/attributes in the Body/ Header, respectively, belonging to the target namespace. Segment level qualification information is taken from the schema level for the target namespace.
  • ID level qualification governs qualifiers for all element/attributes in the described namespace. ID level qualification information is taken from the particular namespace corresponding to the referenced schema.
  • Field level qualification governs qualifiers for the particular element/attribute and overwrites Segment/ID settings. Field level qualification is taken from the particular schema element type definition.

New parameters are introduced in the Access File in both the Segment and ID records:

  • ELEMFORM and ATTRFORM (for the SOAP Body).
  • HELEMFORM and HATTRFORM (for the SOAP Header).

A new FORM parameter is introduced in the Field record that describes the element or attribute.

Acceptable values for the new parameters are qualified and unqualified.

The default behavior (full qualification for all elements in the Header and Body, and no qualification for the attributes) is applied when no new parameters are found in the Access File.

See the XML Schema Part 0: Primer, which you can access at http://www.w3.org/TR/2001/REC-xmlschema-0-20010502/#NS, for details about Advanced Concepts: Namespaces, Schemas & Qualification.

Data Type Support

The following table lists how the server maps XSD data types in a Master File.

XSD Data Type

USAGE

ACTUAL

string

A30

A30

double

D20.2

A20

float

F15.2

A15

decimal

P20.3

A20

int

I11

A11

short

I6

A6

long

P20

A20

boolean

A5

A5

dateTime

HYYMDm

For related information, see Date-Time Processing.

A35

time

HHISsm

A15

date

YYMD

A10

gYearMonth

HYYM

A8

gYear

HYY

A5

gMonthDay

HMD

A6

gDay

HD

A3

gMonth

HM

A4

integer

P33

A33

nonPositiveInteger

P33

A33

negativeInteger

P33

A33

nonNegativeInteger

P32

A32

unsignedLong

P20

A20

unsignedInt

P10

A10

unsignedShort

I5

A5

positiveInteger

P32

A32

byte

I4

A4

unsignedByte

I4

A4

normalizedString

A30

A30

token

A30

A30

Name

A30

A30

NMTOKEN

A30

A30

ID

A30

A30

hexBinary

A30

A30

language

A30

A30

anyURI

A30

A30

QName

A30

A30

Date-Time Processing

How to:

Date-time formats can produce output values and accept input values that are compatible with the ISO 8601:2000 date-time notation standard.

Syntax: How to Enable ISO Standard Date-Time Notation 

SET DTSTANDARD = {OFF|ON|STANDARD|STANDARDU}

where:

OFF

Does not provide compatibility with the ISO 8601:2000 date-time notation standard.

ON|STANDARD

Enables recognition and output of the ISO standard formats, including use of T as the delimiter between date and time, use of period or comma as the delimiter of fractional seconds, use of Z at the end of "universal" times, and acceptance of inputs with time zone information. STANDARD is a synonym for ON.

STANDARDU

Enables ISO standard formats (like STANDARD) and also, where possible, converts input strings to the equivalent "universal" time (formerly known as "Greenwich Mean Time"), thus enabling applications to store all date-time values in a consistent way.

WebFOCUS

Feedback