Referência do desenvolvedor BHOLD para o Microsoft Identity Manager 2016

O módulo BHOLD-core pode processar comandos de script. Isso pode ser feito usando diretamente o bscript.dll em um projeto .NET. Também interagindo com a interface b1scriptservice.asmx do serviço Web.

Antes de um script ser executado, todas as informações dentro do script devem ser coletadas para compor esse script. Esta informação pode ser recolhida a partir das seguintes fontes:

• Entrada do usuário
• Dados BHOLD
• Aplicações
• Outros

Os dados BHOLD podem ser recuperados usando a função GetInfo do objeto script. Há uma lista completa de comandos que podem apresentar todos os dados armazenados no banco de dados HOLD. No entanto, os dados apresentados estão sujeitos às permissões de visualização do utilizador com sessão iniciada. O resultado está na forma de um documento XML que pode ser analisado.

Outra fonte de informação pode ser uma das aplicações que são controladas pelo BHOLD. O snap-in do aplicativo tem uma função especial, o FunctionDispatch, que pode ser usado para apresentar informações específicas do aplicativo. Isso também é apresentado como um documento XML.

Finalmente, se não houver outra maneira, o script pode conter comandos diretamente para outros aplicativos ou sistemas. NoThenstallation de software extra no servidor BHOLD pode minar a segurança de todo o sistema.

Todas essas informações são colocadas em um documento XML e atribuídas ao objeto de script HOLD. O objeto combina este documento com uma função predefinida. A função predefinida é um documento XSL que traduz o documento de entrada de script em um documento de comando BHOLD.

de processamento de scripts BHOLD

Os comandos são executados na mesma ordem do documento. Se uma função falhar, todos os comandos executados serão revertidos.

Objeto Script

Esta seção descreve como usar o objeto de script.

Recuperar informações BHOLD

A função GetInfo é usada para recuperar informações dos dados disponíveis no sistema de autorização BHOLD. A função requer um nome de função e, eventualmente, um ou mais parâmetros. Se essa função for bem-sucedida, um objeto ou coleção BHOLD será retornado na forma de um documento XML.

Se a função não for bem-sucedida, a função GetInfo retornará uma cadeia de caracteres vazia ou um erro. A descrição e o número do erro podem ser usados para obter mais informações sobre a falha.

A função GetInfo 'FunctionDispatch' pode ser usada para recuperar informações de um aplicativo controlado pelo sistema BHOLD. Esta função requer três parâmetros: o ID do aplicativo, a função de despacho como é definida no ASI e um documento XML com informações de suporte para o ASI. Se a função for bem-sucedida, o resultado estará disponível em formato XML no objeto result.

O trecho abaixo é um exemplo simples de GetInfo em C#:

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

Da mesma forma, o objeto BScript também pode ser acessado através do serviço web b1scriptservice. Isso é feito adicionando uma referência da Web ao seu projeto usando http://<servidor>:5151/BHOLD/Core/b1scriptservice.asmx, onde <servidor> é o servidor com os binários BHOLD instalados. Para obter mais informações, consulte Adicionando uma referência de serviço Web a um projeto do Visual Studio.

O exemplo a seguir mostra como usar a função GetInfo de um serviço Web. Esse código recupera a Unidade Organizacional que tem um OrgID de 1 e, em seguida, exibe o nome dessa Unidade Organizacional na tela.

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

        }
    }
}

O exemplo VBScript a seguir usa o serviço Web via SOAP e usando GetInfo. Para obter exemplos adicionais para SOAP 1.1, SOAP 1.2 e HTTP POST, consulte a seção BHOLD Managed Reference ou você pode navegar para o serviço Web diretamente de um navegador e visualizá-los lá.

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

Executar scripts

A função ExecuteScript do objeto BScript pode ser usada para executar scripts. Esta função requer dois parâmetros. O primeiro parâmetro é o documento XML que contém as informações personalizadas a serem usadas pelo script. O segundo parâmetro é o nome do script predefinido a ser usado. InNo diretório de scripts predefinidos BHOLD, aqui deve ser um documento XSL com o mesmo nome da função, mas com a extensão .xsl.

Se a função não tiver êxito, a função ExecuteScript retornará o valor False. A descrição e o número do erro podem ser usados para saber o que correu mal. A seguir está um exemplo de uso do método da 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

