Anwendungsbeispiele

Im Folgenden werden einige Beispiele für die Nutzung der Prozeduren vorgestellt.

Anlegen von Benutzern

Das Beispiel zeigt, wie Sie aus Kontaktobjekten in der Processes-Datenbank Benutzer mit eigenem SSO-Konto und einer Mitgliedschaft in einer Portal-Gruppe erstellen können.

Cursor importieren 
-- Read the person data
----------------------------------------------------------------------------
DECLARE c1 CURSOR FAST_FORWARD FOR
SELECT s.personid, a2o.agentid, acc.accnam
FROM contsystem s
JOIN contdetail d ON d.personid = s.personid
LEFT JOIN hlsysagenttoobject a2o ON a2o.objectid = s.personid
        AND a2o.objectdefid = s.persondefid
-- Join the account type that matches your Authenticator configuration
LEFT JOIN contaccinfapplacc acc ON acc.personid = s.personid
        AND acc.accapp = 'Windows'
-- only create if no agent exists and an accountname is given
WHERE a2o.agentid IS NULL
AND     ISNULL(acc.accnam,'') <> ''
AND     ISNULL(d.persta,0) = @StatusEmployed
            /*
             Maybe filter duplicate accnam values, since this is not supported
            */
OPEN c1
FETCH NEXT FROM c1 INTO @PersonID, @UserID, @UserAccountNT

WHILE @@FETCH_STATUS = 0
BEGIN
        -- create user out of contact information in Processes
        EXEC hlapi_userimport_elevatepersontouser @ActionContext
            , @PersonID, @ContactDefID, @UserID OUTPUT
        
        -- create login for user
        EXEC hlapi_userimport_oidcaccountforuser @ActionContext
            , @UserID, @UserAccountNT

        -- associate all groups needed for portal
        EXEC hlapi_userimport_assignusertoportalgroups @ActionContext
                , @UserID, @PortalName
        FETCH NEXT FROM c1 INTO @PersonID, @UserID, @UserAccountNT
END
CLOSE c1
  1. Erstellen Sie einen Benutzer für einen Kontakt.
  2. Erstellen Sie das Konto.
  3. Weisen Sie den neuen Benutzer einer Gruppe zu, die die Serviceware Portal-Verwendung ermöglicht.

Im AD-Import Kontakt zur einer Organisation assoziieren

Ein häufiger Anwendungsfall in SQL-Import-Skripten ist das Erstellen einer Assoziation und das Entfernen unnötiger oder alter Assoziationen desselben Typs (verschieben). Dies kann auf zwei Arten erreicht werden. Die API associate_object verfügt zu diesem Zwecke über eine Funktion. In diesem Kapitel werden zwei Wege aufgezeigt, um dieses Ergebnis zu erzielen:
  • Move-Funktion von associate_object
  • Separater deassociate_object-Aufruf
Anmerkung: Wir empfehlen die erste Variante zu verwenden.
Nutzung der Move-Funktion in associate_object
Neu Alt 
-- check for unnecessary previous associations and log deletion
IF @EventLogging > 2 AND @RemovePersonAsc = 1
    BEGIN
        IF EXISTS (SELECT TOP 1 * FROM dbo.hlsysassociation
            WHERE associationdefid=@Person2OrganizationDefID
            AND objectdefida IN (@CompanyDefID, @DepartmentDefID, @SiteDefID)
            AND objectida!=@orgunitB_ID AND objectdefidb=@ContactDefID
            AND objectidb=@ContactID)

        BEGIN
        -- log deletion
            INSERT hlgtadslog VALUES (@gmtsysdate, @orgunitB_ID, 'ASC_D_0005'
                , 'Alle Assoziationen zwischen der Person '
                + ISNULL(@lastname,'<Kein Name>') + ', '
                + ISNULL(@firstname,'<Kein Name>')
                + ' und anderen Organisationen wurden geloescht.','')
        END
    END

