Witamy w kolejnej części serii artykułów o API ServiceDesk Plus. Jak do tej pory, przedstawiliśmy sposób w jaki można założyć proste zgłoszenie za pomocą API oraz jak utworzyć zgłoszenie z dość niestandardową treścią. Teraz przyszedł czas na automatyczne zamykanie zgłoszeń 🙂
W tym artykule zaprezentujemy sposób w jaki można zamknąć zgłoszenie. W pierwszej części przedstawiony skrypt ma zastosowanie w przypadku integracji aplikacji zewnętrznej, natomiast druga część to przykład zaplanowanego zadania, uruchamianego cyklicznie tak, aby być na bieżąco z nowymi informacjami. W tej cześci zajmiemy się wyzwalaniem niestandardowych akcji – w tym wypadku automatyczne zamykanie zgłoszeń.
Założenia
Jak wiadomo, w aplikacji możemy ustawić statusy rozwiązania zgłoszenia, zamknięcia oraz okres przejścia z jednego statusu w drugi. W większości implementacjach jest taki mechanizm, że po rozwiązaniu zgłoszenia, daje się zgłaszającemu jakiś czas na zgłoszenie ewentualnych poprawek co do rozwiązania danego problemu. Po tym czasie – zazwyczaj 🙂 – nie chcemy by tworzyły się kolejne zgłoszenia, powodując tym samym wzrost wpływu zgłoszeń. I właśnie tym przypadkiem zajmiemy się w tej części.
Tworzymy skrypt
Etap 1: Przygotowanie
W naszym przykładzie automatyczne zamykanie zgłoszenia będzie składać się z trzech elementów: dwa informacyjne (dodanie publicznej notatki o przyczynie zamknięcia zgłoszenia oraz odpowiedź do zgłaszającego) i jeden zamykający zgłoszenie. Na pierwszy rzut oka może wydawać się to dość skomplikowane, ale w rzeczywistości takie nie jest. Pisanie skryptu zaczniemy od ustawienia wszystkich parametrów potrzebnych do przeprowadzenia operacji.
Uwaga: wartość przy zmiennej $closeStatus musi być identyczna jak w aplikacji – spacja w spację, literka w literkę
# przechowanie danych zgłoszenia w pliku json param ( $json = "none" ) # wydobywamy interesujące nas dane $jsondata = Get-Content $json $obj = ConvertFrom-Json $jsondata # i przypisujemy wartości do zmiennych $reqid = $obj.request.WORKORDERID # ID zgłoszenia $requester = $obj.request.REQUESTER # Zgłaszający $title = $obj.request.SUBJECT # Tytuł zgłoszenia # parametry do zapytań API SDP $isPublic = "true" # Ustawiamy parametr publiczny dla notatki, jeśli ma być prywatna ustawiamy wartość na "false" $noteTxt = "Przeprowodzono autozamykanie zgłoszenia. Powód: Odpowiedź na zgłoszenie po upływie 14 dni roboczych na weryfikację poprawności realizacji." # Treść notatki / wiadomości $closeStatus = "Closed" # Nazwa statusu zamykającego zgłoszenie # parametry połączenia do API SDP $sdphost = "http://sdp.sdpadmins.local:8080/" # adres ServiceDesk $techkey = "[techniciankey]" # klucz API technika - do wygenerowania w aplikacji $url = $sdphost + "sdpapi/request/" + $reqid # adres wskazujący na zapytanie API $method = "POST" # metoda wysyłania danych WebRequest'a # operacje na zgłoszeniach poprzez API SDP (OPERATION_NAME) $addnote = "ADD_NOTE" # dodawanie notatki $editrequest = "EDIT_REQUEST" # edycja zgłoszenia - potrzebna do zmiany statusu $reply = "REPLY_REQUEST" # odpowiedź do zgłoszenia
Sporo tego, czyż nie? 🙂
Ponieważ będziemy potrzebować adresu e-mail zgłaszającego, znajdującego się w profilu użytkownika SDP, musimy jeszcze do kolekcji parametrów dopisać namiary bazy danych – w naszym przykładzie baza danych jest oparta na Microsoft SQL Server.
# parametry połączenia do bazy danych SDP $sqlServer = "adres serwera db" $sqlName = "baza danych" $sqlUser = "user" $sqlPwd = "hasło" # budujemy connection string $sqlConnection = "Server = $sqlServer; Database = $sqlName; User ID=$sqlUser; Password=$sqlPwd; Connect Timeout=10"
Uwaga: Podany w parametrach użytkownik, musi mieć uprawnienia do odczytu danych z bazy danych SDP.
Etap 2: Funkcje
Ponieważ autozamykanie zgłoszenia ma charakter wieloetapowy, dla naszej wygody, niektóre funkcje rozbijemy na dwie odrębne. Dzięki temu unikniemy funkcji składających się z dużej liczby linijek oraz uzyskamy swego rodzaju uniwersalność tych funkcji, a co za tym idzie, możliwość wykorzystania w przyszłości.
Funkcje zapytania SQL
Pierwszymi funkcjami jakim się zajmiemy to wyciągnie adresu e-mail zgłaszającego. Jak wiadomo, odpowiadając na zgłoszenie będące w statusie zamkniętym tworzy się nowe zgłoszenie z danymi osoby, która na dane zgłoszenie odpowiedziała.
Najpierw napiszemy funkcję, która wykona zapytanie. Jej działanie polega na utworzeniu obiektu połączenia SQL o parametrach podanych w zmiennych na początku pliku skryptu. Następnie tworzymy obiekt wykonujący zapytanie. Kolejnym krokiem jest pobranie wyników do obiektu DataSet.
# funkcja wykonująca zapytanie SELECT bazy danych
function dbSelect($query, $connection)
{
$sqlConnect = New-Object System.Data.SqlClient.SqlConnection
$sqlConnect.ConnectionString = $connection
$sqlConnect.Open()
$sqlQuery = New-Object System.Data.SqlClient.SqlCommand
$sqlQuery.CommandText = $query
$sqlQuery.Connection = $sqlConnect
$sqlQuery.CommandTimeout = 10
$sqlAdapter = New-Object System.Data.SqlClient.SqlDataAdapter
$sqlAdapter.SelectCommand = $sqlQuery
$sqlResult = New-Object System.Data.DataSet
$sqlAdapter.Fill($sqlResult)
$sqlConnect.Close()
return $sqlResult
}
Drugą funkcją zapytania SQL jest już właściwe jego wykonanie. Jest to prosta funkcyjka, która wyszuka nam interesujący nas adres e-mail na podstawie zgłoszenia.
# funkcja wyszukująca adres e-mail zgłaszającego
function dbRequesterMail($id)
{
$query = "SELECT aaacontact.EMAILID 'email' FROM WorkOrder wo
LEFT JOIN SDUser sdu ON wo.REQUESTERID=sdu.USERID
LEFT JOIN AaaUser aau ON sdu.USERID=aau.USER_ID
LEFT JOIN AaaUserContactInfo aaausercontact ON aau.USER_ID=aaausercontact.USER_ID
LEFT JOIN AaaContactInfo aaacontact ON aaausercontact.CONTACTINFO_ID=aaacontact.CONTACTINFO_ID
where wo.workorderid = $id"
$select = dbSelect -query $query -connection $sqlConnection
$requesterMail = $select.Tables[0] | Select-Object -expandproperty email
return $requesterMail
}
W ten oto sposób uzyskujemy adres nadawcy odpowiedzi do zgłoszenia.
Funkcje API ServiceDesk Plus
Jak narazie zajmowaliśmy się zbieraniem potrzebnych danych. Na tym etapie mamy już wszystko co potrzebne do przeprowadzenia autozamykania zgłoszenie. Funkcje będziemy pisać w kolejności zgodnej ze schematem podanym na etapie przygotowań.
# funkcja dodająca notatkę
function addNote($pub, $txt)
{$inputdata = @{"operation" = @{"details" = @{"notes" = @{"note" = @{"ispublic" = "$pub"; "notestext" = "$txt"}}}}}
$params = @{INPUT_DATA=$inputdata;OPERATION_NAME=$addnote;TECHNICIAN_KEY=$techkey;format='json'}
$result = Invoke-WebRequest -UseBasicParsing -Uri "$url/notes" -Method POST -Body $params
return $result
}
# funkcja odpowiedzi do zgłoszenia
function replyRequest($to, $subject, $body)
{
$inputdata = @{"operation" = @{"details" = @{"to" = "$to"; "subject" = "$subject"; "description" = "$body"}}}
$params = @{INPUT_DATA=$inputdata;OPERATION_NAME=$reply;TECHNICIAN_KEY=$techkey;format='json'}
$result = Invoke-WebRequest -UseBasicParsing -Uri $url -Method POST -Body $params
return $result
}
# funkcja zmieniająca status zgłoszenia
function changeStatus($status)
{
$inputdata = @{"operation" = @{"details" = @{"status" = "$status" }}}
$params = @{INPUT_DATA=$inputdata;OPERATION_NAME=$editrequest;TECHNICIAN_KEY=$techkey;format='json'}
$result = Invoke-WebRequest -UseBasicParsing -Uri $url -Method $method -Body $params
retrun $result
}
Teraz wystarczy tylko wywołać funkcje i ustawić parametry Wyzwalacza niestandardowego (Custom trigger)
# dodajem notatkę addNote -pub "$isPublic" -txt "$noteTxt" # pobieramy adres e-mail $email = dbRequesterMail -id "$reqid" # wysyłamy wiadomość o autozamknięciu zgłoszenia replyRequest -to "$email" -subject "Automatyczne zamknięcie zgłoszenia $reqid" -body "$noteTxt" # zamykamy zgłoszenie changeStatus -status "$closeStatus"
W panelu administracji musimy ustawić jeszcze parametry uruchomienia wyzwalacza niestandardowego. W sekcji Wykonaj działanie ustawiamy Przy tworzeniu zgłoszenia oraz W dowolnym momencie. W kryteriach ustawiamy parametry Temat Zawiera i w polu wartość wpisujemy temat zgodny ze schematem. Jeśli mamy coś w stylu [RE: Zgloszenie zostało rozwiązane – ##<nr_zgloszenia>##] to wpisujemy RE: Zgloszenie zostało rozwiązane. Na potrzeby testów można tymczasowo wpisać np. test autoclose i wysłać po prostu maila do naszego ServiceDesk’a. W polu wykonywania skryptu wpisujemy
powershell.exe -WindowStyle Hidden -file c:\ManageEngine\ServiceDesk\integration\custom_scripts\autoclose.ps1 $COMPLETE_JSON_FILE
I możemy testować działanie 🙂