CallAPIMethodActivity - Aufruf vordefinierter und eigener API-Methoden

In Serviceware Processes können Sie sowohl vordefinierte APIs verwenden und als auch im Ihre eigenen APIs im Activity Designer definieren.

API ist die Abkürzung für Application Programming Interface und stellt die Programmierschnittstelle der Processes-Workflow-Software zu anderen Programmen dar.

Die gewünschten APIs können dann über die Aktivität API-Methode ausführen (Gruppe helpLine Activities) oder in einem Instruction Set über die Methode InvokeAPIMethod eingebunden werden.

Anmerkung: Die APIs, die beispielsweise einen TheCase-Parameter enthalten, also einen Parameter, der ein helpLine Objekt anspricht, können nur verwendet werden, wenn sie innerhalb einer Aktivität (im Instruction Set) aufgerufen werden, die dieses Objekt bereits geladen haben.

Beispielhaft müssen die folgenden Schritte ausgeführt werden.

Ziehen Sie die Aktivität oder die Methode in den Workflow bzw. in das Instruction Set.
Fügen Sie zwei Properties hinzu:

APIType

Über Anwahl des Ausrufezeichens hinter dem Parameternamen werden die vordefinierten Typen angezeigt. Hinter den meisten Einträgen verbergen sich mehrer Methoden. Wenn Sie beispielsweise die API für Kalendermethoden anwählen (CalendarCalculatorAPI) auswählen, werden die verfügbaren Methoden in der MethodName-Eigenschaft angezeigt.

MethodName

Der Auswahl der Methoden ist abhängig vom APIType.

Nachdem Sie eine Methode angewählt haben, werden die zu bindenden Parameter im Eigenschaftsbereich angezeigt. Im Beispiel wird nach Auswahl der Kalendermethode IncrementSolutionTimeOffset eingetragen.
Nach Auswahl der Methode werden weitere Parameter hinzugefügt - in diesem Beispiel TheCase und toAdd. Diese müssen Sie an die entsprechenden Objekte binden bzw. mit den gewünschten Werten belegen.

Im nächsten Abschnitt finden Sie die vordefinierten API-Methoden inkl. der Parameterbeschreibung.

CalenderAPI-Methoden

Diese vordefinierte Arbeitszeitkalendermethode greift auf die hinterlegten Arbeitszeiten von Agenten zu.

GetNextWorkingTime: Gibt die nächste reguläre Arbeitszeit des zugewiesenen Agenten zurück.; Rückgabewerte: hlCase, offset, referenceTime

CalendarCalculatorAPI – Kalendermethoden

Diese vordefinierten Kalendermethoden greifen auf die Reaktionszeit (ReactionTime) oder die Lösungszeit (SolutionTime) zu. APIs, die auf ein helpLine Objekt zugreifen, können nur innerhalb einer Aktivität im Instruction Set aufgerufen werden, die dieses Objekt bereits enthält.

IncrementSolutionTimeOffset: Addiert die Zeitspanne (ToAdd) auf die schon vorhandene SolutionTime.; TheCase: Vorgangsobjekt, dessen SolutionTime inkrementiert werden soll; ToAdd: Format [-]hhhh:mm:ss
IncrementReactionTimeOffset: Addiert die Zeitspanne (ToAdd) auf die schon vorhandene ReactionTime.; TheCase: Vorgangsobjekt, dessen ReactionTime inkrementiert werden soll; ToAdd: im Format [-]hhhh:mm:ss
SetReactionTimeOffset: Setzt die ReactionTime.; Offset: Format [-]hhhh:mm:ss; TheCase: Vorgangsobjekt, dessen ReactionTime gesetzt werden soll.
SetSolutionTimeOffset: Setzt die SolutionTime.; Offset: Format [-]hhhh:mm:ss; TheCase: Vorgangsobjekt, dessen SolutionTime gesetzt werden soll.
CaluclateOffset: Berechnet den Offset; ReturnValues:; ReferenceTime; RelativeTime; TheCase: Vorgangsobjekt, dessenSolutionTime gesetzt werden soll.

