ibm.infosvr-openigc

ansible-role-infosvr-openigc

This is an Ansible role that helps automate the deployment of OpenIGC objects for the Information Governance Catalog in IBM Information Server.

If you're new to Ansible, you might find this simple introduction helpful.

Requirements

Ansible version 2.6.x
The following tools must be installed on your control machine:
- zip
- curl

The role works without needing special permissions and mainly runs on the control machine (it sends generated files directly to the relevant APIs).

Since this role uses advanced Jinja templating for the YAML inputs, you need a recent version of Ansible (version 2.6.x or higher is necessary). Although version 2.7 can send files using the uri module, it doesn't allow you to change the certificate authority. Therefore, we continue to use curl for validating self-signed certificates.

Role Variables

Check the defaults/main.yml for detailed information and see the examples below for the main variables you need.

This role will try to automatically use variables from the IBM.infosvr role. For example, you can use a playbook that first imports IBM.infosvr with tasks_from=setup_vars.yml.

By default, the role will check SSL certificates if you've retrieved them using the get_certificate.yml task from IBM.infosvr (see the example playbook). This behavior is controlled by the ibm_infosvr_openigc_verify_selfsigned_ssl variable. If you want to only trust properly signed SSL certificates, set this variable to False.

Example Playbook

This role is primarily meant to be imported into other playbooks as needed for deploying OpenIGC objects, such as bundles and asset instances.

---
- name: Setup Information Server variables
  hosts: all
  tasks:
    - import_role: name=IBM.infosvr tasks_from=setup_vars.yml
    - import_role: name=IBM.infosvr tasks_from=get_certificate.yml

- name: Load OpenIGC bundles and assets
  hosts: ibm_information_server_engine
  roles:
    - IBM.infosvr-openigc
  vars:
    bundles:
      - /some/directory/<BundleId>
    assets_as_xml:
      - /some/directory/asset_instances-<BundleId>.xml
    assets_as_yaml:
      - /some/directory/assets.yml
    flows_as_xml:
      - /some/directory/lineage_flows-<BundleId>.xml
    flows_as_yaml:
      - /some/directory/lineage.yml

Action and Object Structures

This section outlines the actions and object types supported by this role and their expected formats. The order in which variables are listed in the playbook does not affect loading; they will be processed in the order shown here.

`bundles`

The directories listed here should follow a specific bundle format:

<BundleId>: the main directory should exactly match the bundle name (case-sensitive).
- asset_type_descriptor.xml: this XML file describes the bundle's classes and their relationships.
- i18n: a folder for labels
  - labels.properties: file containing translatable labels for classes and attributes.
- icons: a folder containing two .gif files for each class:
  - <ClassId>-icon.gif: a 16x16 pixel icon (can also be .png) but named .gif.
  - <ClassId>-bigIcon.gif: a 32x32 pixel icon (can also be .png) but also named .gif.

`assets_as_xml`

This variable should provide fully-formed XML files for asset instances, either pre-generated or created manually.

`assets_as_yaml`

This variable offers a more readable way to specify asset instances compared to the XML format required by assets_as_xml.

Use this variable to provide YAML files for generating valid asset instance XMLs. The structure should look like this:

---

bundleId: $<BundleId>
contains:
  - class: <ClassName>
    name: <name>
    contains:
      - class: <NestedClassName>
        name: <name>
        contains:
          ...

You can nest the contains structure as needed for your assets. Each entry must include at least a class and name.

You may add additional attributes as allowed by your bundle definition (e.g., short_description, long_description). Prefix any bundle attributes with $. For example:

---

bundleId: $TestBundle
contains:
  - class: Folder
    name: level1
    short_description: The top-level directory
    $filesystem: UNIX
    contains:
      - class: Folder
        name: level2
        short_description: The next level down
        contains:
          - class: File
            name: MyFile.txt
            short_description: A file in /level1/level2/MyFile.txt
            $encoding: UTF-8

For attributes that accept multiple values, list these values as a YAML list. For example:

---

bundleId: $TestBundle
contains:
  - class: Folder
    name: root
    $users_with_access:
      - user123
      - user456
      - user789

You can also simplify leaf nodes by using the names shortcut, allowing you to specify just the names without repeating the class:

---

bundleId: $TestBundle
contains:
  - class: Folder
    name: root
    contains:
      - class: File
        names:
          - MyFile.txt
          - YourFile.txt
          - OtherFile.txt

`flows_as_xml`

This variable should contain fully-formed lineage flow XML files, either pre-generated or created manually.

`flows_as_yaml`

This variable provides a more readable way to specify lineage flows than the XML format required by flows_as_xml.

Use this to list YAML files that create valid lineage flow XMLs. Each YAML file should have this structure:

---

assets:
  - class: <FullClassName>
    name: <name>
    contains:
      - class: <NestedFullClassName>
        name: <name>
        id: <unique identifier>
        contains:
          ...

flows:
  - name: <description>
    within: <id>
    contains:
      - name: <description>
        from:
          - <id>
          - ...
        to:
          - <id>
          - ...
      - ...

The contains structure for assets can be nested as needed. Each must have a class and name defined. Use fully-qualified class names, which include the bundleId (e.g., $BundleId-ClassName), so you can combine OpenIGC and native assets.

Make sure to include a unique id for each asset used in the flow, which makes it easier to reference them in the flows variable. Avoid spaces and special characters in the id, except for . and _.

For example:

---

assets:
  - class: $TestBundle-Folder
    name: root
    contains:
      - class: $TestBundle-File
        name: MyFile.txt
        id: MyFile.txt
      - class: $TestBundle-File
        name: YourFile.txt
        id: YourFile.txt
      - class: $TestBundle-File
        name: OtherFile.txt
        id: OtherFile.txt
  - class: $TestBundle-Command
    name: copy
    id: copy

flows:
  - name: Copy command to duplicate a file
    within: copy
    contains:
      - name: Copy from My to Your and Other
        from:
          - MyFile.txt
        to:
          - YourFile.txt
          - OtherFile.txt

In this example, a TestBundle defines Folder, File, and Command objects. The assets section describes the structure we want in the lineage, including unique ids for each asset.

The flows section creates the lineage by specifying the process and the inputs and outputs of the action.