Essa função GetInfo está disponível depois que a função executescript é executada. A função retorna uma cadeia de caracteres formatada em XML que contém o relatório de execução completo. O nó Script contém a estrutura XML do script executado.

Para cada função que falha durante a execução do script, uma função de nó é adicionada com o nome dos nós. ExecuteXML e Error é adicionado ao final do documento, todos os IDs gerados são adicionados.

Observe que apenas as funções, que contêm um erro é adicionado. Um número de erro de '0' significa que a função não é executada.

<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 identificação

Os parâmetros de identificação recebem tratamento especial. Valores não numéricos são usados como valor de pesquisa para localizar as entidades correspondentes no armazenamento de dados HOLD. Quando o valor de pesquisa não é exclusivo, a primeira entidade que está em conformidade com o valor de pesquisa é retornada.

Para distinguir valores de pesquisa numérica de IDs, é possível usar um prefixo. Quando os primeiros seis caracteres do valor de pesquisa são iguais a 'no_id:', esses caracteres são removidos antes que o valor seja usado para pesquisar. Caracteres curinga SQL '%' podem ser usados.

Os seguintes campos são usados com o valor de pesquisa:

Acesso e permissões de script

O código do lado do servidor no Ative Server Pages é usado para executar os scripts. Portanto, o acesso ao script significa o acesso a essas páginas. O sistema BHOLD mantém informações sobre os pontos de entrada das páginas personalizadas. Estas informações incluem a página inicial e a descrição da função (vários idiomas devem ser suportados).

Um usuário está autorizado a entrar nas páginas personalizadas e executar um script. Cada ponto de entrada é apresentado como uma tarefa. Cada usuário que ganhou essa tarefa através de uma função ou uma unidade é capaz de executar a função correspondente.

Uma nova função no menu apresenta todas as funções personalizadas que podem ser executadas pelo usuário. Porque um script pode executar ações no sistema BHOLD sob uma identidade diferente do usuário conectado. É possível dar permissão para executar uma ação específica sem ter supervisão sobre qualquer objeto. Por exemplo, isso pode ser útil para um funcionário que só tem permissão para inserir novos clientes na empresa. Esses scripts também podem ser usados para criar páginas de auto-registro.

Script de comando

O script de comando contém uma lista de funções que são executadas pelo sistema BHOLD. A lista é escrita em um documento XML que está em conformidade com as seguintes definições:

XML tem as seguintes traduções de caracteres especiais:

Esses caracteres XML podem ser usados em identificadores, mas não são recomendados.

O código a seguir mostra um exemplo de um documento de comando válido com três funções:

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

A função OrgUnitAdd armazena a ID da unidade criada em uma variável chamada UnitID. Esta variável é usada como entrada para a função UserAdd. O valor de retorno desta função não é usado. As seções a seguir descrevem todas as funções disponíveis, os parâmetros necessários e seus valores de retorno.

Executar funções

Esta seção descreve como usar as funções de execução.

ABAAttributeRuleAdd

Crie uma nova regra de atributo em um tipo de atributo específico. As regras de atributo só podem ser vinculadas a um tipo de atributo.

A regra de atributo especificada pode ser vinculada a todos os tipos de atributos possíveis.

O RuleType não pode ser alterado com o comando "ABAattributeruletypeupdate". Requer que a descrição do atributo por unique.

aplicaçãoadicionar

Cria um novo aplicativo, retorna a ID do novo aplicativo.

AttributeSetValue

Define o valor de um tipo de atributo conectado ao tipo de objeto. Requer que as descrições do tipo de objeto e do tipo de atributo sejam exclusivas.

AttributeTypeAdicionar

Insere um novo tipo de atributo / tipo de propriedade.

AttributeTypeSetAdd

Insere um novo conjunto de tipos de atributo. Requer que a descrição de um conjunto de tipos de atributo seja exclusiva.

AttributeTypeSetAddAttributeType

Insere um novo tipo de atributo em um conjunto de tipos de atributo existente. Requer que as descrições do conjunto de tipos de atributo e do tipo de atributo sejam exclusivas.

ObjectTypeAddAttributeTypeSet

