Referencia para desarrolladores de BHOLD para Microsoft Identity Manager 2016

El módulo BHOLD-core puede procesar comandos de script. Se puede hacer directamente mediante el bscript.dll en un proyecto de .NET. También interactúa con la interfaz b1scriptservice.asmx del servicio web.

Antes de que se haya ejecutado un script, toda la información del script debe recopilarse para redactar este script. Esta información se puede recopilar de los siguientes orígenes:

• Entrada del usuario
• Datos de BHOLD
• Aplicaciones
• Otros

Los datos de BHOLD se pueden recuperar mediante la función GetInfo del objeto de script. Hay una lista completa de comandos que pueden presentar todos los datos almacenados en la base de datos BHOLD. Sin embargo, los datos presentados están sujetos a los permisos de vista del usuario que inició sesión. El resultado está en forma de un documento XML que se puede analizar.

Otro origen de información puede ser una de las aplicaciones controladas por BHOLD. El complemento de aplicación tiene una función especial, FunctionDispatch, que se puede usar para presentar información específica de la aplicación. Esto también se presenta como un documento XML.

Por último, si no hay otra manera, el script puede contener comandos directamente a otras aplicaciones o sistemas. NoLanstallation of extra software on the BHOLD server can mina la seguridad de todo el sistema.

Toda esta información se coloca en un documento XML y se asigna al objeto de script BHOLD. El objeto combina este documento con una función predefinida. La función predefinida es un documento XSL que traduce el documento de entrada del script en un documento de comando BHOLD.

de procesamiento de scripts de BHOLD

Los comandos se ejecutan en el mismo orden que en el documento. Si se produce un error en una función, se revierten todos los comandos ejecutados.

Script (objeto)

En esta sección se describe cómo usar el objeto de script.

Recuperación de información de BHOLD

La función GetInfo se usa para recuperar información de los datos disponibles en el sistema de autorización de BHOLD. La función requiere un nombre de función y, finalmente, uno o varios parámetros. Si esta función se ejecuta correctamente, se devuelve un objeto o colección BHOLD en forma de documento XML.

Si la función no se ejecuta correctamente, la función GetInfo devuelve una cadena vacía o un error. La descripción del error y el número se pueden usar para obtener más información sobre el error.

La función GetInfo 'FunctionDispatch' se puede usar para recuperar información de una aplicación controlada por el sistema BHOLD. Esta función requiere tres parámetros: el identificador de la aplicación, la función de distribución tal como se define en asi y un documento XML con información complementaria para asi. Si la función se realiza correctamente, el resultado está disponible en formato XML en el objeto de resultado.

El fragmento de código siguiente es un ejemplo sencillo de C# de GetInfo:

ScriptProcessor myScriptProcessor = new ScriptProcessor();
myScriptProcessor.Initializae("CORP\\b1user");
myScriptProcessor.GetInfo("OrgUnit", "1");

Del mismo modo, también se puede acceder al objeto BScript a través del servicio web b1scriptservice. Para ello, se agrega una referencia web al proyecto mediante http://<servidor>:5151/BHOLD/Core/b1scriptservice.asmx donde <servidor> es el servidor con los archivos binarios de BHOLD instalados. Para obtener más información, vea Agregar una referencia de servicio web a un proyecto de Visual Studio.

En el ejemplo siguiente se muestra cómo usar la función GetInfo desde un servicio web. Este código recupera la unidad organizativa que tiene un OrgID de 1 y, a continuación, muestra el nombre de esa unidad organizativa en la pantalla.

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);

        }
    }
}

En el siguiente ejemplo de VBScript se usa el servicio web a través de SOAP y mediante GetInfo. Para obtener ejemplos adicionales de SOAP 1.1, SOAP 1.2 y HTTP POST, consulte la sección Referencia administrada de BHOLD o puede navegar al servicio web directamente desde un explorador y verlos allí.

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=""http://schemas.xmlsoap.org/soap/envelope/"">" & vbCRLF
SOAPRequest = SOAPRequest & " <soap:Body>" & vbCRLF
SOAPRequest = SOAPRequest & " <GetInfo xmlns=""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

Ejecutar scripts

La función ExecuteScript del objeto BScript de se puede usar para ejecutar scripts. Esta función requiere dos parámetros. El primer parámetro es el documento XML que contiene la información personalizada que va a usar el script. El segundo parámetro es el nombre del script predefinido que se va a usar. En el directorio de scripts predefinidos de BHOLD, debe ser un documento XSL con el mismo nombre que la función, pero con la extensión .xsl.

