Mapping to complex documents

To create the mapping of a complex document, you first need to create forms and a complex XML Schema. See Advanced-XML-editing. Select the parent form as the base form of the web service. Additional forms are used as child forms. You should not use a child form with more than one parent form.

In addition to the following procedure, see these topics for more information:

To map to complex documents

1. In BMC Remedy Developer Studio, open a web service for editing.
2. Expand the WSDL Ports panel, the Port panel, and the WSDL Operations panel.

3. Click the operation you want to map, expanding the corresponding panel.
    Tables for input and output mapping appear.

   Note

   BMC Remedy AR System sets default mappings automatically when you create a web service or when you add an operation to a web service.

4. Select the Data Source type for your mapping.

   1. To have BMC Remedy AR System automatically generate a basic XML schema, set the Data Source Type to Generated, click the Auto Map button, and skip to step f.

      Note

      You cannot use Developer Studio to modify XML elements in an external XML schema. To modify XML elements in an external schema, edit the XML schema file directly.

   2. If you are using an external XML schema, set the Data Source Type to XML Schema.

      Note

      The XML Schema option is available only if you specify a file name in the XML Schema panel, and the file has been loaded.

   3. Select Support XSI Type, if necessary.
       If this option is selected, the system specifies XSI Type for all XML data while creating XML documents.
   4. Click Choose, then click OK to verify that you want to change the mapping.
       The Choose Start Element dialog box appears, displaying complex types and elements.
      
      Choose Start Element dialog box
      
      
   5. Select your start element or complex type. See Importing an external XML schema.

   6.  Verify that your XML elements and complex types are displayed in the XML Data Type column, and the parent form and fields are displayed in the Form/Field column (see the following figure).
      
      Input mapping section in an operation on the WSDL Operations tab
      

      Tip

      To view the XML properties of an object in the XML Data Type column, hover your mouse over the object. To edit XML properties, select the object and click the ellipsis button (...).

5. Review the mappings, and make any necessary adjustments to forms, fields, and elements in your XML schema. (See the following figure.)
    To replace a form or field in the Form/Field column, select the object and click the adjacent ellipsis button (...).
6. Add child forms to the list of mapped objects.
   1. Right-click the ROOT element in the XML Data Type column.
   2. Select New > Element > Form.
   3. Rename the new form element that appears under ROOT.
   4. Click the corresponding (blank) field in the Form/Field column.
   5. Click the ellipsis button (...), and select a form for mapping to your new form element.
7. In the row where your parent form is mapped, click the field in the Mapping Info column.
    The parent form is typically mapped to the ROOT element.
    The Primary Key selector appears.
   
   Primary Key selector
   
8. Click the ellipsis button (...) and select a field to use as the primary key.
    This is the field that uniquely identifies the entries in the specified form. It is typically the Request ID field. The list of primary keys is limited to character fields specified as unique in Form > Form Properties > Indexes.
9. Click OK to close the Primary Key dialog box.

10. Map any other fields in the parent form to elements in the XML schema.

    Note

    When you create a filter to consume a web service, the output mapping table does not allow you to select fields that only the system can modify. You must map to the same data types. If you hover the cursor over the XML element name or field name, the tooltip shows the data type. See Mapping an XML element to a BMC Remedy AR System field.

11. In the row where one of your child forms is mapped, click the field in the Mapping Info column.
     The Distinguishing Key and Foreign Key selectors appear.

12. Click the ellipsis button (...), and select a value for Distinguishing Key.
     This is the value that uniquely identifies each of the detail items in the child form of any given parent entry.

    Note

    The BMC Remedy AR System server does not allow the mapping of an integer as the distinguishing key during the consumption of a web service.

13. Click the ellipsis button (...) and select a value for Foreign Key.
     The combination of distinguishing key and foreign key should uniquely identify an entry in a child form. BMC Remedy Developer Studio does not enforce this relationship, but the AR System server returns an error if it detects noncompliance.
     A field specified as foreign key should not be used in any field mapping, because the system uses this field to store the foreign key. If it is mapped, the value of the mapped XML element is usually overridden by the foreign key value.
14. Map any other fields in the child form to XML elements.
    
    Mapping for a Get operation (complex document)
     (Click the image to expand it.)
    
    

15. Repeat step 11 to step 14 to map other child forms to XML elements.

    Note

    The immediate children of all or choice element type cannot be mapped to another form. To map choice nodes, map the choice node in the XML schema to the choice field in a form before mapping the choices.

16. Save your web service.
     See Supported-schema-constructs-and-web-service-limitations.