Dokumentacja dla deweloperów pakietu BHOLD dla programu Microsoft Identity Manager 2016

Moduł BHOLD-core może przetwarzać polecenia skryptów. Można to zrobić bezpośrednio przy użyciu bscript.dll w projekcie platformy .NET. Interakcja z interfejsem b1scriptservice.asmx usługi internetowej.

Przed wykonaniem skryptu należy zebrać wszystkie informacje wewnątrz skryptu, aby utworzyć ten skrypt. Te informacje można zebrać z następujących źródeł:

• Dane wejściowe użytkownika
• Dane pakietu BHOLD
• Aplikacje
• Pozostałe

Dane BHOLD można pobrać przy użyciu funkcji GetInfo obiektu skryptu. Istnieje pełna lista poleceń, które mogą przedstawiać wszystkie dane przechowywane w bazie danych BHOLD. Jednak prezentowane dane podlegają uprawnienia do wyświetlania zalogowanego użytkownika. Wynik jest w postaci dokumentu XML, który można przeanalizować.

Innym źródłem informacji może być jedna z aplikacji kontrolowanych przez usługę BHOLD. Przystawka aplikacji ma specjalną funkcję FunctionDispatch, która może służyć do prezentowania informacji specyficznych dla aplikacji. Jest on również przedstawiany jako dokument XML.

Na koniec, jeśli nie ma innego sposobu, skrypt może zawierać polecenia bezpośrednio do innych aplikacji lub systemów. NoThenstallation dodatkowego oprogramowania na serwerze BHOLD może podważyć bezpieczeństwo całego systemu.

Wszystkie te informacje są umieszczane w jednym dokumencie XML i przypisane do obiektu skryptu BHOLD. Obiekt łączy ten dokument ze wstępnie zdefiniowaną funkcją. Wstępnie zdefiniowana funkcja jest dokumentem XSL, który tłumaczy dokument wejściowy skryptu na dokument polecenia BHOLD.

Polecenia są wykonywane tak samo jak w dokumencie. Jeśli jedna funkcja zakończy się niepowodzeniem, wszystkie wykonane polecenia zostaną wycofane.

Obiekt skryptu

W tej sekcji opisano sposób używania obiektu skryptu.

Pobieranie informacji dotyczących pakietu BHOLD

Funkcja GetInfo służy do pobierania informacji z dostępnych danych w systemie autoryzacji BHOLD. Funkcja wymaga nazwy funkcji i ostatecznie co najmniej jednego parametru. Jeśli ta funkcja powiedzie się, obiekt lub kolekcja BHOLD jest zwracana w postaci dokumentu XML.

Jeśli funkcja nie powiedzie się, funkcja GetInfo zwraca pusty ciąg lub błąd. Opis błędu i numer mogą służyć do uzyskania dodatkowych informacji na temat błędu.

Funkcja GetInfo "FunctionDispatch" może służyć do pobierania informacji z aplikacji kontrolowanej przez system BHOLD. Ta funkcja wymaga trzech parametrów: identyfikator aplikacji, funkcję dispatch zdefiniowaną w środowisku ASI i dokument XML z informacjami pomocniczymi dla usługi ASI. Jeśli funkcja powiedzie się, wynik jest dostępny w formacie XML w obiekcie wynikowym.

Poniższy fragment kodu jest prostym przykładem języka C# getInfo:

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

Podobnie dostęp do obiektu BScript można również uzyskać za pośrednictwem usługi internetowej b1scriptservice. Jest to wykonywane przez dodanie odwołania do sieci Web do projektu przy użyciu serwera http://<>:5151/BHOLD/Core/b1scriptservice.asmx, gdzie <serwer> jest serwerem z zainstalowanymi plikami binarnymi BHOLD. Aby uzyskać więcej informacji, zobacz Dodawanie odwołania usługi internetowej do projektu programu Visual Studio.

W poniższym przykładzie pokazano, jak używać funkcji GetInfo z usługi internetowej. Ten kod pobiera jednostkę organizacyjną z identyfikatorem OrgID 1, a następnie wyświetla nazwę tej jednostki organizacyjnej na ekranie.

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

        }
    }
}

Poniższy przykład w języku VBScript używa usługi internetowej za pośrednictwem protokołu SOAP i getInfo. Aby uzyskać dodatkowe przykłady protokołu SOAP 1.1, SOAP 1.2 i HTTP POST, zobacz sekcję Dokumentacja zarządzana BHOLD lub możesz przejść do usługi internetowej bezpośrednio z przeglądarki i wyświetlić je tam.

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

Wykonywanie skryptów

Funkcja ExecuteScript obiektu BScript może służyć do wykonywania skryptów. Ta funkcja wymaga dwóch parametrów. Pierwszy parametr to dokument XML zawierający informacje niestandardowe, które mają być używane przez skrypt. Drugi parametr to nazwa wstępnie zdefiniowanego skryptu do użycia. W katalogu skryptów wstępnie zdefiniowanych BHOLD powinien być dokument XSL o takiej samej nazwie jak funkcja, ale z rozszerzeniem xsl.