-- check for an existing association to the organization and log creation
IF @EventLogging > 1  
    BEGIN
        IF NOT EXISTS (SELECT TOP 1 * FROM hlsysassociation
            WHERE associationdefid=@Person2OrganizationDefID
                AND objectdefida = @orgunitB_DefID
                AND objectida=@orgunitB_ID AND objectdefidb = @ContactDefID
                AND objectidb=@ContactID)

         BEGIN
            -- log creation
            INSERT hlgtadslog VALUES (@gmtsysdate, @ContactID
                , 'ASC_N_0005', 'Zwischen der Person;' + ISNULL(@lastname,'<Kein Name>')
                + ', ' + ISNULL(@firstname,'<Kein Name>')
                + ' und der Organisation ' + ISNULL(@Organisation,'<Kein Name>')
                + ' in der Kategorie ' + ISNULL(@Root,'<Kein Name>')
                + ' wurde eine neue Assoziation angelegt.','')
        END
    END

-- enforce new association and remove old one
EXEC hlapi_userimport_associateobject @ActionContext
    , @Person2OrganizationDefID
    , @DefTypeOrgUnit, @orgunitB_ID, @orgunitB_DefID
    , @DefTypePerson, @ContactID, @ContactDefID
    , @RemovePersonAsc, 0, 1
 
-- delete unnecessary previous associations
IF @RemovePersonAsc = 1
    BEGIN
        DELETE hlsysassociation WHERE associationdefid=@Person2OrganizationDefID
            AND objectdefida IN (@CompanyDefID, @DepartmentDefID, @SiteDefID)
            AND objectida!=@orgunitB_ID
            AND objectdefidb=@ContactDefID
            AND objectidb=@ContactID
      -- log deletion
        IF @@ROWCOUNT > 0 AND @EventLogging > 2
          BEGIN
            INSERT hlgtadslog VALUES (@gmtsysdate, @orgunitB_ID, 'ASC_D_0005'
                , 'Alle Assoziationen zwischen der Person '
                + ISNULL(@lastname,'<Kein Name>') + ', '
                + ISNULL(@firstname,'<Kein Name>')
                + ' und anderen Organisationen wurden geloescht.','')
        END
END

-- check for an existing association to the organization
IF NOT EXISTS (SELECT * from hlsysassociation
    WHERE associationdefid=@Person2OrganizationDefID
    AND objectdefida = @orgunitB_DefID
    AND objectida=@orgunitB_ID
    AND objectdefidb = @ContactDefID
    AND objectidb=@ContactID)

BEGIN
    -- new association id
    SELECT @NewID = 0
    EXECUTE @NewID = hlsysgenerateid
    IF @NewID < 0
        BEGIN
            RAISERROR ('Error: GenerateID.',16,1)
            RETURN
    END
    -- insert association
        INSERT hlsysassociation
        VALUES (@NewID, @Person2OrganizationDefID
            , @orgunitB_ID, @orgunitB_DefID
            , @ContactID, @ContactDefID
            , @gmtsysdate, @gmtsysdate,@owner)
     SELECT @NewAssoc = 1
     -- log creation
        IF @EventLogging > 1
            INSERT hlgtadslog VALUES (@gmtsysdate, @NewID, 'ASC_N_0005'
            , 'Zwischen der Person;' + ISNULL(@lastname,'<Kein Name>') + ', '
            + ISNULL(@firstname,'<Kein Name>') +' und der Organisation '
            + ISNULL(@Organisation,'<Kein Name>') + ' in der Kategorie '
            + ISNULL(@Root,'<Kein Name>') + ' wurde eine neue Assoziation angelegt.','')
    END
