BHOLD Developer Reference
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.
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:
|
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) |
|
||||||||||||||||||||||||
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>