InternalTaskAPI – Methoden

Internal TaskAPI.

AllTasksClosed: ReturnValue: Identity

LogAPI - Methoden

LogAPIs eignen sich bei der Erstellung von Workflows, um die Attribut-Belegungen, die während des Workflows vorgenommen werden, zu überprüfen.

TrackValue: Schreibt einen Wert in die Benutzer Events (UserEvent) Liste.; Key: Der Schlüssel, der in der UserEventList angezeigt wird; Value: Der Wert; Beispiel: In einem Update-Instruction Set eingegebene Anweisungen…

und die zugehörige UserEventListe:

Diese erhalten Sie, indem Sie im Kontextmenü der WF-Definition Zeigt laufende Instanzen wählen und

im darauf eingeblendeten Dialog das dritte Icon von rechts wählen.
TrackText: Schreibt einen Wert in die Benutzer Events (UserEvent) Liste.; Key: Der Schlüssel, der in der UserEvent Liste angezeigt wird; Value: Der Wert des Schlüssels
LogText: Diese Methode ist eine Textausgabe, die einen Parameter enthalten kann.; Format: Text, in dem der Parameter mit {0} eingebunden ist.; LogType: Typ des Logs; Parameter1: Der auszulesende Parameter; Beispiel: Ausgabe des Vorgangstyps im EventLog mit Kennung WFEvents

und zugehöriger Eintrag im EventLog (Ereignisanzeige/Anwendung).
LogN: N=Anzahl der Parameter; Diese Methode ist eine Textausgabe, die mehrere Parameter enthalten kann.; Format: Text: Parameter werden mit {0} bis {N-1} angegeben.; LogType: Wohin gelogged werden soll; Parameter1-N: Die Parameterwerte; Source: Wenn LogType gleich EventLog ist, steht hier die Source des Eventlogs.

MailAPI

Voraussetzung für das SEnden und Empfangen von Mails im Workflow ist die Installation und Konfiguration von Connectivity.

SendTextMail: Eine E-Mail wird an eine Liste von Personen (allgemein helpLine Objekte) gesendet. In den Personen wird die Standard E-Mail-Adresse gesucht und der E-Mail-Text an die entsprechenden Personen versandt.; Bcc: Blinder 2. Empfänger, Liste von Personen, Rollen, Gruppen, Agenten; Body: Mail-Text; Cc: 2. Empfänger, Liste von Personen, Rollen, Gruppen, Agenten; From: E-Mail-Adresse des Senders; Subject: Betreff, Text; To: Empfänger, Liste von Personen, Rollen, Gruppen, Agenten
SentHtmlMail: Eine E-Mail wird im HTML-Format an eine Liste von Personen (allgemein helpLine Objekte) gesendet. In den Personen wird die Standard E-Mail-Adresse gesucht und der E-Mail-Text an die entsprechenden Personen versandt.; Bcc: Blinder 2. Empfänger, Liste von Personen, Rollen, Gruppen, Agenten; Body: Mail-Text; Cc: 2. Empfänger, Liste von Personen, Rollen, Gruppen, Agenten; From: E-Mail-Adresse des Senders; Subject: Betreff, Text; To: Empfänger, Liste von Personen, Rollen, Gruppen, Agenten

PrincipalAPI

GetSupporterPrincipalInfoByName: Gibt einen AgentPrincipal durch Eingabe eines Namens zurück.; ReturnValue: PrincipalInfo; SupporterName: Der Name des Supporters.
GetSupporterPrincipalInfoByReference: Gibt einen AgentPrincipal durch Eingabe einer Referenz zurück.; ReturnValue: PrincipalInfo; SupporterInstance: Der Name des Supporters.
GetRolePrincipalInfoByName: Gibt die Rolle durch Eingabe eines Namens zurück.; ReturnValue: PrincipalInfo; RoleName: Rolle
GetGroupPrincipalInfoByName: Gibt die Gruppe durch Eingabe eines Namens zurück.; ReturnValue: PrincipalInfo; GoupName: Gruppe

