BHOLD Developer Reference

Article
10/02/2014

Introduction

The BHOLD-core module can process script commands. This can be done by directly using the bscript.dll in a .NET project or by interacting with the web service, b1scriptservice.asmx. This document describes how the script engine of the BHOLD-core module can be used.

Before a script is executed, all the information inside the script should be collected in order to compose this script. This information can be gathered from the following sources:

User input
BHOLD data
Applications
Other

The BHOLD data can be retrieved using the GetInfo function of the script object. There is a complete list of commands that can present all data stored in the BHOLD database. However, the data presented is subject to the view permissions of the user logged in. The result will be in the form of an XML document that can be parsed.

Another source for information can be one of the applications that are controlled by BHOLD. The application snap-in has a special function, the FunctionDispatch, which can be used to present application specific information. This information will be presented as an XML document as well.

Finally, if there is no other way, the script can contain commands directly to other applications or systems. Note that the installation of extra software on the BHOLD server can undermine the security of the whole system.

All this information is put into one XML document and assigned to the BHOLD script object. The object combines this document with a pre-defined function. The pre-defined function is an XSL document that will translate the script input document into a BHOLD command document.

The commands will be executed in the same order as in the document. If one function fails, all commands executed will be rolled back.

Bhold Script Processing

Script Object

All information from, and commands to the BHOLD system will be sent via the bscript object. This object is accessible through the bscript.dll that is found in the %Program Files(x86)%/BHOLD directory. The object offers functions to:

Retrieve information from the BHOLD authorization model
Retrieve custom information from an application
Execute scripts

Retrieve BHOLD information

The GetInfo function is used to retrieve information from the available data in the BHOLD authorization system. The function requires a function name and eventually one or more parameters. If this function succeeds, a BHOLD object or collection will be returned in the form of an XML document.

If the function does not succeed, the GetInfo function returns an empty string or an error. The error description and number can be used to get more information about the failure.

The GetInfo function ‘FunctionDispatch’ can be used to retrieve information from an application controlled by the BHOLD system. This function requires three parameters: The ID of the application, the dispatch function as it is defined in the ASI, and an XML document with supporting information for the ASI. If the function succeeds, the result will be available in XML format in the result object.

The following is an simple C# example of GetInfo:

ScriptProcessor myScriptProcessor = new ScriptProcessor();
myScriptProcessor.Initializae(“CORP\\b1user”);
myScriptProcessor.GetInfo(“orgunit”, “1”);

Likewise, the bscript object can also be accessed via it web service b1scriptservice. This is done by adding a web reference to you project using http://<server>:5151/BHOLD/Core/b1scriptservice.asmx where <server> is the server with the BHOLD binaries installed. For information on adding a web service reference to a visual studio project see Adding and Removing Web References. The following is an example of GetInfo using the web service. This code retrieves the Organizational Unit that has an OrgID of 1 and then displays the name of that Organizational Unit on the screen.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Xml;

