Creating REST data source schema

A data source schema can be created for a REST data source. Creating schemas simplifies authoring document templates for modules with the same structure, and same or similar attribute list.

About this task

You can use the Schema discovery wizard to create data source schemas. You can select from the two options depending on what reportable REST your application supports, REST API 1.0 or REST API 2.0. Check with your system administrator if you do not know the API version that your application supports.

Schema Discovery (REST API 1.0)

Procedure

Note: This is used to help in locating the schema in Rational Team Concert and data sources using data services. For other REST based applications, see your product documentation for information on generating schemas.

  1. In Document Studio, click Data > Schema Discovery > REST Schema Discovery.
  2. Specify the connection details:
    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.
  3. Click Next.
  4. In the Create a Resource window, specify the details for the new resource:
    1. Name: Specify a name for the new resource.
    2. Description: Specify a description for the new resource.
    3. Relative path: Specify a relative path for the new resource.
    If the REST data source is accessible through the Data Services adaptors, use the Locate using data service option to locate the resource. Resource navigation is available for resources having an href attribute. You must drill down until you identify the resource you need.
  5. To select the resources:
    1. In the left pane, select an element in the XML schema tree.
    2. In the right pane, select the href value from the attributes list box.
    3. Click Next. The resource URL is displayed for the selected resource.
    At this point, select the URL and click Finish or you use the URL to locate the child resource.
  6. 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.
    3. Select the href value from the attributes list box from the right pane.
  7. After you identify the resource, click Finish. The wizard completes and the URL you have discovered is displayed in the Configuration window. You can provide a user name and password in the configuration window if the resource is at a protected location.

What to do next

You can now add this schema to you template, see Adding data source schemas.

Schema Discovery (REST API 2.0)

About this task

Note: Rational Publishing Engine supports only the abbreviated RDF. The providers must accept and honour "application/xml" requests. See Open Services for Lifecycle Collaboration Core Specification Version 2.0.
RPE only supports OSLC v2 providers that follow the Reportable REST v2 Specification.
  • An OSLC Service must have Query Capabilities defined in Service Resource for all resources intended for Reporting.
  • Each Query Capability for Reporting,
    • must have oslc:queryBase pointing to the resource that has a list of resources intended for Reporting. The resources in the list must be identified as oslc:isMemberProperty in the Resource Shape Resource of the list resource.
    • must have oslc:resourceShape to describe the list resource.

Procedure

  1. On the Menu bar, click Data > Schema Discovery > REST v2 Schema Discovery.
  2. Enter the REST v2 Service Provider URL. Your system administrator will provide this URL. The URL once entered, will be stored and displayed any time you open the REST v2 Schema Discover Wizard.
    You need to know the URL of the service provider that you want to accept. This URL is the counterpart of the data services URL for the reportable REST data source. Rational Publishing Engine will fetch the data from the datasource as a list of queries. These are resources stored by the service from which data can be queried and interpreted as desired. (Also provides a query service that help filter data according to a set condition, or refine the sub sets of data). These queries are for a type of resource. They allow you access the resource of a given type. A reportable ID2 service can expose many resources types such as a product, user change request etc. The query service will help the user to efficiently retrieve data or a sub set of the data. But its not mandatory. The a query service exists for all the resources. Every product has the freedom to define its resources and the queries that access these resources.
  3. Select Form Authentication or OAuth Authentication. These are the two types of authentication supported by the reportable specification.
  4. Enter your username and password and click Next.
  5. Select a REST v2 service and its corresponding query and click Next. The properties of the selected services are displayed.
  6. Select the required properties from the list and click Test oslc.select. A Result Confirmation screen displays your selected services asking you to confirm if they are correct or incorrect. If you click Correct, the Test oslc.select field status will turn true. By default it is false. Click Next.

    The Test oslc.properties field is not used very often.

    Note: It is not mandatory to click the Test buttons.
  7. You need to enter only the filter or sort clause of the query, such as cq:Product{cq:Product="Rational Publishing Engine"} in the Query include oslc.where clause and the Query include oslc.orderBy clause and click the Test oslc.where and Test oslc.orderBy buttons. Rational Publishing Engine will create the full request using the options defined in the previous wizard pages.
    Note: It is not mandatory to click the Test buttons.
  8. Click Next. The summary of your query displays. Click Finish. The wizard completes and the URL you have discovered is displayed in the Configuration window. You can provide a user name and password in the configuration window if the resource is at a protected location.

Feedback