Explore the sample REST template

The sample template, Tutorial_Rest.dta, is in the IBM® Rational® Publishing Engine installation in the REST Examples folder. The template contains a configured REST data source and elements that you can use to generate a REST output document.

This sample uses the Rational Insight Data Services and the adaptor for IBM Rational RequisitePro®. The sample is also valid for XML data sources, except for the built-in Schema Discovery and Data Source Discovery tools.

You can find the sample template, Tutorial_Rest.dta, in %RPE_HOME%\source\REST\examples.

Basic setup

Create a document template, add a data source, add template elements, such as conditions, table of contents, and images, and generate the document.

1. Obtain the schema

A schema is required to design templates and generate documents.

To obtain the schema:

  1. Create a new document and start the REST Schema Discovery by clicking Data > Schema Discovery > REST Schema Discovery.
  2. Specify the connection details in the following fields:
    1. URL: Specify the base URL for the resource.
    2. Authentication Type: Select the authentication type from the list.
    3. User: Specify the user name if the resource is on secure location.
    4. Password: Specify the password if the resource is on secure location.
      Note: For more information about the base URL and the credentials, refer to the REST data source documentation.
  3. Click Next.
  4. In the Create a Resource window, specify the details for the new resource in the following fields:
    1. Name: Specify a name for the new resource.
    2. Description: Specify a description for the new resource.
    3. Relative path: Select the Manual Entry option to specify a relative path manually for the new resource or click Locate using data service to locate the resource.
      REST Resource Discovery Wizard
    4. To select the resources using the Locate using data service:
      1. In the left pane, select an element in the XML schema tree.
      2. In Element attributes, select the href value from the attributes list box.
        Locate resource using data services
      3. Click Next. The resource URL is displayed for the selected resource.
        REST URL discovered by data source
      Note: Either select the URL and click Finish, or you can use the URL to locate the child resource.
  5. To use the URL to locate the child resource:
    1. Select the resource URL and click Next.
    2. Select an element in the XML schema tree from the left pane.
      Locating child resource
    3. Select the href value from the Element attributes section and click Next. The resource URLs for the resource is displayed.
    4. Select the resource URL discovered by the data source.
      Child resource URLs discovered by data source
  6. Click Finish.

2. Defining template content

To define template content:
  1. From the Palette view, drag the Container element to the editor area, and name the element as Packages Container for easier reference.
  2. From the Data Source Schema view, drag the Project.Packages.Package query to the container element.
  3. From the Palette view, add the Paragraph element to the container element.
  4. From the Data Source Schema view, drag the Name element listed under Package to the paragraph element. At this point, a Select Context window is displayed to select how you want to use that element, as a query or as a value.
  5. Select Use as Value, and click OK. A new text element is created inside the paragraph and its content is set to the Name attribute.
    Adding Name element
  6. Add a paragraph element, and add the description attribute from the Data Source Schema for the package, and format the element as italic.
    Adding Description element
  7. List all the requirements from this package:
    1. From the Palette view, add the List element under the Paragraph element.
    2. Doube-click the list element. The New List window opens.
    3. Type 1 in the Insert the number of items field to create a list with a single item.
    4. Click OK in the New List window.

      New List window

  8. Drag the RequirementsInPackage.Requirement element from the Data Source Schema view to the list detail.
    Adding requirements from the package
  9. Add three text elements from the Palette view to the list detail.
    Adding Text element to list detail
  10. Double-click on the first text element to open the Set Content for Current Element window.
  11. In the Set Content for Current Element window, click the Data Expression tab, expand the Project.Packages.Package.Requirement, and select FullTag attribute.
    Set content for first text element
  12. For the second text element, click theSimple value tab, and type hyphen (-) to set the content as the static text.
    Set content for second text element
  13. For the third text element, click the Data Expression tab, expand the Project.Packages.Package.Requirement, and select Text to set the content as the text attribute.
  14. Click OK in the Set Content for Current Element window.
  15. 15. Optionally, add the following elements to further customize the template:
    1. From the Palette view, add Table of Contents element to the top of the template.
    2. Define a style and apply to a paragraph containing the package name:
      1. In Document Studio, clickStyle > New Style.
      2. In the Style name field, type Style1 for the style name, and then click Next. The Select style properties window opens.
      3. In the Select style properties window, from the left pane, select the property or group of properties that you want to apply to the template element (for example, text) and click Selecting a style icon to move it to the right pane, and then click Next.
        Adding style property
      4. In the Set Property Value window, type the value in the Property Value column for each property, and then click Next.
      5. Review the summary and click Finish.
    3. if the description is empty, set a condition to exclude it from output:
      1. Right-click the Paragraph element containing the description, and click Data > Edit Condition. The Set Condition for Current Element window is displayed.
      2. In the left pane, expand Attributes and select the check box for the Description attribute.
      3. In the right pane, select the Left operand field to Description.
      4. Set the Operator field to Not equal to.
      5. Type a space in the Right operand field, and then click OK. Set condition to the paragraph element
    4. Replace the text element containing the requirement ID with a hyperlink that contains the href attribute of the requirement:
      1. Drag the Hyperlink element from the Palette view to the Project.Packages.Package.Requirement attribute.
      2. In the Data Source Schema view, add the href attribute to the Project.Packages.Package.Requirement attribute.
        Add hyperlink
      3. In the Properties view, expand Specific, and in the value column of the display property, click Setting field value.
      4. In the Set Display Value window, expand the $2 Project.Packages.Package.Requirement attribute, and click the check box for the FullTag attribute.
        Set display value
      5. Click OK.
      6. Apply the InternalHyperlink style to the hyperlink.
  16. Save the template.

4. Generating the document

Switch to the Launcher perspective. If the perspective icon is not visible under the toolbar use the button located in the top left part of the screen, right below the toolbar.

Note: When the keep document specification synchronized preference is selected, the document specification is synchronized with the edited template at every load, close, and save operation. If the preference is not selected, you must manually synchronize the document specification.
To configure the data source:
  1. In the Document Specification window, expand Templates > Data Sources.
  2. Right-click the Data Sources and then click Configure Data Source. In the REST Database Source Selection wizard, click Next.
  3. Specify the connection details:
    • If you know the URL for the REST resource, specify the URL, user name and password if the resource is at a secure location, and then click OK.
    • If you do not know the URL, click Discover to locate the resource.
  4. Click Next.
  5. Specify the connection details in the following fields:
    1. URL: Specify the base URL for the resource.
    2. Authentication Type: Select the authentication type from the list.
    3. User: Specify the user name if the resource is at a secure location.
    4. Password: Specify the password if the resource is at a secure location.
  6. Click Finish.
  7. After you configure the data source, generate the document by clicking Publish > Generate Document or by clicking Generate Document icon icon.
Note: When the document is generated from REST data sources, it logs the URLs it uses. You can copy those URLs from the log and use them in a browser to see the data content.

Feedback