Si la función no se realiza correctamente, la función ExecuteScript devuelve el valor False. La descripción del error y el número se pueden usar para saber lo que salió mal. A continuación se muestra un ejemplo de uso del método web ExecuteXML. Este método invoca 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

Esta función GetInfo está disponible después de ejecutar la función executescript de. La función devuelve una cadena con formato XML que contiene el informe de ejecución completo. El nodo Script contiene la estructura XML del script ejecutado.

Para cada función que produce un error durante la ejecución del script, se agrega una función de nodo con el nombre de los nodos. ExecuteXML y Error se agregan al final del documento todos los identificadores generados.

Observe que solo se agregan las funciones que contienen un error. Un número de error de '0' significa que la función no se ejecuta.

<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>

Parámetros de identificador

Los parámetros id. obtienen un tratamiento especial. Los valores no numéricos se usan como valor de búsqueda para buscar las entidades correspondientes en el almacén de datos de BHOLD. Cuando el valor de búsqueda no es único, se devuelve la primera entidad que cumple con el valor de búsqueda.

Para distinguir los valores numéricos de los identificadores, es posible usar un prefijo. Cuando los seis primeros caracteres del valor de búsqueda son iguales a "no_id:", estos caracteres se quitan antes de que se use el valor para la búsqueda. Se pueden usar caracteres comodín de SQL "%".

Los campos siguientes se usan con el valor de búsqueda:

Acceso y permisos de script

El código del lado servidor en las páginas active server se usa para ejecutar los scripts. Por lo tanto, el acceso al script significa acceso a estas páginas. El sistema BHOLD mantiene información sobre los puntos de entrada de las páginas personalizadas. Esta información incluye la página de inicio y la descripción de la función (se deben admitir varios lenguajes).

Un usuario está autorizado para poder escribir las páginas personalizadas y ejecutar un script. Cada punto de entrada se presenta como una tarea. Cada usuario que obtuvo esta tarea a través de un rol o una unidad puede ejecutar la función correspondiente.

Una nueva función en el menú presenta todas las funciones personalizadas que el usuario puede ejecutar. Dado que un script puede realizar acciones en el sistema BHOLD en una identidad diferente del usuario que inició sesión. Es posible conceder permiso para realizar una acción específica sin tener supervisión sobre ningún objeto. Por ejemplo, esto podría ser útil para un empleado que solo pueda ingresar nuevos clientes a la empresa. Estos scripts también se pueden usar para crear páginas de registro automático.

Script de comandos

El script de comandos contiene una lista de funciones ejecutadas por el sistema BHOLD. La lista se escribe en un documento XML que se ajusta a las definiciones siguientes:

XML tiene las siguientes traducciones de caracteres especiales:

Estos caracteres XML se pueden usar en identificadores, pero no se recomiendan.

En el código siguiente se muestra un ejemplo de un documento de comando válido con tres funciones:

<functions>

   <functionname="OrgUnitAdd" parentID="34" description="Acme Inc." orgtypeID="5" return="@UnitID@" />

   <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>

La función OrgUnitAdd almacena el identificador de la unidad creada en una variable denominada UnitID. Esta variable se usa como entrada para la función UserAdd. No se usa el valor devuelto de esta función. En las secciones siguientes se describen todas las funciones disponibles, los parámetros necesarios y sus valores devueltos.

Ejecutar funciones

En esta sección se describe cómo usar las funciones de ejecución.

ABAAttributeRuleAdd

Cree una nueva regla de atributo en un tipo de atributo específico. Las reglas de atributo solo se pueden vincular a un tipo de atributo.

La regla de atributo especificada se puede vincular a todos los tipos de atributo posibles.

RuleType no se puede cambiar con el comando "ABAattributeruletypeupdate". Requiere que la descripción del atributo sea única.

applicationadd

Crea una nueva aplicación y devuelve el identificador de la nueva aplicación.

AttributeSetValue

Establece el valor de un tipo de atributo conectado al tipo de objeto. Requiere que las descripciones del tipo de objeto y el tipo de atributo sean únicos.

AttributeTypeAdd

Inserta un nuevo tipo de atributo o tipo de propiedad.

AttributeTypeSetAdd

Inserta un nuevo conjunto de tipos de atributo. Requiere que la descripción de un conjunto de tipos de atributo sea única.

AttributeTypeSetAddAttributeType

