Writing plugins
You can write plugin programs as a script file using Python, Bravura Security’s PSLang scripting language, or as an executable.
There are libraries provided to help create plugin programs in Python. Run <instance>\instance.bat to set the library paths required for using these libraries in Windows command line consoles.
The plugin script file or executable file must be located in the plugin directory. Input/output is passed in as plain text, in KVGroup format.
See also
For general information about the use of KVGroups, including syntax, see KVGroups.
For more information about PSLang, see the PSLang Manual (pslang.pdf)
To learn how to set options for running PSLang scripts, see Controlling plugin processes
Request data
Input protocol for plugins commonly includes a "request" inner KVGroup that contains details of a request:
"request" "" = {
"certifier" = "<profile ID of reviewer>" #Certification campaign
"certround" "" = {
# If the request results from a certification campaign.
# Empty otherwise.
"certround" = "<certification campaign ID>"
"description" = "<certification campaign description>"
"endDate" = "<seconds since epoch>" # or 0
"startDate" = "<seconds since epoch>
"termby" = ""
}
"entryDate" = "<seconds since the epoch>"
"macroStatus" = "<status of the request>"
# One of the following codes:
# N -- Request initiated
# O -- Needs authorization
# A -- Approved
# D -- Denied
# E -- Profile ID is denied
# G -- Canceled
# c -- Approved, performing requested operations
# C -- Processed
# H -- On hold pending administrator intervention
# W -- Scheduled for later
# U -- Request unposted
# d -- Confirming delete
"notes" = "<notes entered by the requester in initial request>"
"batchauthnote" = "<authorization note for batch>"
"prequest" = "<pre-defined request ID>"
# If the request originated as a pre-defined request.
# Empty otherwise.
"reason" = "<reason filled in by idwfm service for finalization>"
# As this is always run before finalization, reason will always
# be empty.
"recipient" = "<recipient's Profile ID>"
"recipientEmail" = "<email address of the recipient>"
"requester" = "<requester's Profile ID>"
"requesterEmail" = "<requester's email>"
"requesterName" = "<requester's full name>"
"requestID" = "<request ID>"
# For auditing purposes.
# This is included in email messages and
# CGI web pages.
"requestModule" = "<report used to submit the request>"
"segment" = "" #Certification campaign segment
"reservationid" = "" #output by attribute validation and idm-suite id plugins
"authorizer" "<authorizer's current Profile ID>" = {
"authorizerRenamedFrom" = "<authorizer's old Profile ID>"
"actualAuthorizer" = "<Profile ID of authorizer who responded>"
# This might be empty if there is no response yet.
"reason" = "<reason given by authorizer who responded>"
"remindersSent" = "<number of reminders sent to the authorizer>"
"starttime" = "<hextime>"
"status" = "<status set by authorizer for this request>"
# Can be:
# "O" -- open (no response)
# "A" -- approved
# "D" -- denied
# "I" -- irrelevant
# When a request needs 1 of 3 authorizers to approve and one does,
# the other two are set to "irrelevant" since their answer
# (approve or deny) is not required any more.
"resource" = "<resource that the authorizer is in charge of>" = { # 1 or more
# If IDP APPROVE SINGLE RESOURCE is enabled:
"status" = "<O|A|D|I>" # See notes below.
"reason" = "<reason given by authorizer>"
"authauthnote" = "<authorization note for authorizer>"
}
} # 0 or more authorizers
"implementer" "<profile ID>" = {
"remindersSent" = "0" # Number of email reminders sent
"resource" = "<resource ID>" # Resource to be implemented
"status" = "O" # Task status
} # For each implementer/resource pair, a KVGroup is included
"attribute" "<attribute ID>" ={
# Include only profile and request attributes that have been changed in
# the request.
"oldValue" "" = { # included if the value has changed
# (attribute validation / request rewrite)
"value" = "<old value>" # 0 or more values can be listed
}
"value" "" = {
"value" = "<current value>" # 0 or more values can be listed
}
} # 0 or more attributes
"resource" "<resource identifier>" = {
"authorizationsReceived" = "<number of approvals received>"
#Deny actions are not counted here.
"authorizationsRequired" = "<number of authorizations required>"
"authorizer" = "<authorizers for this resource>" # 0 or more
"acctauthnote" = "<authorization note for resource>"
"autoselect" = "<none|mandatory|optional>"
# Auto selection can be:
# none -- Selected manually by the requester
# mandatory -- Forced selection by IDWFM REQUEST REWRITE PLUGIN
# optional -- Optionally selected by IDWFM REQUEST REWRITE PLUGIN
"enact" = "true|false"
# When used with the WORKFLOW VIEW MODIFICATION plugin, this key
# can be used for displaying or hiding information about resources;
# for example, set to false for resources that won't actually be
# deleted.
"finalized" = "<true|false>"
# All attached resources are not finalized by default. By
# default, resource operations wait for the request to be
# decided (all authorizations received) on all resources. This
# can be overridden by IDSYNCH AUTH CRITERIA MOD PLUGIN
"groupApproval" = "00000000-0000-0000-0000-000000000000"
# Used to approve a group of resources only if all
# approvals are received for the group of resources
# by the IDWFM REQUEST REWRITE PLUGIN.
"implementer" = "<profile ID>" # a key-value for each implementer that can fulfill the task
"implicit" = "<true|false>" # If true, this is selected as part of role
# definition.
# If false, this is selected by the
# requester.
"notes" = "" # empty - only filled in upon provisioning
"operation" = "<opcode>"
# Operation requested, can be:
# "CFYU" -- Certify user
# "CFYA" -- Certify account
# "CFYG" -- Certify group membership
# "CFYP" -- Certify application
# "CFYM" -- Certify group members
# "ACUA" -- Account user add
# "RLUA" -- Role user add
# "UPDT" -- Update account
# "DELU" -- Delete user
# "DELR" -- Remove a user from a role
# "RENU" -- Rename account
# "RPRO" -- Rename profile
# "MVCU" -- Move user from one context to another
# "ENAU" -- Enable user
# "DNAU" -- Disable user
# "GRUA" -- Add a user to a group
# "GRUD" -- Remove a user from a group
# "GROA" -- Add an owner to a group
# "GROD" -- Remove an owner from a group
# "CRTG" -- Create group
# "DELG" -- Delete group
# "LUPD" -- Associate account with profile
# "LDEL" -- Remove account association
# "ORGADDSUB" -- Attach user
# "ORGDELSUB" -- Detach user
# "ORGTFRSUB" -- Transfer user
# "ORGADDMGR" -- Designate manager
# "ORGDELMGR" -- Designate non-manager
"parentRole" = "<role ID for the role this resource is related to>"
"password" = "<new password>"
# Optionally set the plain text password for
# the resource by IDWFM REQUEST REWRITE PLUGIN
"pseudoData" = "<Data for replacement in pseudoTag>"
"pseudoOp" = "true|false" #Is this a pseudo Operation?
# If true, this operation is NOT handled by idtm
"pseudoTag" = "<m4 tag for display in the GUI>"
"reason" = "<reason for the resource being part of the request>"
"result" = "<status of the resource>"
# can be:
# "O" -- open
# "A" -- approved
# "D" -- denied
# "I" -- irrelevant
"itemType" = "<item type>"
# Can be:
# "template"
# "role"
# "groupID"
# "accountID"
# "subordinate" for OrgChart operations
# "networkResource" for folder/shares and other resource
<item type KVGroups or key-values>
# Depending on the item type, there are key-values or KVGroups
# as described below.
"phase" "<phase number>" = {
"authorizer" = "<profile id>" # 1 or more authorizers
} # 1 or more phases
# The following is only relevant for BravuraPrivilege
"managed_system_policies" "" = {
"msp" = "<managed system policy>" # 1 or more msps
}
"primaryMsp" = "<managed system policy>" # primary managed system policy
}# 1 or more resources
}"
The following additional information will be added to the "resource" KVG group depending on the itemType.
role will include the following:
"role" = "<role ID>"
template will include the following:
"template" = "<template ID>" "targetid" = "<target ID>"
For a rename account (RENU) includes:
"template" = "<new account ID>" "userid" = "<current profile ID>" "targetid" = "<target ID for the old account ID>" "accountID" = "<old account ID>"
For a rename profile (RPRO) includes:
"template" = "<new account ID>" "userid" = "<current profile ID>"
accountID will include the following:
For updating a user’s profile, or enable, disable, delete, or move an account:
"accountID" = "<long ID>" "targetid" = "<target ID>"
For an account association (LUPD):
"targetid" = "<target ID>" "accountID" = "<long ID>" "userid" = "<profile ID>"
For an account association (LDEL):
"targetid" = "<target ID>" "accountID" = "<long ID>"
groupID will include the following:
When using a group long ID:
"template|accountID" = "<template ID|long ID>" "targetid" = "<target ID>" "groupID" = "<group long ID>"
When using a group short ID:
"template|accountID" = "<template ID|long ID>" "targetid" = "<target ID>" "groupshortid" = "<group short ID>"
networkResource will include the following:
"template" = "<template ID>" "templateuri" = "<template URI>" "targetid" = "<network resource target ID>" "resourceaddress" = "<target URI>" "resourcetype" = "<folder|share>"
subordinate will include the following for requests related to the OrgChart:
"manager" = "<manager profile ID>" "subordinate" = "<subordinate profile ID>" "newmanager" = "<new manager profile ID>" # only needed for ORGTFRSUB operation
The "resource" KVGroup may include additional groups. If a resource is part of a role, the KVGroup includes the key-value pair of "parentRole" with the value set to the Role ID.
Optional resource detail KVGroups
If the PLUGIN DATA REQUEST RESOURCE DETAILS setting is enabled in the Workflow > Options > Plugins menu, resource key-value sub-groups are included.
The optional detailed input for a role request includes:
"role" "" = {
"roleid" = "<role ID>"
"desc" = "<role description>"
}The optional detailed input for a template request includes:
"template" "" = {
"description" = "<template description>"
"hostid" = "<target ID>"
"id" = "<template ID>"
"location" = "<location associated with template>"
"longid" = "<target account ID>"
"modby" = "<last modified by>"
"numberOfAuthorizers" = "<number of associated authorizers>"
"type" = "<type associated with template>"
} The optional detailed input for an account request includes:
"account" "" = {
"associated" = "<TRUE|FALSE>" # Target configuration flag
"helpdesk" = "<TRUE|FALSE>" # Target configuration flag
"hostid" = "<target ID>"
"invalid" = "<TRUE|FALSE>" # False if the account is not valid.
"list" = "<TRUE|FALSE>" # Target configuration flag
"longid" = "<target account long ID>"
"modby" = "<last modified by>"
"shortid" = "<target account short ID>"
"user" = "<TRUE|FALSE>" # Target configuration flag
"userid" = "<Profile ID associated>"
} The optional detailed input for a group request includes:
"nosgroup" "" = {
"addtype" = "<MODR|OPEN|SUBS>"
"deltype" = "<MODR|OPEN|SUBS>"
"groupid" = "<long ID of the group>"
"hostid" = "<target ID>"
"location" = "<location associated with nosgroup>"
"mgrpid" = "<MANAGEGRP.MGRPID>"
"subgrpid" = "<MANAGEGRP.SUBGROUPID>"
"type" = "<type associated with group>"
}
# followed by template or account KVGroup When the operation is related to the OrgChart, the optional detailed input for a request includes:
"<subordinate|manager>" "user" = {
"id" = "<profile ID>"
"name" = "<profile full name>"
"account" "" = {
...
} # 1 or more; Accounts are listed for each associated with the subordinate.
"attribute" "<attribute ID>" = {
"value" "" = {
"value" = "<attribute value>" # 0 or more
} # Only one per attribute
} # O or more; Profile and request attributes of the subordinate are listed.
} User data
Input protocol for plugins commonly includes one or more of the following inner KVGroups:
"requester" "admin—user" which describes the user whose action caused the plug-on to run.
"recipient" "user" which describes the recipient of the action, if there is one. This is a user whose profile is being managed.
"viewer" "user" which describes the viewer of the action, if there is one; for example, an authorizer reviewing a request.
"model" "user" which describes the model user used in profile comparison, if there is one.
It is possible for the requester, recipient, and viewer to be the same user.
The product administrator KVGroups
Following is the syntax for requester KVGroup input for a product administrator using the Manage the system (PSA) module:
"requester" "admin" = {
"ACL" "" = {<rights list>}
"ID" = "<adminID>"
"MODBY" = "<admin.modby>" # The last user to modify this user
"NAME" = "<Full name of the user>"
} For example:
"requester" "admin" = {
"ACL" "" = {
"superuser" = ""
}
"ID" = "superuser"
"MODBY" = ""
"NAME" = "superuser"
} See Administrative privileges for keywords to include in the ACL rights list.
The regular user KVGroups
Following is the syntax for KVGroup input for a regular user as requester or viewer:
"<requester|recipient|viewer>" "user" = {
"ID" = "<profile ID>"
"NAME" = "<user alias>"
} # 1 or more
} "
For example:
"requester" "user" = {
"ID" = "crysta.soria"
"NAME" = "Crysta Soria"
}
} Optional user attribute, account and role detail KVGroups
If the PLUGIN DATA USER ATTRIBUTE DETAILS setting is enabled in the Workflow > Options > Plugins menu, regular user KVGroups include a list of all the user’s profile and request attributes and their values. Each attribute key has the corresponding attribute ID as the name.
Each attribute KVGroup contains a "value" KVGroup. The value KVGroup contains zero or more "value" key-value pairs. Each key-value represents a single distinct value of the attribute. Multiple key-values represent multiple values of the attribute.
"attribute" "<attribute ID>" = {
"value" "" = {
"value" = "<value>" # 0 or more
}
} If the PLUGIN DATA USER ROLE DETAILS setting is enabled in the Workflow > Options > Plugins menu, regular user KVGroups include a key-value pairs list of all the user’s currently assigned roles.
"role" = "<role ID>" # 0 or more
If the PLUGIN DATA USER ACCOUNT DETAILS setting is enabled in the Workflow > Options > Plugins menu, regular user KVGroups include a list of all the user’s accounts.
"account" "" = {
"associated" = "<TRUE|FALSE>"
"helpdesk" = "<TRUE|FALSE>"
"hostid" = "<target ID>"
"invalid" = "<TRUE|FALSE>"
"longid" = "<long ID>"
"list" = "<TRUE|FALSE>"
"modby" = ""
"shortid" = "<short ID>"
"user" = "<TRUE|FALSE>"
"userid" = "<profile ID>"
} # 1 or more Navigation data
Input protocol for plugins commonly includes a "navigation" inner KVGroup that contains details of the end user navigation:
"navigation" "" = {
"button" = "<button name>"
# Button that was pressed prior to plugin being executed
"jump" = "<link>"
# Link that was followed prior to the plugin being executed
"attrgroup" = "<attribute group id>"
# Passed in when modifying attributes in an attribute on a subsidiary page
"managedresource" = "<managed resource id>"
# Set when using Group Manager
"prequest" = "<predefined request id>"
# Set after selecting a pre-defined request
"roleid" = "<role id>"
# Set when selecting optional members of a role
"targetid" = "<target id>"
# Set when selecting groups to add to a request for a specific target
"wfpage" = "<page>"
# Set on every page
# Possible values:
# - attrs
# - createaccount
# - groupselectionchange
# - groupselectionfull
# - idpattrsubsid
# - idprequestlong
# - idprequestshort
# - idrattrsubsid
# - idsattrsubsid
# - idsrequestlong
# - idsrequestshort
# - idvattrsubsid
# - idvrequestlong
# - jump
# - listrolesandtemplates
# - psaattrsubsid
# - pswattrsubsid
# - rbacvariances
# - requestsubmit
# - requestsubmitdeleteaccount
# - requestsubmitdeleterole
# - requestsubmitdisableaccount
# - requestsubmitenableaccount
# - requestsubmitgroupchange
# - requestsubmitmove
# - requestsubmitpredefinedrequest
# - requestsubmitrenameaccount
# - requestsubmitreplacerole
# - requestsubmitupdateaccounts
# - selectmanagedgroup
# - selectmanagedresource
# - selectmoveaccounts
# - selectoptionalrolemembers
# - selectpredefinedrequest
# - selectrenameaccounts
# - selectrole
# - selecttemplate
# - sodviolations
# - userinfo
}