Adiciona um tipo de atributo definido a um tipo de objeto. Requer que a descrição do tipo de objeto e o conjunto de tipos de atributo sejam exclusivos. Os tipos de objeto são: System, OrgUnit, User, Task.

OrgUnitadd

Cria uma nova unidade organizacional, retorna a ID da nova unidade organizacional.

OrgUnitaddsupervisor

Faça de um usuário um supervisor de uma unidade organizacional.

OrgUnitadduser

Tornar um usuário membro de uma unidade organizacional.

OrgUnitdelete

Remove uma unidade organizacional.

OrgUnitdeleteuser

Remove um usuário como membro de uma unidade organizacional.

roleadd

Cria uma nova função.

roleaddOrgUnit

Atribui uma função a uma unidade organizacional.

roleaddrole

Atribui uma função como uma subfunção de outra função.

RoleAddSupervisor

Tornar um usuário um supervisor de uma função.

roleadduser

Atribui uma função a um usuário. A função não pode ser uma função adaptável ao contexto quando nenhum contextID é fornecido.

roledelete

Exclui uma função.

roledeleteuser

Remove a atribuição de função a um usuário. As funções herdadas pelo usuário são revogadas por este comando.

roleproposeOrgUnit

Propõe uma função para atribuí-la aos membros e às sub-OrgUnits de uma OrgUnit.

taskadd

Cria uma nova tarefa, retorna a ID da nova tarefa.

taskadditask

Indique que duas tarefas são incompatíveis.

taskaddrole

Atribui uma tarefa a uma função.

TaskAddSupervisor

Torne um usuário um supervisor de uma tarefa.

useradd

Cria um novo usuário, retorna a ID do novo usuário.

UserAddRole

Adiciona uma função de usuário.

UserDeleteRole

Exclui uma função de usuário.

Userupdate

Atualiza um usuário.

Funções GetInfo

O conjunto de funções descrito nesta seção pode ser usado para recuperar informações armazenadas no sistema BHOLD. Cada função pode ser chamada usando a função GetInfo do objeto BScript. Alguns objetos requerem parâmetros. Os dados retornados estão sujeitos às permissões de exibição e aos objetos supervisionados do usuário conectado.

Argumentos GetInfo

Informação OrgUnit

Informações sobre a função

Permissão - Informações da tarefa

Informação do utilizador

Tipos de devolução

Nesta seção, os tipos de retorno da função GetInfo são descritos.

Exemplo de script

Uma empresa tem um servidor BHOLD e quer um script automatizado que crie novos clientes. As informações sobre a empresa e seu gerente de compras entram em uma página web personalizada. Cada cliente é apresentado no modelo como uma unidade sob os clientes da unidade. O gestor de compras é tão membro como supervisor desta unidade. É criada uma função que dá aos proprietários o direito de comprar em nome do novo cliente.

No entanto, esse cliente não existe no aplicativo. Há uma função especial implementada no ASI FunctionDispatch que cria uma nova conta de cliente no aplicativo de compra. Cada cliente tem um tipo de cliente.

Os tipos possíveis podem ser apresentados pela função FunctionDispatch também. O AA escolhe o tipo correto para o novo cliente.

Crie uma função e uma tarefa para apresentar os privilégios de compra. O privilégio de compra real é apresentado pelo ASI como um arquivo /customers/customer id/purchase. Esse arquivo deve ser vinculado à nova tarefa.

A página do Ative Server que reúne as informações tem esta aparência:

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

Tudo o que as páginas personalizadas teriam que fazer é solicitar as informações corretas e criar um documento XML com as informações solicitadas. Neste exemplo, a página MySubmit transforma os dados no documento XML, atribuindo-os ao b1script. Os parâmetros objeto e, finalmente, chama a função b1script.ExecuteScript("MyScript").

O script de entrada a seguir mostra este exemplo:

<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 não contém comandos para BHOLD. Isso ocorre porque esse script não é executado diretamente por BHOLD; em vez disso, esta é a entrada para uma função pré-definida. Esta função predefinida traduz este objeto para um documento XML com comandos BHOLD. Esse mecanismo impede que o usuário envie scripts para o sistema BHOLD que contenham funções que o usuário não tem permissão para executar, como setUser e despachos de função para um 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>

Próximos passos

• Guia de conceitos BHOLD
• Histórico de versões do BHOLD