irods_testbench_training_python_bash/client_metadata_example/README.md

# Example client side iRODS rule to show metadata operations

- The rule requires the local host be connected/authenticated to iRODS server with the appropriate ~/.irods directory and contained connection profile
- The rule does not require any input
- The rule is written in the iRODS native rule engine language
- The rule is intended to be run client side only, most functions and microservices will work in server side rules, some will not
- The rule intends to assist users with common metadata manipulation tasks
- To augment existing workflow scripts, the user could call their custom metadata rule passing an iRODS data-object as INPUT

## Run the rule

- remove the data-object generated from iRODS rule
`irm test.txt`
- clear the trash to ensure there is no history of the data-object
`irmtrash`
- run the rule, pass -t for test mode,-F for file (data-object), specify the rule engine with -r (this is only required if multiple rule engines are present on the server - such as the python rule engine)
`irule -r irods_rule_engine_plugin-irods_rule_language-instance -F ~/test-meta.r`
- check test.txt now exists
`ils test.txt`
- check metadata of test.txt, -d for file (data-object)
`imeta ls -d test.txt`
- the rule output should resemble
```
a = 10
zebra = horse
hula = dance
art = crayon
timestamp = 2021-06-30.12:09:54
a || 10
zebra || horse
hula || dance
art || crayon
timestamp || 2021-06-30.12:09:54
a
zebra
hula
art
timestamp
1: a = 10
1: zebra = horse
1: hula = dance
1: art = crayon
1: timestamp = 2021-06-30.12:09:54
2: a = 5
2: zebra = horse
2: no match
2: no match
2: timestamp = 2021-06-30.12:09:54
3: AND a = 10
3: zebra = horse
3: art = crayon
3: timestamp = 2021-06-30.12:09:54
4: collection exists: /OCF/home/rods true
4: file created: /OCF/home/rods/test.txt
4: metadata to keep on /OCF/home/rods/test.txt, a=10
4: metadata to keep on /OCF/home/rods/test.txt, art=crayon
4: metadata to remove from /OCF/home/rods/test.txt, hula=dance
4: metadata to remove from /OCF/home/rods/test.txt, timestamp=2021-06-30.12:09:54
4: metadata to remove from /OCF/home/rods/test.txt, zebra=horse
4: year: 2021
4: file: test.txt created between 2020 - 2030
5: writeoff: catC saab £1200
```

## What does the script do?

- creates a metadata array like object from a delimited string of key value pairs
- adds key value pairs to the metadata object
- finds values from keys and keys from values
- example of conditional behaviour based upon key value match
- tests for existence of file in iRODS
- add/remove metadata conditionally where file (data-object) iRODS exists
- creates a file (data-object) in iRODS with simple string content, the file did not pre-exist on a local filesystem
- convert metadata object to metadata structure and apply to iRODS file (data-object)
- use inbuilt function to list iRODS path (collection) and iRODS file (data-object) from a full iRODS path (ZONE + collection + data-object)
- perform SQL like query against the iCAT database to find a file (data-object) with specific keys or values, output specific metadata keys to metadata structure from query result
- loop metadata structure conditionally and remove unwanted key value pair
- remove key value pair without looping using more recent inbuilt function
- use inbuilt function to get and format date/time, use inbuilt split function to create year/month/day key value pairs
- accociate metadata structure directly to an iRODS file (data-object)
- perform SQL like query against the iCAT database to find a file (data-object) with a key value between a range of values
- illustrate usage of the new microservice msiModAVUMetadata to perform all metadata operations that previously required many intermediatory steps
- car lot example, use existing metadata to decide if a car is to sell or writeoff, the *new* unit attribute of a key value pair is used more granular metadata evaluation