Separater deassociate_object-Aufruf
Neu Alt 
-- Create and maintain association to contact
SELECT @ContactID = MIN(personid) FROM dbo.contpercomm WHERE emaadd = @UsedBy
IF @ContactID IS NOT NULL
    BEGIN
            
        -- Log deletion of old associations, if they exist
        IF @EventLogging > 2 AND @RemovePersonAsc = 1
            BEGIN
                IF EXISTS (SELECT * FROM dbo.hlsysassociation
                    WHERE associationdefid = @ITSMAssetUSedByDefID
                    AND objectida != @ContactID AND objectdefida = @ContactDefID
                    AND objectidb = @HardwareITSMID AND objectdefidb = @HardwareDefID)
                BEGIN
                    INSERT dbo.hlgthardwareitsmlog VALUES (@gmtsysdate, @HardwareITSMID
                    , 'ASC_D_0002', '','All associations between hardware '
                    + ISNULL(@AssetModel,'<no name>')
                    + ' and other contacts have been deleted')
                END
       END

        -- Log creation of the associations, if it actually is created now
        IF @EventLogging > 1
            BEGIN
                IF NOT EXISTS (SELECT * FROM dbo.hlsysassociation
                WHERE associationdefid = @ITSMAssetUSedByDefID
                    AND objectida = @ContactID AND objectdefida = @ContactDefID
                    AND objectidb = @HardwareITSMID AND objectdefidb = @HardwareDefID)
                    BEGIN
                        INSERT dbo.hlgthardwareitsmlog VALUES (@gmtsysdate, @HardwareITSMID
                        , 'HAIT_A_0002', '', 'The Hardware "' + ISNULL(@AssetModel,'<no name>')
                        + '" with serialnumber "'+ISNULL(@SerialNumber,'<no name>')
                        +'" was added to the contact "'+ ISNULL(@UsedBy,'<no name>') +'"')
                    END
            END

            -- Create and maintain association to contact
            EXEC hlapi_userimport_associateobject @ActionContext
                , @ITSMAssetUSedByDefID
                , @DefType Person, @ContactID, @ContactDefID
                , @DefTypeProduct, @HardwareITSMID, @HardwareDefID
                , @RemovePersonAsc, 0, 0
END
 
-- Create and maintain association to contact
SELECT @ContactID = MIN(personid) FROM dbo.contpercomm WHERE emaadd = @UsedBy
IF @ContactID IS NOT NULL
    BEGIN
        IF NOT EXISTS (SELECT * FROM dbo.hlsysassociation
            WHERE associationdefid = @ITSMAssetUSedByDefID
            AND objectida = @ContactID AND objectdefida = @ContactDefID
            AND objectidb = @HardwareITSMID AND objectdefidb = @HardwareDefID)
        BEGIN

            -- Create new object id for the association
            SELECT @NewID = 0
            EXECUTE @NewID = dbo.hlsysgenerateid
            IF @NewID < 0
                BEGIN
                    RAISERROR ('Error: GenerateID.',16,1)
                    RETURN
                END

                -- Create association
                INSERT dbo.hlsysassociation VALUES (@NewID, @ITSMAssetUSedByDefID
                    , @ContactID, @ContactDefID
                    , @HardwareITSMID, @HardwareDefID
                    , @gmtsysdate, @gmtsysdate,@owner)
                IF @EventLogging > 1
                    INSERT dbo.hlgthardwareitsmlog VALUES (@gmtsysdate, @HardwareITSMID
                    , 'HAIT_A_0002', '', 'The Hardware "' + ISNULL(@AssetModel,'<no name>')
                    + '" with serialnumber "'+ISNULL(@SerialNumber,'<no name>')
                    + '" was added to the contact "'+ ISNULL(@UsedBy,'<no name>') +'"')
           END

            -- Delete associations to other contacts
            IF @RemovePersonAsc = 1
                BEGIN
                    DELETE FROM dbo.hlsysassociation WHERE associationdefid = @ITSMAssetUSedByDefID
                        AND objectida != @ContactID AND objectdefida = @ContactDefID
                        AND objectidb = @HardwareITSMID AND objectdefidb = @HardwareDefID
                -- Log deletion
                IF @@ROWCOUNT > 0 AND @EventLogging > 2
                    BEGIN
                        INSERT dbo.hlgthardwareitsmlog VALUES (@gmtsysdate, @HardwareITSMID
                        , 'ASC_D_0002', '','All associations between hardware'
                        + CONVERT(NVARCHAR(10), @AssetModel)
                        + ' and other contacts have been deleted')
                    END
               END