ServiceSupportAPI

CopyProductServices: Kopiert einen Service; Target:
AddAsserToProcessService: Target:
AddAssetToAffectedServices: Target:
AddKBArticleToAffectedServices: Target:

StringFormattingAPI

Format1 – Format5

Diese Methode(n) formatieren einen String mit bis zu 5 Parametern. Anzahl der Formatierungsparameter werden im Text mit {0} bis {4} angegeben; {0} entspricht dem PlaceHolder1, {1} dem PlaceHolder2“, usw.:

Anmerkung: Für Workflows werden kein EBL ausgeführt. Das bedeutet u.a., dass der Text im Feld/Register Übersicht (Attribut CaseGeneral.Overview) von Incidents (in ITIL) NICHT gefüllt wird und somit Workflow-Incidents bei der Vorgangssuche nicht gefunden werden. Verwenden Sie daher die StringFormatting API, um am Ende der Activities das Übersichtsfeld mit den gewünschten Vorgangstexten selbst zu füllen.

Beispiel 1: Aneinanderhängen vom Feld Überblick (CaseGeneral.Overview), dem Beschreibungstext (CaseDescription.DescriptionText) und dem Lösungstext (CaseSolution.SolutionText) und Hineinschreiben wiederum in das Überblickfeld.

hlObj.CaseGeneral.Overview = StringFormattingAPI.Format3
(ctx, "{0} {1} {2}",
hlObj.CaseGeneral.Overview, hlObj.CaseDescription.DescriptionText, hlObj.CaseSolution.SolutionText);

Beispiel für die Anwendung der StringFormattingAPI im Instruction Set, um Texte aneinanderhängen und in ein Feld schreiben zu können.

Ziehen Sie die Methode InvokeApiMethod in ein Instruction Set und wählen Sie die StringFormattingAPI aus den Helpline.Workflow.Activities.
Wählen Sie die Format2-Methode, da zwei Texte zusammengefügt werden sollen.

Es werden zwei Platzhalter zur Verfügung gestellt.
Bestimmen Sie den Format-String bestimmt.
Verwenden Sie zur Einbindung der Platzhalter geschweifte Klammern und eine nullbasierte Nummerierung.
Erstellen Sie zwei durch ein Semikolon getrennt eingaben für zwei Texte.
Geben Sie die Attribute für die beiden Platzhalter, d.h. der zu verwendenden Textfelder an.
Geben Sie an, in welches Feld/Attribut diese Verkettung geschrieben werden soll.

Zwei Texte wurden zusammengefügt in ein Feld geschrieben.

HLCaseSupport - Methoden für Vorgangsobjekte

Die nachfolgend aufgelisteten Support-Methoden bieten Ihnen die Möglichkeit, auf helpLine Objekte zuzugreifen.

Anmerkung: Verwenden Sie diese Methoden ausschließlich im Activity Designer und NICHT in den Instruction Sets.

