PID creation and deletion + documentation

interactiveRules/pid-test-rules/README.md

@@ -85,7 +85,42 @@ The PID suffix is by bets practice a UUID.
 
 ### Example rules
 
-- Create PID:
-- Add metadata to PID:
-- 
+#### Create EPIC PIDs
+
+- **Create** PID for data object or collection
+
+  ```
+  irule -F registerData.r "*path='/bobZone/home/bob/test.txt'"
+  DEBUG RegisterData: Create EPIC PID for /bobZone/home/bob/test.txt.
+  DEBUG RegisterData: Created 21.T12995/381cb850-dd7d-11eb-a862-00505684a77c for /bobZone/home/bob/test.txt
+  DEBUG RegisterData: EPIC PID lookup for /bobZone/home/bob/test.txt: 21.T12995/381cb850-dd7d-11eb-a862-00505684a77c.
+  ```
+
+  The rule will create an EPIC PID with the following profile:
+
+  ![PID-bob](figs/PID-bob.png)
+
+- **Resolving** of PIDs
+
+  Note, that iRODS paths are not actionable through HTTP(s). If you want an actionable URL you can direct the PID URL field to the davrods endpoint by setting the variable `*proto` accordingly:
+
+  ```
+  irule -F registerData.r "*path='/bobZone/home/bob/test.txt'" "*proto='https://scomp1446.wur.nl'"
+  ```
+
+  The resolving of the EPIC PID is now redirected to https://scomp1446.wur.nl/bobZone/home/bob/test.txt.
+
+- **Recursive** creation of PIDs
+
+  If you want to create PIDs for a collection recursively set the `*recursive` variable to true:
+
+  ```
+   irule -F registerData.r "*path='/bobZone/home/bob/registered'" "*proto='https://scomp1446.wurnet.nl'" "*recursive='true'"
+  ```
+
+#### Update EPIC PIDs
+
+- **Moving** registered data objects in iRODS
+
+  When data which carries a PID is moved, the iRODS path changes . Hence we need to update the URL field in the EPIC PID.
 

interactiveRules/pid-test-rules/deregisterData.r

+deregisterData{
+    # Removes a PID for *path and the iRODS metadata key=EPIC_PID, value=Handle
+    # If the input path is a collection and the recursive flag is set to true 
+    # all members of the collection will be checked.
+    #
+    # *path: full path do object or collection
+    # *recursive: apply to all memebers of a collection, ignored if path is an object
+    
+    msiGetObjType(*path, *objType);
+    if(*objType == "-c" && *recursive == "true"){
+        writeLine("stdout","DEBUG DeregisterData: Remove EPIC PID for *path and all its members.");
+        # deregister all data objects in the collection
+        foreach(*row in SELECT COLL_NAME, DATA_NAME where COLL_NAME like "*path"){
+	    *coll = *row.COLL_NAME;
+            *obj = *row.DATA_NAME;
+            *epic = isregistered("*coll/*obj", "-d");
+	    if(*epic != ""){ deregister("*coll/*obj", *epic, "-d"); }
+	}
+	# deregister all data objects in subcollections
+        foreach(*row in SELECT COLL_NAME, DATA_NAME where COLL_NAME like "*path/%"){
+            *coll = *row.COLL_NAME;
+            *obj = *row.DATA_NAME;
+            *epic = isregistered("*coll/*obj", "-d");
+	    if(*epic != ""){ deregister("*coll/*obj", *epic, "-d"); }
+        }
+	# deregister all subcollections
+        foreach(*row in SELECT COLL_NAME where COLL_NAME like "*path/%"){
+            *coll = *row.COLL_NAME;
+            *epic = isregistered(*coll, "-c");
+	    if(*epic != ""){ deregister("*coll", *epic, "-c"); }
+	}
+	# deregister the collection itself
+        *epic = isregistered(*path, *objType);
+	if(*epic != ""){ deregister("*coll", *epic, "-c"); }
+    }
+    else{
+        writeLine("stdout","DEBUG DeregisterData: Remove EPIC PID for *path.");
+        *epic = isregistered(*path, *objType);
+	if(*epic != ""){ deregister(*path, *epic, *objType); }
+    }
+}
+
+#Helper functions
+
+deregister(*path, *epic, *objType){
+   msiString2KeyValPair("EPIC_PID=*epic",*Keyval);
+   msiRemoveKeyValuePairsFromObj(*Keyval, *path, *objType);
+   msiDeleteEpicPID(*epic, *out);
+   writeLine("stdout", "DEBUG DeregisterData: *epic remove status *out");
+}
+
+isregistered(*path, *objType){
+    # Checks if EPIC PID for *path is known in the iRODS metadata, key=EPIC_PID.
+    # Returns the EPIC PID or "".
+    *epic = "";
+    if(*objType == "-d"){
+        msiSplitPath(*path, *coll, *obj);
+        foreach(*row in SELECT META_DATA_ATTR_VALUE where META_DATA_ATTR_NAME = 'EPIC_PID' and COLL_NAME = '*coll' and DATA_NAME = '*obj'){ 
+            *epic = *row.META_DATA_ATTR_VALUE;
+	}
+    }
+    if(*objType == '-c'){
+        foreach(*row in SELECT META_COLL_ATTR_VALUE where META_COLL_ATTR_NAME == "EPIC_PID" and COLL_NAME == "*path"){
+            *epic = *row.META_COLL_ATTR_VALUE;
+	}
+    }
+    *epic;
+} 
+
+input *path='/<ZONE>/home/<user>/<obj or coll>',*recursive='false'
+output ruleExecOut