Inserta un nuevo tipo de atributo en un conjunto de tipos de atributo existente. Requiere que las descripciones del conjunto de tipos de atributo y el tipo de atributo sean únicos.

ObjectTypeAddAttributeTypeSet

Agrega un tipo de atributo establecido a un tipo de objeto. Requiere que la descripción del tipo de objeto y el conjunto de tipos de atributo sean únicos. Los tipos de objeto son: System, OrgUnit, User, Task.

OrgUnitad

Crea una nueva unidad organizativa y devuelve el identificador de la nueva unidad organizativa.

OrgUnitadddsupervisor

Convierta a un usuario en supervisor de una unidad organizativa.

OrgUnitadduser

Convertir a un usuario en miembro de una unidad organizativa.

OrgUnitdelete

Quita una unidad organizativa.

OrgUnitdeleteuser

Quita un usuario como miembro de una unidad organizativa.

roleadd

Crea un nuevo rol.

roleaddOrgUnit

Asigna un rol a una unidad organizativa.

roleaddrole

Asigna un rol como subrole de otro rol.

roleaddsupervisor

Convierta a un usuario en supervisor de un rol.

roleadduser

Asigna un rol a un usuario. El rol no puede ser un rol adaptable al contexto cuando no se da ningún valor contextID.

roledelete

Elimina un rol.

roledeleteuser

Quita la asignación de roles a un usuario. Este comando revoca los roles heredados por el usuario.

roleproposeOrgUnit

Propone un rol para asignarlo a los miembros y a los sub-OrgUnits de un OrgUnit.

taskadd

Crea una nueva tarea y devuelve el identificador de la nueva tarea.

taskadditask

Indique que dos tareas no son compatibles.

taskaddrole

Asigna una tarea a un rol.

taskaddsupervisor

Convierta a un usuario en supervisor de una tarea.

useradd

Crea un nuevo usuario y devuelve el identificador del nuevo usuario.

UserAddRole

Agrega un rol de usuario.

UserDeleteRole

Elimina un rol de usuario.

Userupdate

Actualiza un usuario.

Funciones GetInfo

El conjunto de funciones descritas en esta sección se puede usar para recuperar información almacenada en el sistema BHOLD. Se puede llamar a cada función mediante la función GetInfo del objeto BScript. Algunos objetos requieren parámetros. Los datos devueltos están sujetos a los permisos de vista y a los objetos supervisados del usuario que inició sesión.

Argumentos GetInfo

Información de OrgUnit

Información de roles

Permiso: información de tareas

Información del usuario

Tipos de valores devueltos

En esta sección, se describen los tipos devueltos de la función GetInfo.

Ejemplo de script

Una empresa tiene un servidor BHOLD y quiere un script automatizado que crea nuevos clientes. La información sobre la empresa y su administrador de compras entra en una página web personalizada. Cada cliente se presenta en el modelo como una unidad bajo los clientes de la unidad. El administrador de compras es también miembro como supervisor de esta unidad. Se crea un rol que proporciona a los propietarios el derecho de comprar en nombre del nuevo cliente.

Sin embargo, este cliente no existe en la aplicación. Hay una función especial implementada en la función ASIDispatch que crea una nueva cuenta de cliente en la aplicación de compra. Cada cliente tiene un tipo de cliente.

La función FunctionDispatch también puede presentar los tipos posibles. AA elige el tipo correcto para el nuevo cliente.

Cree un rol y una tarea para presentar los privilegios de compra. El privilegio de compra real lo presenta asi como un archivo /customers/customer id/purchase. Este archivo debe estar vinculado a la nueva tarea.

La página Servidor activo que recopila la información tiene este aspecto:

<%@ 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>

Todas las páginas personalizadas tendrían que hacer es solicitar la información correcta y crear un documento XML con la información solicitada. En este ejemplo, la página MySubmit transforma los datos del documento XML, asígnelos al b1script. Los parámetros objeto y, por último, llaman a la función b1script.ExecuteScript("MyScript").

El siguiente script de entrada muestra este ejemplo:

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

Este script de entrada no contiene ningún comando para BHOLD. Esto se debe a que BHOLD no ejecuta directamente este script; en lugar de ello, esta es la entrada de una función predefinida. Esta función predefinida traduce este objeto a un documento XML con comandos BHOLD. Este mecanismo impide que el usuario envíe scripts al sistema BHOLD que contenga funciones que el usuario no puede ejecutar, como setUser y function se distribuye a 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>

Pasos siguientes

• guía de conceptos de BHOLD
• del historial de versiones de BHOLD