GetCaseRead: Gibt einen Vorgang zum Lesezugriff zurück.; ReturnValue: Der zurückgegebene Vorgang; Identity: Die Identität des Vorgangs
GetCaseWrite: Gibt einen Vorgang zum Lese- und Schreibzugriff zurück; ReturnValue: Der zurückgegebene Vorgang; Identity: Die Identität des Vorgangs; Achtung: Auf einen Vorgang darf schreibend nur in der zugehörigen Workflow-Instanz zugegriffen werden. Ein schreibender Zugriff auf Vorgänge fremder Workflow-Instanzen ist nicht zulässig.
AppendCaseSU: Hängt eine ServiceUnit (SU) an.; ReturnValue: Die neue SU; hlCase: Der Vorgang, an den die SU angehängt werden soll
CommitCaseChanges: Spiechert den Vorgang; hlCase: Der Vorgang, der gespeichert werden soll; ReleaseOnChange: True/False legt fest, ob der Vorgang nach Beenden der Methode freigegeben werden soll (True) oder nicht (False)
CreateCase: Erzeugt einen neuen Vorgang; ReturnValue: Der erzeugte Vorgang; TypeOfCase: Vorgangstyp, der erzeugt werden soll
AreAllChildCasesClosedOrSolved: Diese Boolean Methode prüft, ob dem aktuellen Workflow andere, nicht abgeschlossene Vorgänge oder Workflows assoziiert sind.; AreAllChildCasesClosedOrSolved(ICodeContext context, Case theCase,AssociationChildCollection children); theCase: Der Ausgangsvorgang; AssociationChildCollection: Association --> Die B Rolle des zugeordneten Cases.; Der bool’sche Wert gibt zurück, ob alle Vorgänge am anderen Ende der Assoziation geschlossen oder gelöst sind (INTERNALSTATECLOSED oder SOLVED).; HLPersonSupport – Methoden für Personenobjekte

HLPersonSupport – Methoden für Personenobjekte

GetPersonRead: Gibt ein Personenobjekt zum Lesezugriff zurück.; ReturnValue: Das zurückgegebene Personenobjekt; Identity: Die Identität des Personenobjekts
GetPersonWrite: Gibt ein Personenobjekt zum Lese- und Schreibzugriff zurück.; (ReturnValue): Das zurückgegebene Personenobjekt; Identity: Die Identität des Personenobjekts
CommitPersonChanges: Speichert das Personenobjekt; PersonToCommit: Personenobjekt, das gespeichert werden soll.
CreatePerson: Erzeugt ein neues Personenobjekt.; ReturnValue: Das erzeugte Personenobjekt; TypeOfPerson: Personentyp (Employee oder ExternalPerson), der erzeugt werden soll.

DisplaySupport – Methoden für Anzeigenamen

GetTypeDisplayName

Gibt den Anzeigenamen eines von helpLine generierten Objekttyps zurück.

Syntax: GetTypeDisplayName(ICodeContext ctx, Type objType, int lcid)

Parameter:

ICodeContext ctx: Kontext, in dem die Methode aufgerufen wird
Type objType: Typ des Objekts, dessen Anzeigename bestimmt werden soll
int lcid: Sprache, in der der Anzeigename ausgegeben werden soll

Rückgabewert: Anzeigename

GetInstanceDisplayName

Gibt den Anzeigenamen des Werts eines Felds zurück ( beispielsweise Schlagwort oder Listenattribut).

Syntax: GetTypeDisplayName(ICodeContext ctx, object obj, int lcid)

Parameter:

ICodeContext ctx: Kontext, in dem die Methode aufgerufen wird
object obj: Objekt, dessen Anzeigename bestimmt werden soll
int lcid: Sprache, in der der Anzeigename ausgegeben werden soll

Rückgabewert: Anzeigename

TwitterSupportAPI

SendNewReply: Veröffentlicht einen Artikel auf Twitter.; SendAsPrivate: True/False legt fest, ob der Artikel als „privat“ veröffentlicht werden soll (True) oder nicht (False); TweetText: Der Inhalt, der im Tweet eingefügt werden soll.

SupporterAPI

GetSupporterByID: Gibt den Supporter mit der angebenen ID zurück.

WorkflowActivationAPI

Da zur Verwendung der beiden Methoden StartWorkflow und StartWorkflowWithRelatedObject weitere Konfigurationen und Einstellungen erforderlich sind, lesen Sie hierzu den Abschnitt Workflow aus Workflow starten.

WorkflowProcessLifetimeAPI

UpdateEndTimeToNow