mklemm2/graphit-tool-1

(Unofficial) Python library to work with the HIRO Graph, a semantic datastore for the arago HIRO Automation Platform.

graphit-tool

Small command line tool to work with GraphIT. Includes graphit.py, a library that can be used by other project. The API documentation can be found in the Wiki: API Documentation

IMPORTANT: The instructions below are outdated and only work with HIRO version 5. For HIRO 6, graphit-tool can only be used as a Python library, please have a look at the Wiki.

Installation

Download and install the .rpm packages from the releases page of this repository. There are some dependencies that require the “Extra Packages for Enterprise Linux” (https://fedoraproject.org/wiki/EPEL) repository to be active:

yum install epel-release # if necessary
yum localinstall graphit-tool-x.x-x.noarch.rpm

Setup

Setup WSO2 Service Provider and Policies

In order for graphit-tool to be able to access the Graph Database, a Service Provider has to be created and an access policy has to be installed.

Creating the Service Provider

1. Log into WSO2 and go to Main → Identity → Service Providers → Add
2. As Service Provider Name, fill in “graphit-tool” (exactly like that), the Description doesn’t matter. Click on “Register”

   

3. Open “Inbound Authentication Configuration” → “OAuth/OpenID Connect Configuration” and click on “Configure”.

   

4. Uncheck everything but “Client Credentials” and click “Add”.

   

5. Click on “Show” and copy the client key and the client secret. You’ll need them later in the configuration:

   

6. Click on “Update”

Adding the co.arago.GraphIT-allow-All-graphit-tool policy

IMPORTANT: This step is always necessary as it grants graphit-tool access to the Graph Database. Without this policy, graphit-tool will not be able to write to the Graph Database.

The policy can be downloaded here: policies/co.arago.GraphIT-allow-All-graphit-tool.xml

1. Go to Main → Entitlement → PAP → Policy Administration
2. Click on “Add New Entitlement Policy” and select “Import Existing Policy”.
3. Select the co.arago.GraphIT-allow-All-graphit-tool.xml file and click on “Upload”.
4. Back in the policy list, publish the new “co.arago.GraphIT-allow-All-graphit-tool” policy by clicking on “Publish to My PDP” and then on “Publish”.

Copying the Graphit-Server and WSO2 certificates

Get graphit-server.pem and wso2carbon.pem from your HIRO instance’s IAM and Database node (they’re located at /opt/autopilot/conf/certs/) and copy them to /usr/share/graphit-tool/

Configuration

The system–wide configuration file is located at /etc/graphit-tool.conf. User–specific settings can be stored in ~/.graphit-tool.conf.

The configuration file looks like this:

[Graphit]
URL: https://graphit.yourdomain.com:8443
VerifyCert: /usr/share/graphit-tool/graphit-server.pem

[WSO2]
URL: https://wso2.yourdomain.com:9443
VerifyCert: /usr/share/graphit-tool/wso2carbon.pem
ClientID: GRAPHIT_TOOL_CLIENT_ID
ClientSecret: GRAPHIT_TOOL_CLIENT_SECRET

[MARS]
Schema: /usr/share/graphit-tool/MODEL_default.xsd

The following values must be set:

Setting	Value
Graphit → URL	REST URL of your GraphIT (same as cockpit URL)
Graphit → VerifyCert	Path to the graphit-server certificate. If you’re using public certificates that can be verified using the system’s keychain, this can also be set to “Yes”. Setting this value to “No” disables certificate verification.
WSO2 → URL	REST URL of your WSO2 (same as WSO2 admin interface)
WSO2 → VerifyCert	Path to the wso2carbon certificate. If you’re using public certificates that can be verified using the system’s keychain, this can also be set to “Yes”. Setting this value to “No” disables certificate verification.
WSO2 → ClientID	ClientID of the congigured Service Provider (see section “Creating the Service Provider” above
WSO2 → ClientSecret	ClientSecret of the configured Service Provider

Usage

graphit-tool

Usage:
  graphit-tool [options] mars list[--count] [PATTERN]...
  graphit-tool [options] mars put [--chunk-size=NUM] [--replace] FILE...
  graphit-tool [options] mars get [--out=DIR] NODEID...
  graphit-tool [options] mars del [--chunk-size=NUM] [--del-ci] NODEID...
  graphit-tool [options] mars sync NODEID...
  graphit-tool [options] mars sync (--count-unsynced|--list-unsynced)
  graphit-tool [options] token (info|get)
  graphit-tool [options] ci (count_orphans|cleanup_orphans)
  graphit-tool [options] ci create --attr=ATTR NODEID...
  graphit-tool [options] issue getevent [--field=FIELD...] [--pretty] IID...
  graphit-tool [options] vertex get OGITID...
  graphit-tool [options] vertex query [--count] [--list] [--field=FIELD...] [--pretty] [--] QUERY...
  graphit-tool [options] vertex setattr --attr=ATTR --value=VALUE NODEID...

Switches:
  -o DIR, --out=DIR          save node to <node_id>.xml in given directory
  -f FIELD, --field=FIELD    Return only given fields
  -p, --pretty               Pretty print JSON data
  -c, --count                return the number of results, not the results themselves
  -C NUM, --chunk-size=NUM   Upload NUM MARS nodes in parallel
  -R, --replace              Replace existing nodes instead of updating them. Before 0.3.2, this
                             was the default behavior.
  -h, --help                 print help and exit

Options:
  -d, --debug                print debug messages

Recent Changes

0.3.4

• ci create command to create additional ConfigurationItems
• vertex setattr command to set attributes of GraphitNodes

0.3.3

• performance improvements for concurrent operations
• enhanced logging when uploading MARSNodes

0.3.2

• mars put for already existing MARSNodes now uses POST instead of PUT per default. The old behavior can be restored with the --replace command line switch.

License (MIT)

Copyright (c) 2017 arago GmbH

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.