namespace bhold_console
{
    class Program
    {
        static void Main(string[] args)
        {
             var bholdService = new BHOLDCORE.B1ScriptService();
             bholdService.Url = "http://app1.corp.contoso.com:5151/BHOLD/Core/b1scriptservice.asmx";
             string orgname= "";

             if (args.Length == 3)
             {
                 //Use explicit credentials from command line
                 bholdService.UseDefaultCredentials = false;
                 bholdService.Credentials = new System.Net.NetworkCredential(args[0], args[1], args[2]);
                 bholdService.PreAuthenticate = true;
             }
             else
             {
                 bholdService.UseDefaultCredentials = true;
                 bholdService.PreAuthenticate = true;
             }

             //Load BHOLD information into an xml document and loop through document to find the bholdDescription value
             var myOrgUnit = new System.Xml.XmlDocument();
             myOrgUnit.LoadXml(bholdService.GetInfo("orgunit","1","","");

            XmlNodeList myList = myOrgUnit.SelectNodes(("//item");

            foreach (XmlNode myNode in myList)
            {
                for (int i = 0; i < myNode.ChildNodes.Count; i++)
                {
                    if (myNode.ChildNodes[i].InnerText.ToString() == "bholdDescription")
                    {
                        orgname = myNode.ChildNodes[i + 1].InnerText.ToString();
                    }
                }
            }
            
            System.Console.WriteLine("The Organizational Unit Name is: " + orgname);

        }
    }
}

The following is a vbscript example using the web service via SOAP and using GetInfo. For additional examples for SOAP 1.1, SOAP 1.2, and HTTP POST see the BHOLD Managed Reference section or you can navigate to the web service directly from a browser and view them there.

Dim SOAPRequest
Dim SOAPParameters
Dim SOAPResponse
Dim xmlhttp

Set xmlhttp = CreateObject("Microsoft.XMLHTTP")

xmlhttp.open "POST", "http://app1.corp.contoso.com:5151/BHOLD/Core/b1scriptservice.asmx", False, "CORP\Administrator", "abc123*2k"

xmlhttp.setRequestHeader "Content-type", "text/xml; charset=utf-8"
xmlhttp.setRequestHeader "SOAPAction", "http://B1/B1ScriptService/GetInfo"

SOAPRequest = "<?xml version='1.0' encoding='utf-8'?> <soap:Envelope" & vbCRLF
SOAPRequest = SOAPRequest & " xmlns:xsi=""http://" & vbCRLF
SOAPRequest = SOAPRequest & " www.w3.org/2001/XMLSchema-instance""" & vbCRLF
SOAPRequest = SOAPRequest & " xmlns:xsd=""http://www.w3.org/2001/XMLSchema""" & vbCRLF
SOAPRequest = SOAPRequest & " xmlns:soap=""https://schemas.xmlsoap.org/soap/envelope/"">" & vbCRLF
SOAPRequest = SOAPRequest & " <soap:Body>" & vbCRLF
SOAPRequest = SOAPRequest & " <GetInfo http://B1/B1ScriptService"">" & vbCRLF
SOAPRequest = SOAPRequest & " <functionName>orgunit</functionName>" & vbCRLF
SOAPRequest = SOAPRequest & " <parameter1>1</parameter1>" & vbCRLF
SOAPRequest = SOAPRequest & " <parameter2></parameter2>" & vbCRLF
SOAPRequest = SOAPRequest & " <parameter3></parameter3>" & vbCRLF
SOAPRequest = SOAPRequest & " </GetInfo>" & vbCRLF
SOAPRequest = SOAPRequest & " </soap:Body>" & vbCRLF
SOAPRequest = SOAPRequest & " </soap:Envelope>"
MsgBox SOAPRequest

xmlhttp.send SOAPRequest 

SOAPResponse = xmlhttp.responseText

MsgBox SOAPResponse

Execute scripts

The ExecuteScript function of the bscript object can be used to execute scripts. This function requires two parameters. The first parameter is the XML document that contains the custom information to be used by the script. The second parameter is the name of the predefined script to be used. In the BHOLD predefined scripts directory there should be an XSL document with the same name as the function, but with the .xsl extension.

If the function does not succeed, the ExecuteScript function returns the value False. The error description and number can be used to know what went wrong. The following is an example of using the ExecuteXML web method. This method invokes ExecuteScript.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace Sample
{
    class Program
    {
        static void Main(string[] args)
        {
            var bholdService = new BHOLDCORE.B1ScriptService();
            bholdService.Url = "http://app1.corp.contoso.com:5151/BHOLD/Core/b1scriptservice.asmx";

            if (args.Length == 3)
            {
                //Use explicit credentials from command line
                bholdService.UseDefaultCredentials = false;
                bholdService.Credentials = new System.Net.NetworkCredential(args[0], args[1], args[2]);
                bholdService.PreAuthenticate = true;
            }
            else
            {
                bholdService.UseDefaultCredentials = true;
                bholdService.PreAuthenticate = true;
            }
            System.Console.WriteLine( "Add user #3 to role #44, result: {0}", bholdService.ExecuteXml(roleAddUser("44", "3")) );
            System.Console.WriteLine("Add user D1 to role 'MR-OU2 No Users', result: {0}", bholdService.ExecuteXml(roleAddUser("MR-OU2 No Users", "D1")));
            
        }

        private static System.Xml.XmlNode roleAddUser(string roleId, string userId)
        {
            var script = new System.Xml.XmlDocument();
            script.LoadXml(string.Format("<functions>"
                                        +"  <function name='roleadduser' roleid='{0}' userid='{1}' />"
                                        +"</functions>",
                                        roleId,
                                        userId)
                           );
            return script.DocumentElement;

BholdScriptResult

This GetInfo function is available after the executescript function is executed. The function returns an XML formatted string which contains the complete execution report. The Script node contains the XML structure of the script executed.

For each function which fails during the execution of the script a Node Function is added with the nodes Name, ExecuteXML and Error.On the end of the document all generated ID’s are added.

Notice that only the functions which contain an error will be added. An error number of ‘0’ means that the function is not executed. In some cases there is no error raised, for example when linking a role to an orgunit. When the role already exists no error is raised.

<Bhold>
  <Script>
    <functions>
      <function name="orgunitadd" description="OrgUnit1" parentid="root" orgtypeid="root" return="@ID@"/>     
      <function name="roleaddorgunit" orgunitid="OrgUnit1" roleid="Role1_OrgUnit1" return="@ID@"/>      
    </functions>
  </Script>
  <Function>
    <Name>orgunitadd</Name>
    <ExecutedXML>
      <function name="orgunitadd" description="OrgUnit1" parentid="root" orgtypeid="root" return="@ID@"/>
    </ExecutedXML>
    <Error Number="5" Description="Violation of UNIQUE KEY constraint 'IX_OrgUnits'. Cannot insert duplicate key in object 'dbo.OrgUnits'.
The statement has been terminated."/>
  </Function>
  <Function>
    <Name>roleaddorgunit</Name>
    <ExecutedXML>
      <function name="roleaddorgunit" orgunitid="OrgUnit1" roleid="Role1_OrgUnit1" return="@ID@"/>
    </ExecutedXML>
    <Error Number="0" Description=""/>
  </Function>
  <IDS>
    <ID name="@ID@">35</ID>
  </IDS>
</Bhold>

ID parameters

ID parameters get a special treatment. Non-numeric values are used as search value for locating the corresponding entities in the BHOLD data store. When the search value is not unique the first entity that complies with the search value is returned.

To distinguish numeric search values from ID’s it is possible to use a prefix. When the first six characters of the search value equals ‘no_id:’ then these characters are stripped before the value is used for searching. SQL wildcard characters (%) may be used.

The following fields are used with the search value:

ID type	Search field
orgunitID	Description
roleID	Description
taskID	Description
userID	DefaultAlias

Script Access and Permissions

Server side code in the Active Server Pages will be used to execute the scripts. Therefore, access to the script means access to these pages. The BHOLD system will maintain information about the entry points of the custom pages. This information includes start page and function description (multiple language should be supported).

A user needs to be authorized in order to enter the custom pages and execute a script. Each entry point will be presented as a task. Each user that gained this task via a role or a unit will be able to execute the corresponding function.

A new function in the menu will present all the custom functions that can be executed by the user. Because a script can perform actions in the BHOLD system under an identity different from the user logged on, it is possible to give permission to perform one specific action without having supervision over any object. For instance, this could be very useful for an employee that is only allowed to enter new customers to the company. These scripts can also be used to create self-register pages.

Command Script

The command script contains a list of functions that will be executed by the BHOLD system. The list is written in an XML document that is conforms to the following definition:

Command script	<functions>functions</functions>
functions	function {function}
function	<function name=”functionName” functionParameters [return] ( /> \| > parameterList </ function>)
functionName	valid function name from tables below
functionParameters	{ functionParameter }
functionParameter	parameterName = “parameterValue”
parameterName	valid parameter name
parameterValue	@variable@ \| value
value	valid parameter value
parameterList	<parameters> {parameterItem} </parameters>
parameterItem	<parameter name=”parameterName”> parameterValue </parameter>
return	return=”@variable@”
variable	custom variable name

XML has a few translations of special characters. These characters are mentioned below.

XML	Character
&	&
<	<
>	>
"	“
'	‘

These characters can be used in identifiers although we recommend not to use these characters.

An example of a valid command document with three functions:

<functions>
<functionname=”OrgUnitAdd”
parentID=”34” 
description=”Acme Inc.”
orgtypeID=”5”
return=”@UnitID@” />
</function>
<function name=”UserAdd”
description=”John Doe”
alias=”jdoe”
languageID=”1”
orgunitID=”@UnitID@” />
<function name=”TaskAddFile”
taskID=”93”
path=”/customers/purchase”>
<parameters>
<parameter name=”history”> True</parameter>
</parameters>
</function>
</functions>

The function OrgUnitAdd stores the ID of the created unit in a variable called UnitID. This variable is used as input for the UserAdd function. The return value of this function is not used.The next paragraphs describe all the functions available, the required parameters and their return values.

Execute Functions

ABAAttributeRuleAdd

Create a new attribute rule on a specific attributetype, attribute rules can only be linked to one attribute type.

The specified attribute rule can be linked to all possible attribute types. Notice that an attribute rule must be part of an attribute rules set which must be linked to an object rules set.

Note that the RuleType can not be changed with the “ABAattributeruletypeupdate” command. Requires that the description of the attribute by unique.

Arguments	Type
Description	Text
RuleType	Specify the kind of attribute rule. Depending on the kind of the attribute rule type other arguments must be included. Valid rule type values are: “0”: Regular Expresion (add argument “value”) “1”: Value (add arguments “operator” and “value”) “2”: List of Values “3”: Range (add arguments “rangemin” and “rangemax”) “4”: Age (add arguments “operator” and “value”)
InvertResult	[“0”\|”1”\|”N”\|”Y”]
AttributeTypeID	Text
Optional Arguments
Operator (Mandatory if RuleType is 1 or 4)	Text Possible values: “=”, “<” or “>” Notice that xml tags need “>” (>) and “<” (<)
RangeMin (mandatory if ruletype is 3)	Number
RangeMax (mandatory if ruletype is 3)	Number
Value(Mandatory if RuleType is 0, 1 or 4)	Text A numeric value or an alphanumeric value
Return type	Type
AttributeRuleID	Text

applicationadd

Creates a new application, returns the ID of the new application.

Arguments	Type
description
machine
module
parameter
protocol
username
password
svroleID (optional)	If this argument is not present then a supervisor role of the current user is used.
Applicationaliasformula (optional)	The alias formula is used to create a alias for a user when it is assigned to a permission of the application. The alias is created if the user has not already an alias for this application. If no value is given the defaultalias of the user is used as alias for the application. The formula is formatted: [<<objecttype>>.<<nameofobjecttypeattribute>>(startindexoffset,length offset)]. The offset is optional. Only User and Application attributes could be used. Free text could be used. The reserved characters are ‘[‘ and ‘]’. Example: [Application.bholdDescription]\[User.bholdDefAlias(1,5)]”
Return type	Type
ID of the new application

AttributeSetValue

Sets the value of an attribute type connected to object type. Requires that the description of the object type and the attribute type are unique.

Arguments	Type
ObjectTypeID	Text
ObjectID	Text
AttributeTypeID	Text
Value	Text
Return type	Type

AttributeTypeAdd

Inserts a new attribute type / property type.

Arguments	Type
DataTypeID	Text
Description (=Identity)	Text The next reserved words can not be used: “a” “frm” “id” “usr” “bhold”
MaxLength	Number in [1,..,255]
ListOfValues (boolean)	[“0”\|”1”\|”N”\|”Y”]
DefaultValue	Text
Return type	Type
AttributeTypeID	Text

AttributeTypeSetAdd

Inserts a new attribute type set. Requires that the description of an attribute type set is unique.

Arguments	Type
Description (=Identity)	Text
Return type	Type
AttributeTypeSetID	Text

AttributeTypeSetAddAttributeType

Inserts a new attribute type in an existing attribute type set. Requires that the description of the attribute type set and attribute type are unique.

Arguments	Type
AttributeTypeSetID	Text
AttributeTypeID	Text
Order	Number
LocationID	Text. The location is either “group” or “single”.
Mandatory	[“0”\|”1”\|”N”\|”Y”]
Return type	Type

ObjectTypeAddAttributeTypeSet

Adds an attribute type set to an object type. Requires that the description of the object type and the attribute type set are unique and the object types are: System, OrgUnit, User, Task

Arguments	Type
ObjectTypeID	Text
AttributeTypeSetID	Text
Order	Number
Visible	“0“ The attribute type set is visible. “2” The attribute type set is visible when the ‘more info’ button is selected. “1” The attribute type set is invisible.
Return type	Type

orgunitadd

Creates a new organizational unit, returns the ID of the new organizational unit.

Arguments	Type
description
orgtypeID
parentID
orgunitinheritedroles (optional)
Return type	Type
ID of the new unit	The parameter orgunitinheritedroles has either the value yes or no.

orgunitaddsupervisor

Make a user a supervisor of an organizational unit.

Arguments	Type
svroleID	The argument userID can also be used. In this case the default supervisor role is selected. A default supervisor role has a name like __svrole followed by a number. The argument userID can be used for backwards compatibility.
orgunitID
Return type	Type

orgunitadduser

Make a user a member of an organizational unit.

Arguments	Type
userID
orgunitID
Return type	Type

orgunitdelete

Removes an organizational unit.

Arguments	Type
orgunitID
Return type	Type

orgunitdeleteuser

Removes a user as a member of an organizational unit.

Arguments	Type
userID
orgunitID
Return type	Type

roleadd

Creates a new role.

Arguments	Type
Description
svrole
svroleID (optional)	If this argument is not present then a supervisor role of the current user is used.
ContextAdaptable (optional)	[“0”,”1”,”N”,”Y”]
MaxPermissions(optional)	Integer
MaxRoles(optional)	Integer
MaxUsers(optional)	Integer
Return type	Type
ID of the new role

roleaddorgunit

Assigns a role to an organizational unit.

Arguments	Type
orgunitID
roleID
inheritThisRole	‘true’ or ‘false’, indicates whether the role will be propsed to underlying units.
Return type	Type

roleaddrole

Assigns a role as a sub-role of another role.

Arguments	Type
roleID
subRoleID
Return type	Type

roleaddsupervisor

Make a user a supervisor of a role.

Arguments	Type
svroleID	The argument userID can also be used. In this case the default supervisor role is selected. A default supervisor role has a name like __svrole followed by a number. The argument userID can be used for backwards compatibility.
roleID
Return type	Type

roleadduser

Assigns a role to a user. The role cannot be a context adaptable role when no contextID is given.

Arguments	Type
userID
roleID
durationType	Optional, can contain values ‘free’, ‘hours’, ‘days’
durationLength	Optional. Required when durationType is ‘hours’ or ‘days’, should contain the integer value for the number of hours or days that the role will be assigned to a user.
start	Optional. Date and time when the role will be assigned. When this attribute is omitted, the role will be assigned immediately. Date format is ‘YYYY-MM-DDThh:nn:ss”, where only year, month and day are required. E.g. “2004-12-11” and “2004-11-28T08:00” are valid values.
end	Optional. Date and time when the role will be revoked. When durationType and durationLength are given, this value will be ignored. Date format is ‘YYYY-MM-DDThh:nn:ss”, where only year, month and day are required. E.g. “2004-12-11” and “2004-11-28T08:00” are valid values.
linkreason	Required when start, end or duration is given, otherwise ignored.
contextId	Optional. Id of the organizational unit, only required for context adaptable roles.
Return type	Type

roledelete

Deletes a role.

Arguments	Type
roleID
Return type	Type

roledeleteuser

Removes role assignment to a user. Inherited roles by the user are revoked by this command.

Arguments	Type
userID
roleID
contextID	Optional
Return type	Type

roleproposeorgunit

Proposes a role to assign it to the members and the sub-orgunits of an orgunit.

Arguments	Type
orgunitID
roleID
durationType	Optional, can contain values ‘free’, ‘hours’, ‘days’
durationLength	Required when durationType is ‘hours’ or ‘days’, should contain the integer value for the number of hours or days that the role will be assigned to a user.
durationFixed	‘true’ or ‘false’, indicates whether the assignment of this role to a user should be equal to durationLength.
inheritThisRole	‘true’ or ‘false’, indicates whether the role will be propsed to underlying units.
Return type	Type

taskadd

Creates a new task, returns the ID of the new task.

Arguments

Type

applicationID

description

Text with a maximum of 254 characters.

taskname

Text with a maximum of 254 characters.

tokenGroupID

svroleID (optional)

If this argument is not present then a supervisor role of the current user is used.

contextAdaptable (optional)

[“0”,”1”,”N”,”Y”]

underconstruction (optional)

[“0”,”1”,”N”,”Y”]

auditaction (optional)

[”0”,	Unknown (default)
“1”,	ReportOnly
“2”,	AlertAppAll
“3”,	AlertAppObsolete
“4”,	AlertAppMissing
“5”,	EnforceAppAll
“6”,	EnforceAppObsolete
“7”,	EnforceAppMissing
“8”,	AlertEnforceAppAll
“9”,	AlertEnforceAppObsolete
“10”,	AlertEnforceAppMissing
“11”]	ImportAll

auditalertmail (optional)

The e-mail address to where alerts about this permission are sent by the auditor. If this argument is not present then the alert e-mail address of the auditor is used.

MaxRoles(optional)

Integer

MaxUsers(optional)

Integer

Return type

Type

ID of the new task

taskadditask

Indicate that 2 tasks are incompatable.

Arguments	Type
taskID
taskID2
Return type	Type

taskaddrole

Assigns a task to a role.

Arguments	Type
roleID
taskID
Return type	Type

taskaddsupervisor

Make a user a supervisor of a task.

Arguments	Type
svroleID	The argument userID can also be used. In this case the default supervisor role is selected. A default supervisor role has a name like __svrole followed by a number. The argument userID can be used for backwards compatibility.
taskID
Return type	Type

useradd

Creates a new user, returns the ID of the new user.

Arguments	Type
description
alias
languageID	‘1’ = English, ‘2’ = Dutch
orgunitID
enddate (optional)	Date format is ‘YYYY-MM-DDThh:nn:ss”, where only year, month and day are required. E.g. “2004-12-11” and “2004-11-28T08:00” are valid values.
disabled (optional)	‘0’ = enabled, ‘1’ = disabled
MaxPermissions(optional)	Integer
MaxRoles(optional)	Integer
Return type	Type
ID of the new user

UserAddRole

UserDeleteRole

Userupdate

Arguments	Type
UserID
description (optional)
language	‘1’ = English, ‘2’ = Dutch
userDisabled (optional)	‘0’ = enabled, ‘1’ = disabled
UserEndDate (optional)	Date format is ‘YYYY-MM-DDThh:nn:ss”, where only year, month and day are required. E.g. “2004-12-11” and “2004-11-28T08:00” are valid values.
firstName (optional)
middleName (optional)
lastName (optional)
maxPermissions(optional)	Integer
maxRoles(optional)	Integer

GetInfo Functions

The set of functions described in this section, can be used to retrieve information that is stored in the BHOLD system. Each function can be called using the GetInfo function from the bscript object. Some objects require parameters. The data returned is subject to the view permissions and the supervised objects of the user logged in.

GetInfo arguments

Name	Description
applications	Returns a list of applications.
attributetypes	Returns a list of attribute types.
orgtypes	Returns a list of organizational unit types.
orgunits	Returns a list of organizational units without the attributes of the organizational units.
orgunitproposedroles	Returns a list of proposed roles linked to the organizational unit.
orgunitroles	Returns a list of directly linked roles of the given organizational unit
Objecttypeattributetypes
permissions
permissionusers
roles	Returns a list of roles
roletasks	Returns a list of tasks of the given role.
tasks	Returns all tasks known by BHOLD.
users	Returns a list of users.
usersroles	Returns the list of linked supervisor roles of the given user.
userpermissions	Returns the list of permissions of the given user.

Orgunit Info

Name	Parameters	Return type
orgunit	orgunitID	Orgunit
orgunitasiattributes	orgunitID	Collection
orgunits	optional: filter optional: proptypeid Searches for units that contain the string described in filter in the proptype described in proptypeid. If this id is omitted, the filter applies to the unit description. If no filter is supplied all visible units are returned.	Collection
orgunitorgunits	orgunitID	Collection
orgunitparents	orgunitID	Collection
orgunitpropertyvalues	orgunitID	Collection
orgunitproptypes	-	Collection
orgunitusers	orgunitID	Collection
orgunitproposedroles	orgunitID	Collection
orgunitroles	orgunitID	Collection
orgunitinheritedroles	orgunitID	Collection
orgunitsupervisors	orgunitID	Collection
orgunitinheritedsupervisors	orgunitID	Collection
orgunitsupervisorroles	orgunitID	Collection

Role Info

Name	Parameters	Return type
role	roleID	Object
roles	optional: filter	Collection
roleasiattributes	roleID	Collection
roleorgunits	roleID	Collection
roleparentroles	roleID	Collection
rolesubroles	roleID	Collection
rolesupervisors	roleID	Collection
rolesupervisorroles	roleID	Collection
roletasks	roleID	Collection
roleusers	roleID	Collection
rolesupervisorroles	roleID	Collection
proposedroleorgunits	roleID	Collection
proposedroleusers	roleID	Collection

Permission – Task Info

Name	Parameters	Return type
permission	TaskID	Permission
permissions	optional: filter	Collection
permissionasiattributes	TaskID	Collection
permissionattachments	TaskID	Collection
permissionattributetypes	-	Collection
permissionparams	TaskID	Collection
permissionroles	TaskID	Collection
permissionsupervisors	TaskID	Collection
permissionsupervisorroles	TaskID	Collection
permissionusers	TaskID	Collection
task	TaskID	Task
tasks	optional: filter	Collection
taskattachments	TaskID	Collection
taskparams	TaskID	Collection
taskroles	TaskID	Collection
tasksupervisors	TaskID	Collection
tasksupervisorroles	TaskID	Collection
taskusers	TaskID	Collection

User Info

Name	Parameters	Return type
user	UserID	User
users	1. optional: filter 2. optional: attributetypeid Searches for users that contain in the attributetype specified by attributetypeid the string specified by filter. If this id is omitted, the filter applies to the user defaultalias. If no filter is supplied all visible users are returned. Examples: 1. GetInfo(“users”) returns all users 2. GetInfo(“users”, “%dmin%”) returns all users with the string “dmin” in the defaultalias 3. Suppose users have an extra attribute called “City”.GetInfo(“users”, “%msterda%”, “City”) returns all users having the string “msterda” in the City.	UserCollection
usersapplications	UserID	Collection
Userpermissions	UserID	Collection
userroles	UserID	Collection
usersroles	UserID	Collection
userstasks	UserID	Collection
usersunits	UserID	Collection
usertasks	UserID	Collection
userunits	UserID	Collection

Return Types

In this section the return types of the GetInfo function are described.

Return type	Return value
Collection	= <ITEMS>{<ITEM description="..." id="..." />}</ITEMS>
Object	= <ITEM type=”…” description="..." />
OrgUnit	= <ITEM id=”…” description="..." orgtype="..." parent="..."> <LIST> {<ITEM> <KEY>… </KEY> <VALUE> … </VALUE> </ITEM>} </LIST> </ITEM>
Permission	= <ITEM id="…" description="…" name="…" tokengroup="…" application="…" > <LIST> {<ITEM> <KEY>… </KEY> <VALUE> … </VALUE> </ITEM>} </LIST> </ITEM>
Roles	= <ITEMS> {<ITEM id="…" description="…" />} </ITEMS>
Role	= <ITEM id="…" description="… " > <LIST> {<ITEM> <KEY>… </KEY> <VALUE> … </VALUE> </ITEM>} </LIST> </ITEM>
Task	See Permission
Users	= <ITEMS> {<ITEM description="…" id="…" alias="…" />} </ITEMS>
User	= <ITEM id="…" description="…" alias="…" firstname="…" lastname="…" uuid="…" language="…"> <LIST> {<ITEM> <KEY>… </KEY> <VALUE> … </VALUE> </ITEM>} </LIST> </ITEM>

Script Sample

A company has a BHOLD server and wants an automated script that creates new customers. The information about the company and its purchase manager will be entered in a customized web page.Every customer is presented in the model as a unit under the unit customers. The purchase manager is as well a member as a supervisor of this unit. A role will be created that gives the owners the right to purchase in name of the new customer.

However, this customer does not exist in the application. There is a special function implemented in the ASI FunctionDispatch that creates a new customer account in the purchase application. Each customer has a customer type.

The possible types can be presented by the FunctionDispatch function as well. The AA will choose the correct type for the new customer.

A role and task need to be created that present the purchase privileges. The real purchase privilege is presented by the ASI as a file: /customers/customer id/purchase”. This file should be linked to the new task.

The Active Server Page that gathers the information will look like this:

<%@ Language=VBScript %>
<% Option Explicit %>
<html>
<body>
<form action=”MySubmit.asp” method=post>
<input type=”hidden” name=”OrgUnitID” 
     value=”<% = Request(”ID”) %>”>
Company <input type=”text” name=”Description”> <br>
Type <select name=”OrgType”>
<%Dim oOrgType
For Each oOrgType on bscript.getinfo(”Orgtypes”) %>
<option value=”<% = oOrgType.OrgTypeID %>”>
<% = oOrgType.Description %>
</option> <%
Next %>
</select>  <br>
Manager <input type=”text” name=” manager”> <br>
Alias <input type=” text” name=” alias”> <br>
e-mail <input type=” text” name=” email”> <br>
<input type=”submit”>
</form>
</body>
</html>

All the customized pages would have to do is request for the right information and create an XML document with the requested information. In this example, the MySubmit page will transform the data in the XML document, assign it to the b1script.Parameters object and finally calls the b1script.ExecuteScript(“MyScript”) function.

The input script will look like this:

<customer>
<description>ACME inc.</description>
<orgtype>5<orgtype>
<name>John Doe</name>
<alias>jdoe</alias>
<email>jdoe@acme.com</email>
</customer>

Note that this input script does not contain any commands for BHOLD. This is because this script is not executed directly by BHOLD; instead of it, this is the input for a pre-defined function. This pre-defined function translates this object to an XML document with BHOLD commands. This mechanism withholds the user from sending scripts to the BHOLD system that contain functions that he is not allowed to execute (e.g. setUser and function dispatches to an ASI).

  <?xml version="1.0" encoding="utf-8" ?> 
- <functions xmlns="http://tempuri.org/BscriptFunctions.xsd">
  
  <function name="roleadduser" roleid="" userid="" /> 
  <function name="roledeleteuser" roleid="" userid="" /> 
  </functions>