interactiveRules/pid-test-rules/registerData.r

@@ -16,12 +16,13 @@ registerData{
 	    *epic = isregistered("*coll/*obj", "-d");
 	    if(*epic == ""){
 	        writeLine("stdout","DEBUG RegisterData: Create EPIC PID for *coll/*obj.");
-                if(*davrods == ""){register("*coll/*obj", "irods:", "-d");}
-                else{register("coll/*obj", *davrods, "-d");}
+                register("*coll/*obj", *proto, "-d");
                 *epic = isregistered("*coll/*obj", "-d");
-                writeLine("stdout",
-                          "DEBUG RegisterData: EPIC PID lookup for *coll/*obj: *epic.");
+
 	    }
+            writeLine("stdout",
+                      "DEBUG RegisterData: EPIC PID lookup for *coll/*obj: *epic.");
+
 	}
         # register all data objects in subcollections
 	foreach(*row in SELECT COLL_NAME, DATA_NAME where COLL_NAME like "*path/%"){
@@ -30,12 +31,12 @@ registerData{
             *epic = isregistered("*coll/*obj", "-d");
             if(*epic == ""){
                 writeLine("stdout","DEBUG RegisterData: Create EPIC PID for *coll/*obj.");
-                if(*davrods == ""){register("*coll/*obj", "irods:", "-d");}
-                else{register("coll/*obj", *davrods, "-d");}
-                *epic = isregistered("*coll/*obj", "-d");
-                writeLine("stdout",
-                          "DEBUG RegisterData: EPIC PID lookup for *coll/*obj: *epic.");
+                register("*coll/*obj", *proto, "-d");
+		*epic = isregistered("*coll/*obj", "-d");
             }
+            writeLine("stdout",
+                      "DEBUG RegisterData: EPIC PID lookup for *coll/*obj: *epic.");
+
         }
 	# register all subcollections
         foreach(*row in SELECT COLL_NAME where COLL_NAME like "*path/%"){
@@ -43,21 +44,19 @@ registerData{
             *epic = isregistered(*coll, "-c");
             if(*epic == ""){
                 writeLine("stdout","DEBUG RegisterData: Create EPIC PID for *coll.");
-                if(*davrods == ""){register(*coll, "irods:", "-c");}
-                else{register(*coll, *davrods, "-c");}
+                register(*coll, *proto, "-c");
                 *epic = isregistered(*coll, "-c");
-                writeLine("stdout",
-                          "DEBUG RegisterData: EPIC PID lookup for *coll: *epic.");
             }
+	    writeLine("stdout",
+                      "DEBUG RegisterData: EPIC PID lookup for *coll/*obj: *epic.");
         }
 	# register the collection itself
 	*epic = isregistered(*path, *objType);
         if(*epic == ""){
             writeLine("stdout","DEBUG RegisterData: Create EPIC PID for *path.");
-            if(*davrods == ""){register(*path, "irods:", *objType);}
-            else{register(*path, *davrods, *objType);}
+            register(*path, *proto, *objType);
+	    *epic = isregistered(*path, *objType);
         }
-        *epic = isregistered(*path, *objType);
         writeLine("stdout",
                   "DEBUG RegisterData: EPIC PID lookup for *path: *epic.");
     }
@@ -65,8 +64,7 @@ registerData{
         *epic = isregistered(*path, *objType);
 	if(*epic == ""){
             writeLine("stdout","DEBUG RegisterData: Create EPIC PID for *path.");
-	    if(*davrods == ""){register(*path, "irods:", *objType);}
-	    else{register(*path, *davrods, *objType);}
+	    register(*path, *proto, *objType);
 	}
 	*epic = isregistered(*path, *objType);
 	writeLine("stdout",
@@ -75,12 +73,12 @@ registerData{
 }
 
 #Helper functions
-
 register(*path, *endpoint, *objType){
 
     msiExecCmd("uuid","","","","",*createUuid);
     msiGetStdoutInExecCmdOut(*createUuid,*uuid);
-    msiCreateEpicPID(*uuid, "*endpoint/*path", *handle, *code);
+    msiCreateEpicPID(*uuid, "*endpoint*path", *handle, *code);
+    addPIDProfile(*handle, *path);
     if(*code == "201"){
         writeLine("stdout", "DEBUG RegisterData: Created *handle for *path");
         msiAddKeyVal(*Keyval,"EPIC_PID", *handle);
@@ -110,5 +108,12 @@ isregistered(*path, *objType){
     *epic;
 } 
 
-input *path='/bobZone/home/bob/registered',*recursive='true',*davrods=""
+addPIDProfile(*handle, *path){
+    msiUpdateEpicPID(*handle, "IRODS_SERVER", "scomp1448.wurnet.nl", *out);
+    msiUpdateEpicPID(*handle, "IRODS_ZONE", "bobZone", *out);
+    msiUpdateEpicPID(*handle, "IRODS_PORT", "1247", *out);
+    msiUpdateEpicPID(*handle, "IRODS_PATH", *path, *out);
+}
+
+input *path='/<zone>/home/<user>/<obj or coll>',*recursive='false',*proto='irods:'
 output ruleExecOut