Among the items I’d been working on for the presentation at the DCLUG earlier this month was an evaluator’s page.
Now before I get into the code snippet, let me lay out a bit more of the design concept to put this in context. Users would anonymously create grant requests via browser, then internal users would assign evaluators with their Notes clients, and those evaluators would login via browser to fill out their assessments of the requests. So, I needed to come up with a way to force the logins and inhibit anyone who wasn’t authorized from seeing the evaluators work lists or assessments.
Notes does this wonderfully well, but as I’m breaking new ground with XPages, I had to search around for clues on how to do it. After a while, I did finally find something on my go-to source, Stack Overflow. (Thanks to Matt White and AndrewGra!)
<xp:this.acl> <xp:acl> <xp:this.entries> <xp:aclEntry type="ANONYMOUS" right="READER"></xp:aclEntry> <xp:aclEntry type="DEFAULT" right="EDITOR"></xp:aclEntry> </xp:this.entries> </xp:acl> </xp:this.acl>
While this is nice, it also opened me to wondering about all the other options of the aclEntry control. There are 5 parameters to be considered. The two required parameters are intriguing.
type – string – Defines type of entry, valid values are USER, GROUP, ROLE, ORGUNIT, ORGROLE, DEFAULT, ANONYMOUS
While both ORGUNIT and ORGROLE are deprecated, the other 5 are quite familiar. If you set type to either DEFAULT or ANONYMOUS, you don’t supply any of the name values, since these are effectively “unnamed” access types. For USER, GROUP and ROLE, you must supply name values.
right – string – Defines rights for this entry, valid values are NOACCESS, READER, EDITOR
On an XPage, you really are only concerned about end-user access, so it’s either none, reading or editing. Distinguishing between Author and Editor depends on the ACL and whether their are Author names fields on the source documents, so not something one wants the XPage monkeying around in anyway.
Since neither DEFAULT nor ANONYMOUS requires any name information, the next two parameters are optional.
fullName – string – Defines users full name e.g. John Smith
name – string – Defines entry name
There’s a real lack of clarity here as to what goes where, in particular, what to do about ROLES. Is it a name or a fullName. Do you use brackets [ ] or just the text? So, I fiddled around. I’d almost figured out how to implement ROLES myself when I searched just a bit more and found Russ Maher’s guidance. Basically, put brackets around the name value and straight text for the fullName. Here’s my ACL to limit the XPage to only those users with the Evaluator role.
<xp:this.acl> <xp:acl> <xp:this.entries> <xp:aclEntry type="ANONYMOUS" right="NOACCESS"></xp:aclEntry> <xp:aclEntry type="DEFAULT" right="NOACCESS"></xp:aclEntry> <xp:aclEntry fullName="Evaluator" right="EDITOR" type="ROLE" name="[Evaluator]"> </xp:aclEntry> </xp:this.entries> </xp:acl> </xp:this.acl>
The final parameter is also optional.
loaded – boolean – Specifies whether or not the tag instance should be created when the page is loading. Value defaults to ‘true’.
This one is obviously for people far more clever than I. I suppose that if you want the ACL to only take effect after some other event that trips the loaded flag to true or something. I’m not real sure. It is inherited from com.ibm.xsp.BaseComplexType if that helps you figure it out.
Just as form access and creation controls are very sneaky, these are as well. Since the properties don’t show up in the nice little properties box for the XPage and you have to hunt into either the source or the All Properties tab (under data), they are sure to create some trouble-shooting issues, especially when you’re new to XPages. So, I’d recommend you make sure to put these at the top of your XPages and I would be careful about using them on custom controls, unless you do everything in your custom controls, simply because of the lack of visibility.
Hope that helps someone looking for help with security in their XPages. I’m pretty happy with how easy it turned out to be to code it.