END

Assoziationen löschen

Die Prozedur hlapi_userimport_deassociateobject ist kein Ersatz für alle DELETE-Statements die zuvor im Script verwendet wurden. Die meisten Assoziationen können über die Funktion Move in der hlapi_userimport_deassociateobjectt API gelöscht werden, wie zuvor beschrieben.

Mit der neuen Prozedur besteht keine Möglichkeit mehr, mehrere Assoziationen gleichzeitig zu löschen. Es muss für jede Assoziation die gelöscht werden soll ein separater Aufruf der Prozedur erfolgen. In der Regel ist dazu die Verwendung eines Cursors notwendig.
Entfernen von leeren Organisationen in AD-Importen
Neu Alt 
DECLARE     c3Assoc CURSOR FAST_FORWARD FOR
SELECT      a.associationdefid, a.objectida, a.objectdefida, a.objectidb, a.objectdefidb
            FROM hlsysassociation a
            WHERE a.objectidb=@ID
OPEN c3Assoc
FETCH NEXT FROM c3Assoc INTO @AssociationDefID
            , @ObjectIDA, @ObjectDefIDA
            , @ObjectIDB, @ObjectDefIDB
WHILE @@FETCH_STATUS = 0
    BEGIN
        EXEC hlapi_userimport_deassociateobject @ActionContext
            , @AssociationDefID
            , @ObjectIDA, @ObjectDefIDA
            , @ObjectIDB, @ObjectDefIDB
        FETCH NEXT FROM c3Assoc INTO @AssociationDefID
            , @ObjectIDA, @ObjectDefIDA
            , @ObjectIDB, @ObjectDefIDB
    END
CLOSE c3Assoc
DEALLOCATE c3Assoc
 
DELETE hlsysassociation WHERE objectidb=@ID
Remove Software from Computers in Software Import
Neu Alt 
--Delete assocation between hardware and software that has not been created or updated in this run
DECLARE c2 CURSOR FAST_FORWARD FOR
    SELECT a.objectida, a.objectidb
    FROM @Assocations a
OPEN c2
FETCH NEXT FROM c2 INTO @HardwareITSMID, @SoftwareITSMID

WHILE @@FETCH_STATUS = 0
BEGIN
    EXEC hlapi_userimport_deassociateobject @ActionContext
        , @SoftwareITSMInstalledOn
        , @HardwareITSMID, @HardwareDefID
        , @SoftwareITSMID, @SoftwareDefID
    FETCH NEXT FROM c2 INTO @HardwareITSMID, @SoftwareITSMID
END

CLOSE c2
DEALLOCATE c2
 
--Delete assocation between hardware and software that has not been created or updated in this run
DECLARE c2 CURSOR FAST_FORWARD FOR
    SELECT associationid FROM dbo.hlsysassociation a
            INNER JOIN dbo.hlgtsoftwareitsmdictionary dict ON a.objectidb = dict.objectid
    WHERE a.associationdefid = @SoftwareITSMInstalledOn
        AND a.objectdefida = @HardwareDefID
        AND a.objectdefidb = @SoftwareDefID
        AND a.lastmodified != @gmtsysdate
OPEN c2
FETCH NEXT FROM c2 INTO @AssociationID

WHILE @@FETCH_STATUS = 0
BEGIN
        DELETE FROM dbo.hlsysassociation WHERE associationid = @AssociationID
        FETCH NEXT FROM c2 INTO @AssociationID
END

CLOSE c2
DEALLOCATE c2