Designing templates with GitLab or GitHub as a data source

You might want to create a document-style report that tracks tasks or other artifacts in GitLab or GitHub.

Before you begin

Get familiar with the GitLab APIs and the various URLs needed in order to extract JSON data.

About this task

Data is extracted by using the REST API. This interface is installed and implemented with the data source application and works independently of IBM Engineering Lifecycle Optimization - Publishing (PUB). For more information about the REST API for a data source, see the documentation for that data source.

Procedure

  1. Review Designing document templates for an overview of the template development process.
    Start planning the structure of your document-style report and the data that might be included.
    For example, decide whether the final document-style report will be generated from one template or from multiple template files that each contain reusable pieces of content.
  2. In Create a document template.
  3. Identify a data source schema from your data source.
  4. Add a data source schema to your document template.
    For JSON data, you can complete the following steps:
    1. In Document Studio, click Data > Add Data Source .
    2. In the Type field,
      select JSON.
    3. To add the schema from GitLab or GitHub instance, edit the Schema field to enter the schema URL.
      Example:
      • http://<server>/api/v4/projects/<id>/repository/commits
    4. Click Next and then Finish.
    5. Select the Authentication Type from the list.
    6. If the resource is on a secured server, specify the Username.
    7. If the resource is on a secured server, specify the Password.
      Note: The user can specify the user password or the application password that is generated by the configured third-party identity provider, such as SAML or OIDC. User must select Basic authentication method while using application password.
    Tip: To edit the JSON schema, in the Outline view, expand Data Source Schemas. Right-click the schema and select Open Schema In Editor. The schema opens in the JSON editor. This is useful if you want to add some attributes to the schema.
  5. Add elements to the template.
    The product includes a comprehensive set of template elements that you can use to structure your document-style report. You can drag elements into the template content editor. For example, you can add a Container element to hold several paragraphs. Each paragraph might be controlled by a test condition that associates it only with specific data. For more information, see Template elements in the Palette view and Adding elements to a template.
  6. Use queries, attributes, and variables to add data to a template. These items specify which pieces of information are generated in the report.
  7. Add formatting and styling to the elements to control how they display in the output.
  8. Create filters to narrow the data that is pulled into the report.
    You can use filters, which are detailed versions of the general data source URI, to point to specific subsets of data so that Engineering Publishing ( PUB) does not try to retrieve more information than necessary from the data source during report generation. These filters must be broad enough to retrieve all necessary data referenced by the template or the generated report cannot include complete data.
  9. Create sorts to organize the data in your report.