Jeśli funkcja nie powiedzie się, funkcja ExecuteScript zwraca wartość False. Opis błędu i numer mogą służyć do poznania, co poszło nie tak. Poniżej przedstawiono przykład użycia metody internetowej ExecuteXML. Ta metoda wywołuje skrypt 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

Ta funkcja GetInfo jest dostępna po wykonaniu funkcji executescript. Funkcja zwraca sformatowany ciąg XML zawierający kompletny raport wykonywania. Węzeł Skrypt zawiera strukturę XML wykonanego skryptu.

Dla każdej funkcji, która kończy się niepowodzeniem podczas wykonywania skryptu, funkcja node jest dodawana z nazwą węzłów. Funkcja ExecuteXML i błąd jest dodawana na końcu dokumentu dodawane są wszystkie wygenerowane identyfikatory.

Zwróć uwagę, że dodawane są tylko funkcje, które zawierają błąd. Liczba błędów "0" oznacza, że funkcja nie jest wykonywana.

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

Parametry identyfikatora

Parametry identyfikatora uzyskują specjalne traktowanie. Wartości nieliczbowe są używane jako wartość wyszukiwania do lokalizowania odpowiednich jednostek w magazynie danych BHOLD. Gdy wartość wyszukiwania nie jest unikatowa, zwracana jest pierwsza jednostka zgodna z wartością wyszukiwania.

Aby odróżnić wartości wyszukiwania liczbowego od identyfikatorów, można użyć prefiksu. Gdy pierwsze sześć znaków wartości wyszukiwania jest równe "no_id:", te znaki zostaną usunięte przed zastosowaniem wartości do wyszukiwania. Można użyć symboli wieloznacznych SQL "%".

Następujące pola są używane z wartością wyszukiwania:

Dostęp do skryptu i uprawnienia

Kod po stronie serwera na stronach active server są używane do wykonywania skryptów. W związku z tym dostęp do skryptu oznacza dostęp do tych stron. System BHOLD przechowuje informacje o punktach wejścia stron niestandardowych. Te informacje obejmują stronę początkową i opis funkcji (wiele języków powinno być obsługiwanych).

Użytkownik ma uprawnienia do wprowadzania stron niestandardowych i wykonywania skryptu. Każdy punkt wejścia jest przedstawiany jako zadanie. Każdy użytkownik, który uzyskał to zadanie za pośrednictwem roli lub jednostki, może wykonać odpowiednią funkcję.

Nowa funkcja w menu przedstawia wszystkie funkcje niestandardowe, które mogą być wykonywane przez użytkownika. Ponieważ skrypt może wykonywać akcje w systemie BHOLD w ramach tożsamości innej niż zalogowany użytkownik. Istnieje możliwość udzielenia uprawnień do wykonania jednej konkretnej akcji bez nadzoru nad żadnym obiektem. Może to być na przykład przydatne dla pracownika, który może wprowadzać nowych klientów tylko do firmy. Te skrypty mogą również służyć do tworzenia stron samodzielnego rejestrowania.

Skrypt polecenia

Skrypt polecenia zawiera listę funkcji wykonywanych przez system BHOLD. Lista jest zapisywana w dokumencie XML zgodnym z następującymi definicjami:

Kod XML zawiera następujące tłumaczenia znaków specjalnych:

Te znaki XML mogą być używane w identyfikatorach, ale nie są zalecane.

Poniższy kod przedstawia przykład prawidłowego dokumentu polecenia z trzema funkcjami:

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

Funkcja OrgUnitAdd przechowuje identyfikator utworzonej jednostki w zmiennej o nazwie UnitID. Ta zmienna jest używana jako dane wejściowe dla funkcji UserAdd. Wartość zwracana tej funkcji nie jest używana. W poniższych sekcjach opisano wszystkie dostępne funkcje, wymagane parametry i ich wartości zwracane.

Wykonywanie funkcji

W tej sekcji opisano sposób używania funkcji execute.

ABAAttributeRuleAdd

Utwórz nową regułę atrybutu dla określonego typu atrybutu. Reguły atrybutów mogą być połączone tylko z jednym typem atrybutu.

Określona reguła atrybutu może być połączona ze wszystkimi możliwymi typami atrybutów.

Nie można zmienić właściwości RuleType za pomocą polecenia "ABAattributeruletypeupdate". Wymaga, aby opis atrybutu był unikatowy.

applicationadd

Tworzy nową aplikację, zwraca identyfikator nowej aplikacji.

AttributeSetValue

Ustawia wartość typu atrybutu połączonego z typem obiektu. Wymaga, aby opisy typu obiektu i typu atrybutu są unikatowe.

AttributeTypeAdd

Wstawia nowy typ atrybutu/typ właściwości.

AttributeTypeSetAdd

Wstawia nowy zestaw typów atrybutów. Wymaga, aby opis zestawu typów atrybutów był unikatowy.

AttributeTypeSetAddAttributeType

Wstawia nowy typ atrybutu w istniejącym zestawie typów atrybutów. Wymaga, aby opisy zestawu typów atrybutów i typu atrybutu są unikatowe.

ObjectTypeAddAttributeTypeSet

