The REST sample data is provided in the Rational® Publishing Engine installation,
which you can use to generate a REST template and report.
Basic overview
This topic helps you to create
a document template, add a data source, add template elements, such
as conditions, table of contents, and images to the template and generate
the document.
You can find
the finished template that this topic helps you to create in %RPE_HOME%\source\REST\examples\Tutorial_Rest.dta.
This
sample uses the IBM® 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.
Before you
begin:
- The web services must be deployed.
- The data services must be deployed.
- The Rational RequisitePro data
source adapter must be deployed.
1. Obtaining the schema
A schema is required
to design templates and generate documents.
To obtain the schema:
- Create a new document and start the REST Schema Discovery by clicking .
- Specify the connection details in the following fields:
- URL: Specify the base URL for the resource.
- Authentication Type: Select the authentication
type from the list.
- User: Specify the user name if the resource
is on secure location.
- 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.
- Click Next.
- In the Create a Resource window, specify
the details for the new resource in the following fields:
- Name: Specify a name for the new resource.
- Description: Specify a description for
the new resource.
- 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.
- To select the resources using the Locate using data service:
- In the left pane, select an element in the XML schema tree.
- In Element attributes, select the href value from the attributes
list box.
- Click Next. The resource URL is displayed
for the selected resource.
Note: Either select the URL and click Finish,
or you can use the URL to locate the child resource.
- To use the URL to locate the child resource:
- Select the resource URL and click Next.
- Select an element in the XML schema tree from the left pane.
- Select the href value from the Element attributes section and
click Next. The resource URLs for the resource
is displayed.
- Select the resource URL discovered by the data source.
- Click Finish.
2. Defining template content
To define template
content:
- From the Palette view, drag the Container element
to the editor area, and name the element as Packages Container for
easier reference.
- From the Data Source Schema view, drag the Project.Packages.Package query
to the container element.
- From the Palette view, add the Paragraph element
to the container element.
- 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.
- 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.
- Add a paragraph element, and add the description attribute from
the Data Source Schema for the package, and format
the element as italic.
- List all the requirements from this package:
- From the Palette view, add the List element
under the Paragraph element.
- Doube-click the list element. The New List window
opens.
- Type 1 in the Insert the number of items field
to create a list with a single item.
- Click OK in the New List window.

- Drag the RequirementsInPackage.Requirement element
from the Data Source Schema view to the list
detail.
- Add three text elements from the Palette view
to the list detail.
- Double-click on the first text element to open the Set Content
for Current Element window.
- In the Set Content for Current Element window,
click the Data Expression tab, expand the Project.Packages.Package.Requirement,
and select FullTag attribute.
- For the second text element, click theSimple value tab,
and type hyphen (-) to set the content as the
static text.
- 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.
- Click OK in the Set Content for
Current Element window.
- 15. Optionally, add the following elements to further customize
the template:
- From the Palette view, add Table
of Contents element to the top of the template.
- Define a style and apply to a paragraph containing the package
name:
- In Document Studio, click.
- In the Style name field, type Style1 for
the style name, and then click Next. The Select
style properties window opens.
- 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
icon to move it to the right pane, and then click Next.
- In the Set Property Value window, type the
value in the Property Value column for each
property, and then click Next.
- Review the summary and click Finish.
- if the description is empty, set a condition to exclude it from
output:
- Right-click the Paragraph element containing the description,
and click . The Set Condition for Current Element window
is displayed.
- In the left pane, expand Attributes and
select the check box for the Description attribute.
- In the right pane, select the Left operand field
to Description.
- Set the Operator field to Not
equal to.
- Type a space in the Right operand field,
and then click OK.

- Replace the text element containing the requirement ID with a
hyperlink that contains the href attribute of the requirement:
- Drag the Hyperlink element from the Palette view
to the Project.Packages.Package.Requirement attribute.
- In the Data Source Schema view, add the href
attribute to the Project.Packages.Package.Requirement attribute.
- In the Properties view, expand Specific,
and in the value column of the display property,
click
.
- In the Set Display Value window, expand the $2 Project.Packages.Package.Requirement
attribute, and click the check box for the FullTag attribute.
- Click OK.
- Apply the InternalHyperlink style to the hyperlink.
- 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:
- In the Document Specification window, expand .
- Right-click the Data Sources and then
click Configure Data Source. In the REST Database
Source Selection wizard, click Next.
- 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.
- Click Next.
- Specify the connection details in the following fields:
- URL: Specify the base URL for the resource.
- Authentication Type: Select the authentication
type from the list.
- User: Specify the user name if the resource
is at a secure location.
- Password: Specify the password if the resource
is at a secure location.
- Click Finish.
- After you configure the data source, generate the document by
clicking Publish > Generate Document or by
clicking
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.