Dodaje typ atrybutu ustawiony na typ obiektu. Wymaga, aby opis typu obiektu i zestaw typów atrybutów był unikatowy. Typy obiektów to: System, OrgUnit, User, Task.

OrgUnitadd

Tworzy nową jednostkę organizacyjną, zwraca identyfikator nowej jednostki organizacyjnej.

OrgUnitaddsupervisor

Nadaj użytkownikowi nadzorcę jednostki organizacyjnej.

OrgUnitadduser

Ustaw użytkownika na członka jednostki organizacyjnej.

OrgUnitdelete

Usuwa jednostkę organizacyjną.

OrgUnitdeleteuser

Usuwa użytkownika jako członka jednostki organizacyjnej.

roleadd

Tworzy nową rolę.

roleaddOrgUnit

Przypisuje rolę do jednostki organizacyjnej.

roleaddrole

Przypisuje rolę jako podrolę innej roli.

roleaddsupervisor

Nadaj użytkownikowi nadzorcę roli.

roleadduser

Przypisuje rolę użytkownikowi. Rola nie może być rolą dostosowywalną do kontekstu, gdy nie podano identyfikatora kontekstu.

roledelete

Usuwa rolę.

roledeleteuser

Usuwa przypisanie roli do użytkownika. Odziedziczone role przez użytkownika są odwoływane przez to polecenie.

roleproposeOrgUnit

Proponuje rolę, która ma zostać przypisana do członków i jednostki organizacyjnej organizacji.

zadaniedodaj

Tworzy nowe zadanie, zwraca identyfikator nowego zadania.

taskadditask

Wskazuje, że dwa zadania są niezgodne.

taskaddrole

Przypisuje zadanie do roli.

taskaddsupervisor

Nadaj użytkownikowi nadzorcę zadania.

useradd

Tworzy nowego użytkownika, zwraca identyfikator nowego użytkownika.

UserAddRole

Dodaje rolę użytkownika.

UserDeleteRole

Usuwa rolę użytkownika.

Userupdate

Aktualizuje użytkownika.

Funkcje GetInfo

Zestaw funkcji opisanych w tej sekcji może służyć do pobierania informacji przechowywanych w systemie BHOLD. Każda funkcja może być wywoływana przy użyciu funkcji GetInfo z obiektu BScript. Niektóre obiekty wymagają parametrów. Zwrócone dane podlegają uprawnieniam do wyświetlania i nadzorowanym obiektom zalogowanego użytkownika.

Argumenty GetInfo

Informacje o organizacji

Informacje o roli

Uprawnienie — informacje o zadaniu

Informacje o użytkowniku

Typy zwracane

W tej sekcji opisano zwracane typy funkcji GetInfo.

Przykładowy skrypt

Firma ma serwer BHOLD i chce zautomatyzowanego skryptu, który tworzy nowych klientów. Informacje o firmie i jej menedżerze zakupów są wprowadzane na dostosowanej stronie internetowej. Każdy klient jest przedstawiany w modelu jako jednostka w ramach klientów jednostkowych. Menedżer zakupów jest również członkiem nadzorcy tej lekcji. Tworzona jest rola, która daje właścicielom prawo do zakupu w imieniu nowego klienta.

Jednak ten klient nie istnieje w aplikacji. Istnieje specjalna funkcja zaimplementowana w funkcji ASIDispatch, która tworzy nowe konto klienta w aplikacji zakupu. Każdy klient ma typ klienta.

Możliwe typy mogą być również prezentowane przez funkcję FunctionDispatch. AA wybiera prawidłowy typ dla nowego klienta.

Utwórz rolę i zadanie, aby przedstawić uprawnienia zakupu. Rzeczywiste uprawnienia zakupu są prezentowane przez usługę ASI jako plik /customers/customer id/purchase. Ten plik powinien być połączony z nowym zadaniem.

Strona aktywnego serwera, która zbiera informacje, wygląda następująco:

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

Wszystkie dostosowane strony muszą być wymagane, to zażądać odpowiednich informacji i utworzyć dokument XML z żądanymi informacjami. W tym przykładzie strona MySubmit przekształca dane w dokumencie XML, przypisz ją do b1script. Parametry obiektu, a na koniec wywołuje funkcję b1script.ExecuteScript("MyScript").

Poniższy skrypt wejściowy przedstawia następujący przykład:

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

Ten skrypt wejściowy nie zawiera żadnych poleceń dla usługi BHOLD. Jest to spowodowane tym, że ten skrypt nie jest wykonywany bezpośrednio przez usługę BHOLD; zamiast tego jest to dane wejściowe dla wstępnie zdefiniowanej funkcji. Ta wstępnie zdefiniowana funkcja tłumaczy ten obiekt na dokument XML za pomocą poleceń BHOLD. Ten mechanizm uniemożliwia użytkownikowi wysyłanie skryptów do systemu BHOLD zawierającego funkcje, których użytkownik nie może wykonać, takich jak setUser i wysyłanie funkcji do usługi 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>

Następne kroki

• Przewodnik po pojęciach dotyczących BHOLD
• historia wersji BHOLD