IBM TRIRIGA Application Platform Wersja 3 Wydanie 4.2. OSLC Podręcznik integracji IBM

IBM TRIRIGA Application Platform Wersja 3 Wydanie 4.2 OSLC Podręcznik integracji IBM

Uwaga Przed użyciem niniejszych informacji i produktu, którego one dotyczą, należy zapoznać się z treścią sekcji Uwagi na stronie 31. Niniejsze wydanie dotyczy wersji 3, edycji 5, modyfikacji 0 produktu IBM TRIRIGA Application Platform oraz wszystkich kolejnych edycji i modyfikacji, dopóki w nowych wydaniach nie zostanie wskazana inna wersja i edycja. Copyright IBM Corporation 2014, 2015.

Spis treści Rozdział 1. Integracja danych przy użyciu specyfikacji OSLC....... 1 Rozdział 2. Integracja w roli konsumenta OSLC................ 3 Komponenty OSLC............. 3 Terminologia OSLC........... 3 Dostawcy usług i ich wykrywanie....... 4 Przestrzenie nazw OSLC.......... 5 Operacje i zasoby OSLC.......... 5 Kształty zasobów............ 6 Dokumenty kształtu........... 7 Znaczniki ETag............ 10 Identyfikatory URI IBM TRIRIGA dla OSLC... 11 Rozdział 3. Praca z zasobami OSLC.. 13 Zapytania dot. zasobów OSLC......... 13 Zapytanie z użyciem metod GET lub POST.... 13 Parametry zapytania OSLC......... 14 Tworzenie zasobów OSLC.......... 17 Tworzenie rekordów zależnych od rekordów głównych 18 Aktualizacja zasobów OSLC......... 19 Metoda HTTP PUT........... 19 Metoda HTTP PATCH.......... 21 Usuwanie zasobów OSLC.......... 23 Praca z załącznikami i danymi binarnymi...... 23 Przetwarzanie załączników OSLC....... 23 Przetwarzanie danych binarnych OSLC..... 25 Rozdział 4. Zarządzanie zasobami OSLC 27 Zabezpieczenia OSLC........... 27 Zmiany haseł............. 27 Nieaktualne hasła............ 28 Rejestrowanie OSLC............ 28 Rozdział 5. Rozwiązywanie problemów z OSLC.............. 29 Objaśnienia kodów HTTP specyfikacji OSLC.... 29 Uwagi............... 31 Znaki towarowe............. 33 Warunki dotyczące dokumentacji produktu..... 33 Oświadczenie IBM o ochronie prywatności w Internecie 34 Copyright IBM Corp. 2014, 2015 iii

iv Copyright IBM Corp. 2014, 2015

Rozdział 1. Integracja danych przy użyciu specyfikacji OSLC Aplikacje produktu i niektóre aplikacje zewnętrzne mogą integrować i udostępniać sobie nawzajem dane w oparciu o specyfikację integracji Open Services for Lifecycle Collaboration (OSLC). OSLC ułatwia techniczną współpracę i wymianę danych między narzędziami. Działając zgodnie z regułami i metodami opisanymi w specyfikacji, aplikacje mogą wykonywać operacje tworzenia, żądania, aktualizowania i usuwania na zasobach innej aplikacji. Społeczność OSLC zrzesza twórców oprogramowania i instytucje współpracujące przy standaryzacji wymiany danych między narzędziami do zarządzania cyklem życia zasobów. Do danych tych należą na przykład wymagania, informacje o usterkach, scenariusze tekstowe i historie zmian. Integracja OSLC aplikacji może odbywać się w oparciu o wersję 2.0 specyfikacji OSLC. Sama specyfikacja wraz z innymi zasobami OSLC dostępna jest w sieci WWW> Integracja OSLC realizowana jest między aplikacją konsumencką a zewnętrzną aplikacją dostawcy. Aplikacja dostawcy OSLC udostępnia dane o swoich zasobach aplikacji konsumenckiej za pośrednictwem kontenerów nazywanych dostawcami usług. Dzięki dostępności danych o zasobach aplikacja konsumencka może tworzyć powiązania między swoimi danymi a danymi zasobów aplikacji dostawcy. Każda aplikacja w produkcie może po odpowiednim skonfigurowani działać jako aplikacja konsumencka OSLC. Aplikacje konsumenckie mogą uzyskiwać identyfikatory URI zasobów w aplikacji dostawcy i na podstawie tych identyfikatorów żądać, na przykład, wyników zapytań. Dostawcy usług IBM TRIRIGA są dostępny pod adresem http://twoj_serwer/oslc/sp. Identyfikatory URI używane w żądaniach OSLC muszą być kodowane jako URL. Copyright IBM Corp. 2014, 2015 1

2 Copyright IBM Corp. 2014, 2015

Rozdział 2. Integracja w roli konsumenta OSLC Aplikacja, konsument OSLC, może być skonfigurowana do obsługi dwóch typów interakcji: zapytań i tworzenia. Aplikacja konsumencka uzyskuje odsyłacze do zasobów od aplikacji dostawcy. Poniższy rysunek przedstawia interakcje między aplikacją konsumencką a aplikacją dostawcy. Aplikacja konsumencka OSLC może pytać o zasoby lub tworzyć zasoby w aplikacji dostawcy i zachowywać dla siebie odsyłacze do tych zasobów. Za pośrednictwem odsyłaczy aplikacja konsumencka może kierować do aplikacji dostawcy żądania zapytań, aktualizacji lub usuwania zasobów. Komponenty OSLC Dostawcy usług, zasoby i znaczniki ETag to informacje potrzebne do konsumowania danych IBM TRIRIGA za pośrednictwem OSLC. Terminologia OSLC W przypadku terminów dotyczących rozwiązania IBM TRIRIGA1 OSLC przedstawione są definicje. aplikacja konsumencka Aplikacja wykorzystująca dane w głównej hurtowni danych do określonych zastosowań biznesowych. fabryka tworzenia Identyfikator URI używany do tworzenia nowych zasobów za pomocą metody HTTP POST. aplikacja dostawcy W kontekście OSLC aplikacja udostępniająca dane o swoich zasobach aplikacji konsumenckiej za pośrednictwem kontenerów nazywanych dostawcami usług. Rozwiązanie IBM TRIRIGA jest aplikacją dostawcy dla aplikacji mobilnych the IBM TRIRIGA Anywhere. rekord dostawcy Rekord identyfikujący aplikację dostawcy i zawierający definicje dla co najmniej jednej interakcji OSLC między aplikacją konsumencką i aplikacją dostawcy. Copyright IBM Corp. 2014, 2015 3

publiczny identyfikator URI Główny identyfikator URI używany w celu uzyskania dostępu do aplikacji dostawcy OSLC. funkcja zapytania Podstawowy identyfikator URI służący do tworzenia URI zasobów zapytań. zasób W kontekście OSLC jest to sieciowy obiekt danych lub usługa, którą można zidentyfikować za pomocą identyfikatora URI. Resource Description Framework (RDF) Struktura reprezentowania informacji w Internecie. kształt zasobu Specyfikacja definiująca stałą listę właściwości zasobu, oczekiwane typy danych i wartości oraz reguły sprawdzania poprawności w przypadku nowych lub zmienionych zasobów. typ zasobu W kontekście OSLC jest to typ danych połączonych między zintegrowanymi aplikacjami, przykładowo może to być zlecenie zmiany statusu zadania roboczego. dostawca usług W kontekście OSLC jest to kontener zasobów zawarty w narzędziu lub produkcie w celu zapewnienia możliwości korzystania z danego zasobu. dokument kształtu Rekord opisujący kształt zasobu i udostępniający go za pomocą identyfikatora URI. Dostawcy usług i ich wykrywanie Dostawca usług to kontener lub kolekcja zasobów utrzymywana i udostępniana przez narzędzie lub produkt. Dostawcy usług są środkiem do grupowania podobnych zasobów, takich jak defekty lub zadania, które mogą być konfigurowane na potrzeby integracji. Dostawca usług w aplikacji dostawcy OSLC zawiera dane zasobów, które mogą być powiązane z danymi aplikacji konsumenckiej poprzez zastosowanie mechanizmów integracji między aplikacjami. Dane zasobów w programie IBM TRIRIGA mogą mieć postać tekstu w językach z kodowaniem wielobajtowym. Aby możliwa była integracja między aplikacją konsumencką a aplikacją dostawcy, konsument musi wykryć lub zidentyfikować dostawców usług dostępnych w aplikacji dostawcy. W programie IBM TRIRIGA dostawca usług może być bardzo prostu lub bardzo skomplikowany, jak np. aplikacja zawierająca wiele modułów i obiektów biznesowych. W programie IBM TRIRIGA można wykrywać dostawców usług, stosując następujące metody: v Z menu Narzędzia > Konfiguracja systemu > Integracja > Menedżer OSLC v Korzystając z identyfikatora URI: http://twoj_serwer/oslc/sp Każda z tych metod prowadzi do uzyskania listy dostawców usług. W następującym przykładzie przedstawiono identyfikator URI pracowników: http://twoj_serwer/oslc/sp/ Employee. Identyfikator URI wskazuje na dokument dostawcy usług zapisany w formacie RDF/XML. W formacie RDF/XML mogą być zapisane dokumenty kształtu, dostawcy usług, zasoby i dane zasobów. Aplikacja konsumencka może użyć formularza dostawcy usług do określenia, które zasoby i usługi są dostępne (np. zapytania, tworzenie). Dostawca usług OSLC realizuje funkcje fabryki tworzenia OSLC oraz obsługuje zapytania, udostępniając konsumentom identyfikatory URI służące do tworzenia lub wyszukiwania 4 Copyright IBM Corp. 2014, 2015

zasobów obsługiwanych przez dostawcę. Dokument dostawcy usług opisuje dostępne zasoby i odwzorowania przestrzeni nazw, a także operacje obsługiwane przez dostawcę usług w odniesieniu do tych zasobów. W poniższej przykładowej odpowiedzi odwołanie do dostawcy usług OSLC znajduje się we właściwości rdfs:member. Dokument dostawcy usług dla domeny zawiera identyfikator URI zadania: <rdf:rdf> <rdf:description rdf:about="http://yourserver/oslc/sp"> <rdfs:member rdf:resource="http://yourserver/oslc/sp/worktask"> </rdf:description> </rdf:rdf> Przestrzenie nazw OSLC W rozwiązaniu OSLC definiowane są ogólne przestrzenie nazw. Właściwość prefixdefinition zapewnia wyświetlanie wszystkich odwzorowań przedrostków na przestrzenie nazw używanych przez dostawcę usług do opisywania zarządzanego zasobu. Przestrzeń nazw właściwości musi się kończyć znakiem # lub /. Przykładowo: http://yourserver/ns/property#. W poniższej tabeli przedstawiono przykładowe przestrzenie nazw OSLC: Przedrostek rdf oslc dcterms asset foaf rdfs rr spi Przestrzeń nazw http://www.w3.org/1999/02/22-rdf-syntax-ns# http://open-services.net/ns/core# http://purl.org/dc/terms/ http://open-services.net/ns# http://xmlns.com/foaf/0.1/ http://www.w3.org/2000/01/rdf-schema# http://jazz.net/ns/ism/registry# http://jazz.net/ns/tririga Poniższy fragment pochodzący z sekcji usługi w dokumencie dostawcy usług zawiera przestrzenie nazw OSLC oraz RDF: <oslc:serviceprovider rdf:about="http://yourserver/oslc/sp/worktask"> <oslc:prefixdefinition> <oslc:prefixdefinition> <oslc:prefixbase rdf:resource="http://open-services.net/ns/core#"/> <oslc:prefix>oslc</oslc:prefix> </oslc:prefixdefinition> </oslc:prefixdefinition> <oslc:prefixdefinition> <oslc:prefixdefinition> <oslc:prefixbase rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#"/> <oslc:prefix>rdf</oslc:prefix> </oslc:prefixdefinition> </oslc:prefixdefinition> Operacje i zasoby OSLC Dostawca usług OSLC realizuje operacje fabryki tworzenia oraz obsługuje funkcje zapytania w przypadku zasobów dostępnych w dokumencie dostawcy usługi. Fabryka tworzenia zapewnia identyfikator URI pozwalający na utworzenie oslc:creation używanego do opracowania nowych zasobów za pomocą metody HTTP POST. Za pomocą identyfikatora Rozdział 2. Integracja w roli konsumenta OSLC 5

URI zapytania oslc:querybase można wybrać zbiór zasobów zarządzany przez dostawcę usług. Po uzyskaniu zasobu przez zapytanie lub utworzenie zasób można aktualizować lub usunąć. Operacja fabryki tworzenia Jeśli zasób obsługuje tworzenie, może istnieć jedna operacja fabryki tworzenia. Poniższy fragment pochodzący z dokumentu dostawcy usług zawiera operację fabryki tworzenia, adres URL kształtu zasobu i URL operacji zasobu tworzenia tworzącej kształt. <oslc:creationfactory> <oslc:creationfactory> <oslc:resourcetype rdf:resource="http://jazz.net/ns/tririga#worktask"/> <oslc:resourceshape rdf:resource="http://yourserver/oslc/shapes/worktask"/> <oslc:creation rdf:resource="http://yourserver/oslc/so/worktask"/> <oslc:label>create WorkTask</oslc:label> <dcterms:title>oslc creation factory for WorkTask</dcterms:title> </oslc:creationfactory> </oslc:creationfactory>... Operacja funkcji zapytania Identyfikator URI zapytania to oslc:querybase, a w poniższym przykładzie przedstawiono wyszukiwanie zadania roboczego za pomocą zlecenia: <oslc:querybase rdf:resource="http://nazwaserwera/oslc/spq/oslcwodetail"/>: <oslc:querycapability> <oslc:querycapability> <oslc:resourcetype rdf:resource="http://jazz.net/ns/tririga#worktask"/> <oslc:querybase rdf:resource="http://yourserver/oslc/so/worktask"/> <oslc:labelquery>worktask</oslc:label> <dcterms:taskname>oslc query capability for WorkTask</dcterms:taskname> </oslc:querycapability> </oslc:querycapability> Po zdefiniowaniu kształtu zasobu OSLC wszystkie zapytania są dostępne poprzez dostawcę usług. Udostępnianie zapytań odbywa się za pomocą funkcji zapytań OSLC. Kształt zasobu OSLC można zdefiniować za pomocą raportu opracowywanego w Menedżerze raportówibm TRIRIGA. Kształt zasobów używa raportu jako szablonu w celu zdefiniowania właściwości dostępnych dla zasobu. Te właściwości są zwracane po uruchomieniu funkcji zapytania. Każda funkcja zapytania zawiera właściwość o nazwie podstawa zapytania, która jest używana do stosowania rozszerzonych kryteriów w zasobie. Za pomocą tych kryteriów można wstępnie zdefiniować filtry dla tego samego kształtu. Pole Podstawa zasobu w funkcji zapytania zawiera nazwę zapytania zgodną z zapytaniem, na podstawie którego zdefiniowano zasób. Jeśli to zapytanie jest zdefiniowane, jest ono używane do filtrowania. W zapytaniu można użyć parametrów TRIRIGA takich jak $$USERID$$, $$RECORDID$$ lub $$PARENT::SECTIONAME::FIELDNAME$$. Podstawa zapytania to lista, a jej zawartość zmienia się wraz ze zmianami wprowadzanymi w zasobie. Przykładowo: zapytanie MyWorkTask zwraca listę zadań roboczych, które są przypisane do użytkownika odpowiadającego za zlecenie zapytanie. Kształty zasobów Kształt zasobu to plik w formacie RDF (Resource Description Framework) zawierający opis typów danych zasobu, jakie mogą być używane w interakcjach. Kształt zawiera listę atrybutów zasobu. Plik RDF zasobu można wyświetlić na karcie Podgląd formularza zasobu. 6 Copyright IBM Corp. 2014, 2015

Kształt zasobu jest podobny do schematu XML w tym sensie, że definiuje strukturę danych zasobu. Dokumenty kształtu Dokument kształtu w rozwiązaniu OSLC stanowi elektroniczny sposób przedstawienia zasobu wraz ze wszystkimi zależnościami, atrybutami i właściwościami. Przykładowo: dokument kształtu zadania roboczego zawiera listę szczegółowych informacji dotyczących zasobu zadania roboczego. Dokumenty kształtów obejmują wszystkie zasoby, w tym aktywa, firmy, zamówienia i zadania robocze. W dokumencie kształtu zawarto również wymagane elementy. Dokument kształtu zasobu może zawierać połączenia z dokumentami kształtu obiektów podrzędnych. Dokumenty kształtu są zapisywane w formacie RDF/XML. Kształt zasobu zawiera właściwości, działania, i zasoby połączone zdefiniowane dla zasobu. W rozwiązaniu IBM TRIRIGA podczas tworzenia nowego zasobu za pomocą formularza zasobu OSLC należy określić moduł, obiekt biznesowy i zapytanie dot. obiektu biznesowego. Można również wybrać moduł i zapytanie o wiele zasobów biznesowych. Na początek w rozwiązaniu IBM TRIRIGA należy utworzyć zapytanie. W przypadku tworzenia kolumn wyświetlania w zapytaniu użytkownik definiuje właściwości wstępne. Za pomocą czynności Importuj wszystkie pola dostępnej w formularzu można zaimportować kolumny wyświetlania z zapytania w postaci właściwości zasobu. Podczas importowania następuje próba określenia dla pól IBM TRIRIGA wartości odpowiednich dla OSLC na przykład wartości tylko do odczytu. Po zaimportowaniu można modyfikować pola oraz usuwać właściwości. Właściwość dcterms:identifier pozwala na utworzenie ID rekordu podczas importowania. Pole trirecordidsy jest wymagane, jeśli użytkownik planuje aktualizowanie zasobu. W poniższej tabeli przedstawiono sposób przypisywania pól IBM TRIRIGA do typów wartości właściwości OSLC: Typ pola IBM TRIRIGA Logiczne Obiekt biznesowy Klasyfikacja Zestawienie klasyfikacji Kolor Numer kontrolny Data Data i godzina Czas trwania Zestawienie finansowe Obraz Tylko etykieta Lista Numer Typ wartości właściwości OSLC OslcPropertyValueType.Boolean OslcPropertyValueType.String OslcPropertyValueType.String OslcPropertyValueType.Decimal OslcPropertyValueType.String Uwaga: identyfikator URI musi być kodowany jako URL podczas filtrowania pod względem kolorów pól. Symbol # należy zastąpić za pomocą ciągu znaków %23. OslcPropertyValueType.String OslcPropertyValueType.String OslcPropertyValueType.String OslcPropertyValueType.String OslcPropertyValueType.Decimal OslcPropertyValueType.String OslcPropertyValueType.String OslcPropertyValueType.String OslcPropertyValueType.Decimal Rozdział 2. Integracja w roli konsumenta OSLC 7

Typ pola IBM TRIRIGA Hasło Tylko do odczytu - system Tekst Czas UOM Url Typ wartości właściwości OSLC OslcPropertyValueType.String OslcPropertyValueType.String OslcPropertyValueType.String OslcPropertyValueType.String OslcPropertyValueType.String OslcPropertyValueType.String Zasób połączony wskazuje zasób przeznaczony do połączenia. Zapewnia on łańcuchy powiązania opisujące relację. Poniżej przedstawiono przykładowe łańcuchy powiązania: Zawiera zasób, Zarządza i Przypisany Do Zasób połączony można dodać do właściwości. Zasób połączony jest dozwolony i opcjonalny w przypadku pól lokalizatora i sekcji inteligentnych. Przykład: dokument kształtu zadania roboczego Dokument kształtu zadania roboczego zawiera listę wszystkich właściwości, atrybutów i zależności zadania roboczego. Poniższy kod prezentuje fragment dokumentu kształtu zadania roboczego o nazwie WorkTask. W tym dokumencie kształtu zasobu są zawarte cztery właściwości, ale dokument może zawierać wiele właściwości. <rdf:rdf xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:oslc="http://open-services.net/ns/core#" xmlns:spi="http://jazz.net/ns/tririga/property#" xmlns:dcterms="http://purl.org/dc/terms/"> <oslc:resourceshape rdf:about="http://yourserver/oslc/shapes/worktask"> <oslc:property> <oslc:property> <oslc:representation rdf:resource="http://open-services.net/ns/core#either"/> <oslc:readonly>false</oslc:readonly> <oslc:occurs rdf:resource="http://open-services.net/ns/core#exactly-one"/> <oslc:valuetype rdf:resource="http://www.w3.org/2001/xmlschema#string"/> <dcterms:title rdf:datatype="http://www.w3.org/1999/02/22-rdf-syntax-ns#xmlliteral" >ID</dcterms:title> <oslc:name>recordinformation.triidtx>/oslc:name> <oslc:propertydefinition rdf:resource="http://jazz.net/ns/tririga/property#triidtx"/> </oslc:property> </oslc:property> <oslc:property> <oslc:property> <oslc:representation rdf:resource="http://open-services.net/ns/core#either"/> <oslc.readonly>false</oslc:readonly> <oslc:occurs rdf:resource="http://open-services.net/ns/core#exactly-one"/> <oslc:valuetype rdf:resource="http://www.w3.org/2001/xmlschema#datetime"/> <oslc:defaultvalue>timestamp</oslc:defaultvalue> <dcterms:title rdf:datatype="http://www.w3.org/1999/02/22-rdf-syntax-ns#xmlliteral" >Planned Start</dcterms:title> <oslc:name>recordinformation.triplannedstartdt</oslc:name> <oslc:propertydefinition rdf:resource="http://jazz.net/ns/tririga/property#triplannedstartdt"/> </oslc:property> </oslc:property> <oslc:property> <oslc:property> <oslc:representation rdf:resource="http://open-services.net/ns/core#either"/> <oslc:readonly>true</oslc:readonly> <oslc:occurs rdf:resource="http//open-services.net/ns/core#exactly-one"/> <oslc:valuetype rdf:resource="http://www.w3.org/2001/xmlschema#decimal"/> <dcterms:title rdf:datatype="http//www.w3.org/1999/02/22-rdf-syntax-ns#xmlliteral" >Actual Total Cost</dcterms:title> <oslc:name>recordinformation.triactualtotalcostnu</oslc:name> <oslc:propertydefinition rdf:resource="http://jazz.net/ns/tririga/property#triactualtotalcostnu"/> </oslc:property> </oslc:property> <oslc:property> <oslc:property> <oslc:representation rdf:resource="http://open-services.net/ns/core#either"/> <oslc:readonly>false</oslc:readonly> <oslc:occurs rdf:resource="http//open-services.net/ns/core#exactly-one"/> <oslc:valuetype rdf:resource="http://www.w3.org/2001/xmlschema#string"/> <dcterms:title rdf:datatype="http//www.w3.org/1999/02/22-rdf-syntax-ns#xmlliteral" >Task Name</dcterms:title> <oslc:name>recordinformation.trinametx</oslc:name> <oslc:propertydefinition rdf:resource="http://jazz.net/ns/tririga/property#trnametx"/> 8 Copyright IBM Corp. 2014, 2015

</oslc:property> </oslc:property> <dcterms:title>worktask</dcterms:title> </oslc:resourceshape> </rdf:rdf> Pola numerów: Atrybut dla skali jest podawany dla pól numerów w OSLC. Skala to liczba cyfr po prawej stronie miejsca dziesiętnego liczby. Jeśli numer posiada niestandardową maskę wyświetlania, wartość skali, która jest zwracana opiera się na niestandardowej masce wyświetlania. Jeśli brakuje maski wyświetlania i nie istnieje zestaw jednostek miary (JM), domyślnie jest zwracana wartość obydwu. Jeśli istnieje jeden zestaw JM dla pola numerów i nie ustawiono maski wyświetlania dla pola, zwracana jest skala maski wyświetlania JM. Znaki 0 i # w masce wyświetlania są uwzględniane podczas określania skali. Przykład: skala w polach numerów Następujący przykład przedstawia zwracane wyniki z wartością skali wynoszącą 3: <oslc:property> <oslc:property> <spi:scale> 3 </spi:scale> <oslc:valuetype rdf:resource="http://www.w3.org/2001/xmlschema#decimal"/> <oslc:readonly>false</oslc:readonly> <oslc:occurs rdf:resource="http://open-services.net/ns/core#zero-or-one" /> <dcterms:title rdf:datatype="http://www.w3.org/1999/02/22-rdf-syntax-ns#xmlliteral"> Cost </dcterms:title> <oslc:name> tricostnu </oslc:name> <oslc:propertydefinition rdf:resource="http://jazz.net/ns/spi#tricostnu" /> </oslc:property> </oslc:property> Właściwości listy i JM: Można wyświetlić wartości, które są dozwolone w przypadku właściwości listy jednostki miary. Właściwość JM lub listy zawiera element oslc:allowedvalues, który obejmuje identyfikator URI zasobu. Identyfikator URI zwraca listę dostępnych wartości, które można użyć w przypadku właściwości tej listy lub JM. Przykład W poniższym przykładzie przedstawiono właściwość z elementem oslc:allowedvalues oraz listę dozwolonych wartości wynikających z identyfikatora URI w elemencie: <oslc:property> <oslc:property> <oslc:defaultvalue>japan Yen</oslc:defaultValue> <oslc:readonly>false</oslc:readonly> <oslc:valuetype rdf:resource="http://www.w3.org/2001/xmlschema#string" /> <oslc:usage rdf:resource="http://jazz.net/ns/ism/datatypes/ smarter_physical_infrastructure#uom" /> <oslc:occurs rdf:resource="http://open-services.net/ns/core#zero-or-one" /> <oslc:name>exampleuom</oslc:name> <dcterms:title rdf:datatype="http://www.w3.org/1999/02/22-rdf-syntax-ns#xmlliteral"> exampleuom</dcterms:title> <oslc:allowedvalues rdf:resource="http://yourserver/oslc/system/list/ Rozdział 2. Integracja w roli konsumenta OSLC 9

resourcename/spi:exampleuom" /> <oslc:propertydefinition rdf:resource="http://jazz.net/ns/spi#exampleuom" /> </oslc:property> </oslc:property> <rdf:rdf> <oslc:allowedvalues rdf:about="http://yourserver/oslc/system/list/ resourcename/spi:exampleuom"> <oslc:allowedvalues> <oslc:allowedvalues> <oslc:allowedvalue>us Dollars</oslc:allowedValue> <oslc:allowedvalue>swedish Krona/Kronor</oslc:allowedValue> <oslc:allowedvalue>brazilian Real</oslc:allowedValue> <oslc:allowedvalue>russian Ruble</oslc:allowedValue> <oslc:allowedvalue>norwegian Krone</oslc:allowedValue> <oslc:allowedvalue>new Zealand Dollars</oslc:allowedValue> <oslc:allowedvalue>united Kingdom Pounds</oslc:allowedValue> <oslc:allowedvalue>thai Baht</oslc:allowedValue> <oslc:allowedvalue>canadian Dollars</oslc:allowedValue> <oslc:allowedvalue>egyptian Pound</oslc:allowedValue> <oslc:allowedvalue>euro</oslc:allowedvalue> <oslc:allowedvalue>polish Zloty</oslc:allowedValue> <oslc:allowedvalue>korea Won</oslc:allowedValue> <oslc:allowedvalue>hungarian Forint</oslc:allowedValue> <oslc:allowedvalue>south Africa Rand</oslc:allowedValue> <oslc:allowedvalue>switzerland Francs</oslc:allowedValue> <oslc:allowedvalue>japan Yen</oslc:allowedValue> <oslc:allowedvalue>australia Dollars</oslc:allowedValue> <oslc:allowedvalue>israeli New Shekel</oslc:allowedValue> <oslc:allowedvalue>danish Krone</oslc:allowedValue> <oslc:allowedvalue>indian Rupees</oslc:allowedValue> <oslc:allowedvalue>clindiarupee</oslc:allowedvalue> </oslc:allowedvalues> </oslc:allowedvalues> </oslc:allowedvalues> </rdf:rdf> Znaczniki ETag Znacznik ETag (znacznik obiektu) to nagłówek HTTP używany do sprawdzania, czy klient (np. urządzenie mobilne) dysponuje najnowszą wersją rekordu. W przypadku wykonania zlecenia GET znacznik ETag jest zwracany jako nagłówek odpowiedzi. Znacznik ETag pozwala również klientowi na wykonanie zleceń warunkowych. Poza obsługą podstawowych metod aktualizacji HTTP PUT i HTTP PATCH rozwiązanie OSLC również obsługuje aktualizacje warunkowe. Aktualizacje warunkowe używają znaczników obiektów HTTP i nagłówków If-Match w celu sprawdzania, czy klienty dysponują najnowszymi obiektami dla zasobów. Ten proces ten używany do wykrywania nieprawidłowych aktualizacji warunków śledzenia. Przykładowo: jeśli dwa klienty wczytują ten sam zasób, rozwiązanie OSLC przesyła nagłówek ETag z odpowiedzią. Wartością znacznika ETag jest data i godzina ostatniej aktualizacji zasobu. Klient przechowuje wartość nagłówka ETag i wysyła jako część nagłówka HTTP If-Match dla kolejnego zlecenia aktualizacji. Serwer ocenia nagłówek If-Match i określa, czy klient dysponuje starą wersją czy najnowszą wersją zasobu. Jeśli serwer określi, że wersja klienta jest stara, odsyła odpowiedź HTTP 412 precondition failed. Klient otrzymuje ponownie zasób i przesyła zlecenie oparte na zaktualizowanym znaczniku ETag. Jeśli jednak serwer określi, że klient wersja jest najnowszą wersją, aktualizacja jest wdrażana, o ile nie znaleziono sprawdzenia poprawności biznesowej lub ograniczeń bazy danych. Klient może również przesłać zlecenie bez nagłówka If-Match lub z wartością nagłówka If-Match określoną jako * (gwiazdka). Przesłanie takiego zlecenia jest semantycznie równoznaczne z brakiem nagłówka If-Match w zleceniu aktualizacji. W obu przypadkach 10 Copyright IBM Corp. 2014, 2015

aktualizacja jest bezwarunkowa. Jeśli zasób, który jest określony przez identyfikator URI istnieje i nie znaleziono sprawdzeń biznesowych ani ograniczeń bazy danych, aktualizacja jest wdrażana. Identyfikatory URI IBM TRIRIGA dla OSLC Identyfikatory URI używane w celu nawiązania połączenia IBM TRIRIGA za pomocą OSLC są niepowtarzalne. Połączenie z IBM TRIRIGA można uzyskać za pomocą poniższych identyfikatorów URI: OSLC component Strona zasobów systemowych Logowanie Wylogowanie Fabryka tworzenia Funkcja zapytania Szczegóły zapytania Kształt zasobu Dostawca usług Opis http://yourserver/oslc http://yourserver/oslc/login http://yourserver/oslc/logout http://yourserver/oslc/so http://yourserver/oslc/spq http://yourserver/oslc/so http://yourserver/oslc/shapes Aby uzyskać dostęp do strony kształtu zasobu, należy wprowadzić adres: http://yourserver/oslc/ shapes/resourceshapename http://yourserver/oslc/sp Rozdział 2. Integracja w roli konsumenta OSLC 11

12 Copyright IBM Corp. 2014, 2015

Rozdział 3. Praca z zasobami OSLC Za pomocą metod HTTP można definiować sposoby tworzenia, usuwania aktualizowania zasobów OSLC przez użytkowników oraz tworzenia zapytań dot. zasobów. Zabezpieczenia IBM TRIRIGA są stosowane we wszystkich czynnościach dotyczących danych. Użytkownik nie można utworzyć, zaktualizować, usunąć rekordu ani utworzyć zapytania dot. rekordu bez odpowiedniego poziomu obsługi zabezpieczeń. Zapytania dot. zasobów OSLC Można tworzyć zapytania dot. zasobów OSLC, korzystając z metody HTTP GET lub HTTP POST. Zmieniając parametry zapytania, można sterować sposobem wyszukiwania zasobów przez użytkowników. OSLC definiuje prostą składnię zapytania pozwalającą tworzyć zapytania dot. zasobów opartą na standardzie SPARQL. Zapytanie z użyciem metod GET lub POST Podczas opracowywania zapytań dot. zasobów OSLC można użyć metod HTTP GET lub HTTP POST. Podczas opracowywania zapytań dot. zasobów OSLC za pomocą metody HTTP GET w identyfikatorze URI należy określić parametry. Jeśli identyfikator URI jest dłuższy niż 2000 znaków, należy opracować zapytanie za pomocą metody HTTP POST, a nie HTTP GET. Metody HTTP POST można również użyć, jeśli identyfikator URI jest krótszy niż 2000, ale nadal długi, lub jeśli użytkownik chce ukryć parametry zapytania, aby nie były wyświetlane w URI. W przypadku zapytań z użyciem metody HTTP POST należy określić dla nagłówka HTTP Content-Type ustawienie application/x-www-form-urlencoded, przesłać identyfikatory URI bez parametrów i określić parametry zapytania w treści zlecenia HTTP. Przykład: zapytanie za pomocą metody HTTP GET Poniżej przedstawiono przykład zapytania za pomocą metody HTTP GET. Wszystkie parametry zapytania są wyświetlane w identyfikatorze URI. http://yourserver/oslc/spq/worktaskquery?oslc.select= spi:trinametx,spi:rca{spi:trircaremedycl}&oslc.where= spi:rca{spi:trircaremedycl="clean"}&oslc.orderby=%2bspi:trinametx Przykład: zapytanie za pomocą metody HTTP POST Poniżej przedstawiono przykład tego samego zapytania wykonanego za pomocą metody HTTP POST. Identyfikator URI zostanie skrócony. http://yourserver1/oslc/spq/worktaskquery Treść HTTP Treść zlecenia HTTP zawiera wszystkie parametry zapytania. oslc.select=spi:trinametx,spi:rca{spi:trircaremedycl}&oslc.where= spi:rca{spi:trircaremedycl="clean"}&oslc.orderby=%2bspi:trinametx Copyright IBM Corp. 2014, 2015 13

Parametry zapytania OSLC Parametry zapytania OSLC zapewniają opcje określające sposoby opracowywania zapytań dot. zasobów OSLC. Przykładowo: parametr oslc.orderby definiuje kolejności wyników zapytania. Obsługiwane parametry zapytania HTTP OSLC to: oslc.properties, oslc.where, oslc.orderby, oslc.select, oslc.pagesize i pageno. Jeśli właściwość nie znajduje się w sekcji Ogólne formularza, należy określić nazwę sekcji właściwości w formacie nazwasekcji#nazwapola. Na przykład tridetails#tritasktypecl. Parametr oslc.properties Parametr zapytania oslc.properties określa listę właściwości zasobu OSLC. Właściwości mogą pochodzić z zasobu lub zasobów połączonych. Jest on używany w celu uzyskania częściowej reprezentacji zasobu. Parametru oslc.properties nie można stosować w zbiorach zasobów. Kolekcja zasobów to zasób OSLC zawierający inne zasoby OSLC jako elementy składowe. Przykład: zlecenia atrybutów W poniższym przykładowym zleceniu określono, że wartości atrybutów shorttitle i istask są zwracane w wynikach: http://yourserver/oslc/so/worktask/ 337?oslc.properties=oslc:shortTitle,spi:isTask Przykład: zlecenia atrybutów z zasobów połączonych W poniższym zleceniu określono, że wartość nazwy organizacji klienta jest zwracana w wynikach: http://yourserver/oslc/so/worktask/ 13353622?oslc.properties=*,spi:triCustomerOrgTX{spi:triNameTX} To zlecenie zapewnia utworzenie następujących wyników: { spi:trinametx: "WorkTask" spi:tristatuscl: "Draft" spi:triidtx: "1027019" -spi:tricustomerorgtx: { spi:trinametx: "Company 01" rdf:about: "http://yourserver/oslc/so/organizationrs/12877121" } rdf:about: "http://yourserver/oslc/so/triworktaskrs/13353622" -trira:action: [10] 0: "tridelete" 1: "triinvaliduploadhidden" 2: "triissue" 3: "tribaseline" 4: "triapplytemplate" 5: "tricopy" 6: "triplanhidden" 7: "trisave" 8: "trisaveandclose" 9: "tritemporarytemplate" -prefixes: { oslc: "http://open-services.net/ns/core#" rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#" trira: "http://jazz.net/ns/tririga#" dcterms: "http://purl.org/dc/terms/" } } 14 Copyright IBM Corp. 2014, 2015

parametr oslc.where Parametr oslc.where określa klauzulę WHERE filtrowania zestawu wyników zapytania. Przykładowo: użytkownik chce wyświetlić listę zasobów zadań roboczych OSLC utworzonych w danym zakresie czasowym i zatwierdzonych przez zarząd. Filtrowanie można wykonać według zasobów połączonych z zastosowaniem parametru oslc.where. Przykładowo: użytkownik może chcieć filtrować osoby według nazwiska przełożonego. Klauzula WHERE OSLC obsługuje następujące, podstawowe operatory porównawcze: Symbol Opis = Equality v "wartość" = równe v "%wartość" = kończy się na v "wartość%" = rozpoczyna się od v "%wartość%" = zawiera Należy zwrócić uwagę, że ręczne wpisanie identyfikatora URI z symbolem % jako fragmentem wyszukiwanym wymaga zakodowania symbolu w następujący sposób: "%25wartość"!= Inequality < Less than > Greater than <= Less than or equal to >= Greater than or equal to Jeśli wymagane jest filtrowanie pod kątem elementów pustych lub innych niż puste, należy wprowadzić słowo null po symbolu. Wymogi parametru oslc.where Daty są wyrażane w formacie ISO 8601. W przypadku typów pól Data i Godzina w milisekundach przedstawiono, czy wartość pola jest niezerowa. Specyfikacja OSLC obsługuje operator and jako operator logiczny między wyrażeniami logicznymi. Operator logiczny or nie jest obsługiwany. W poniższym przykładzie wartość literału w przypadku statusu jest ujęta w cudzysłów ponieważ właściwość statusu zawiera typ danych łańcuch. Wartość ilości nie jest ujęta w cudzysłów, ponieważ jest to dziesiętna wartość danych. Liczby całkowite i wartości logiczne również nie wymagają ujęcia w cudzysłów. Przykładowo: spi:status="zamknięty" and spi:quantity>10.5 and spi:active=true gdzie spi:active zawiera typ danych logicznych. Specyfikacja OSLC obsługuje operator or niejawnie w ramach pojedynczej właściwości, używając operatora in. Przykładowo: aby wyświetlić wszystkie zadania robocze o statusie Wydane lub Aktywne, należy użyć zapytania spi:status in ["Wydane","Aktywne"] Przykładowo: wyszukiwanie zadań roboczych utworzonych w danym zakresie czasowym i zatwierdzonych Użycie poniższej klauzuli powoduje wyświetlenie listy zasobów zadań roboczych utworzonych w określonym zakresie czasowym: Rozdział 3. Praca z zasobami OSLC 15

spi:status="zatwierdzone" and dcterms:created>"2003-07-07t09:50:00-04:00" and dcterms:created<="2004-07-07t09:50:00-04:00". Używanie parametru oslc.orderby w celu określania kolejności sortowania Parametr oslc.orderby umożliwia zdefiniowanie kolejności wyświetlania wyników zapytania. Przykładowo: listę zadań roboczych można uszeregować wg daty lub ID. Aby uszeregować zadania robocze rosnąco wg daty utworzenia i szacowanego czasu trwania, należy użyć następującego parametru oslc.orderby: +dcterms:created,- spi:estimatedduration. Znak + określa sortowanie rosnące, a znak - sortowanie malejące. Wartości są rozdzielane przecinkami. Następujący parametr oslc.orderby jest nieprawidłowy, ponieważ nie istnieje domyślne sortowanie w składni zapytania OSLC: dcterms:created,-spi:estimatedduration. Musi istnieć jawny znak + or - przy nazwie właściwości. Parametr oslc.orderby również obsługuje właściwości zagnieżdżone, np. dcterms:creator{+foaf:name}. W rzeczywistych adresach URL znaki + i - nie działają. Zamiast nich, w adresie URL należy użyć ciągów %2B i %2D. Przykład: sortowanie oparte na zasobach połączonych Pól zasobów połączonych można użyć jako kryteriów kolejności w celu sortowania rekordów nadrzędnych i zasobów połączonych w rekordach nadrzędnych. Przykładowo: mogą istnieć dwa główne obiekty, które są nazwane M1 i M2. M1 zawiera dwa zasoby połączone o nazwach L1 i L3, a M2 zasoby połączone L2 i L4. Jeśli obiekty główne zostaną posortowane rosnąco bez uwzględniania zasobów połączonych, wynikami będą M1, M2. Jeśli obiekty główne zostaną posortowane malejąco, wynikami będą M2, M1. Jednak ponieważ istnieje wiele zasobów połączonych w przypadku obiektów, podczas sortowania malejącego lub rosnącego zasoby połączone również są sortowane. L1 i L3 są sortowane w M1, L2, a L4 w M2. Parametr oslc.select Parametr oslc.select umożliwia określenie zlecenia dotyczącego częściowej reprezentacji zbioru zasobów składowych. Parametr oslc.select jest zawsze stosowany do zasobów w zbiorze. Należy określić listę właściwości uwzględnionych w zleceniu. Wybrane właściwości mogą pochodzić z zasobu lub zasobów połączonych. Przykład: zlecenia dot. zasobu częściowego Parametr oslc.select zapewnia listę kwalifikowanych nazw właściwości rozdzielonych przecinkami. Parametr oslc.prefix nie jest obsługiwany. Poniższe zlecenie jest przykładem zlecenia dot. zasobu częściowego: oslc.select=oslc:shorttitle,dcterms:creator Przykład: właściwości z zasobów dowiązanych Dzięki parametrowi oslc.select można wybrać właściwości z zasobów dowiązanych. Aby pobrać informacje, takie jak nazwa twórcy, należy określić instrukcję SELECT jako oslc.select= oslc:shorttitle,dcterms:creator{foaf:name}. 16 Copyright IBM Corp. 2014, 2015

Zasób foaf:person jest nazwą osoby określonej w wartości właściwości twórca. Aby uzyskać wszystkie właściwości z zasobu, można użyć ciągu oslc.select=*. Tej samej składni można użyć w przypadku parametru oslc.properties podczas wyszukiwania zasobu OSLC. Przykład: właściwości z zasobów połączonych Dzięki parametrowi oslc.select można wybrać właściwości z zasobów połączonych. Aby pobrać informacje, takie jak wartość nazwy organizacji klienta, należy określić instrukcję SELECT jako http://yourserver/oslc/spq/worktaskqc?oslc.select=*,spi:tricustomerorgtx{spi:trinametx} &oslc.where=spi:tricustomerorgtx!="null" Użycie instrukcji SELECT zapewnia następującą odpowiedź: { -rdf:members: [1] -0: { spi:trinametx: "WorkTask" spi:tristatuscl: "Draft" spi:triidtx: "1027019" -spi:tricustomerorgtx: { spi:trinametx: "Company 01" rdf:about: "http://yourserver/oslc/so/organization/12877121" } rdf:about: "http://yourserver/oslc/so/worktask/13353622" -trira:action: [10] 0: "tridelete" 1: "triinvaliduploadhidden" 2: "triissue" 3: "tribaseline" 4: "triapplytemplate" 5: "tricopy" 6: "triplanhidden" 7: "trisave" 8: "trisaveandclose" 9: "tritemporarytemplate" } rdf:about: "http://yourserver/oslc/spq/worktask" -prefixes: { oslc: "http://open-services.net/ns/core#" rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#" spi: "http://jazz.net/ns/tririga#" dcterms: "http://purl.org/dc/terms/" } } parametr oslc.pagesize Parametr oslc.pagesize określa liczbę wyników na stronę zwracanych przez serwer. Przykładowo: oslc.pagesize=20 zapewnia, że zapytanie zwraca 20 wyników na stronę. Parametr pageno Tworzenie zasobów OSLC Parametr pageno określa stronę, którą zwraca serwer. Przykładowo: pageno=3 zapewnia, że zapytanie zwraca tylko dane z trzeciej strony. Utworzenie wystąpienia zasobu OSLC wymaga użycia metody HTTP POST. Następnie można udostępnić zasób innym aplikacjom i zaktualizować go za pomocą metod PUT, PATCH lub MERGE. Rozdział 3. Praca z zasobami OSLC 17

O tym zadaniu Klient OSLC przesyła dokument JSON zgodny z kształtem zasobu opublikowanym w dokumencie kształtu. Dane są przesyłane do rozwiązaniaoslc w treści zlecenia HTTP w formacie JSON, a nagłówek HTTP Content-Type jest określany jako MIME type application/json. Jeśli zlecenie zostanie przetworzone pomyślnie, klient OSLC otrzymuje nagłówek lokalizacji HTTP z identyfikatorem URI nowo utworzonego zasobu. Aby wyświetlić właściwości nowo utworzonego zasobu, można uwzględnić nagłówek właściwości w zleceniu i określić właściwości, które zostaną wyświetlone. Właściwość nagłówka o nazwie Właściwości jest zwracana i zawiera określone właściwości. Podczas tworzenia zlecenia można uwzględnić identyfikator transakcji w nagłówku zlecenia HTTP. Identyfikator transakcji musi być unikalny w obrębie wszystkich aplikacji klienta. OSLC zapisuje status identyfikatora transakcji w bazie danych po zakończeniu zlecenia. Jeśli użytkownik prześle zlecenie z identyfikatorem transakcji, OSLC sprawdza, czy w bazie danych istnieje transakcja. Jeśli transakcja istnieje, zlecenie w OSLC nie zostaje uruchomione. Zwracany jest błąd, który wskazuje, że zlecenie nie zostało zakończone z powodu istnienia identyfikatora transakcji. Poniżej przedstawiono przykładowy nagłówek z określonym identyfikatorem transakcji: Accept: application/rdf-xml transactionid: 6001 Content-Type: application/json;charset=utf-8 Jeśli zlecenie zostanie przetworzone pomyślnie, to klient OSLC otrzyma następującą odpowiedź: 201 Created Location: http://yourserver/oslc/so/worktask/10269 ETag: 1376596202470 W przypadku przesłania działania musi ono być prawidłowe w kontekście bieżącego stanu rekordu. Przykładowo: jeśli bieżącym stanem rekordu jest Projekt, działanie zapisu jest często prawidłowe. Działanie jest wywoływane po utworzeniu rekordu. Na stronie wyników zapytania (oslc/spq) jeśli parametr oslc.select zawiera symbol wieloznaczny(*), lub na stronie szczegółów zapytania (oslc/os), jeśli żaden parametr oslc.properties nie jest dostarczony, wyniki obejmują wszystkie działania, które można wykonać w przypadku każdego pobranego rekordu. Działanie jest przedstawione w postaci "tririga:action":["action1","action2",...]. Zlecenia OSLC mogą zakończyć się niepowodzeniem w wielu powodów, np. z powodu naruszeń biznesowych, uwierzytelnienia lub autoryzacji. Przykładowo: klient OSLC może otrzymać błąd 400 Bad Request wraz z treścią HTTP zawierającą szczegóły dot. tego błędu. Tworzenie rekordów zależnych od rekordów głównych Istnieje możliwość tworzenia zasobów zależnych powiązanych z rekordami głównymi. O tym zadaniu Można dodać powiązane rekordy zależne do rekordu głównego. Rodzaj powiązania zależy od zasobu głównego (nadrzędnego). Przykład: Tworzenie zamówienia z dwoma wierszami. Następująca metoda tworzy zasób reprezentujący zamówienie z dwoma zasobami reprezentujący wiersze. Zasób nadrzędny nosi nazwę HasPOLineItem. 18 Copyright IBM Corp. 2014, 2015

{ "spi:action":"create Draft (tricreatedraft)", "spi:trinametx":"oslcpo", "trirldr:haspolineitem": [ { "spi:action":"create (tricreate)", "spi:trinametx":"polineitem1" }, { "spi:action":"create (tricreate)", "spi:trinametx":"polineitem2" } ] } Aktualizacja zasobów OSLC Jeśli zlecenie zostanie przetworzone pomyślnie, to klient OSLC otrzyma następującą odpowiedź: 201 Created Location: http://yourserver/oslc/so/po/10269 ETag: 1376596202470 Za pomocą metody HTTP PUT można zastąpić zasób OSLC, a metoda HTTP POST z zastąpieniem PATCH pozwala na częściowe zaktualizowanie zasobu OSLC. Metoda HTTP PUT w pełni zastępuje dane w zasobie za pomocą właściwości w zleceniu. An HTTP POST with an x-method-override of PATCH replaces a local resource property with the content in the request. Metoda HTTP POST z parametrem x-method-override PATCH i PATCHTYPE określonym jako MERGE wyszukuje i dopasowuje elementy zasobu lokalnego ze zlecenia elementami na serwerze. W zależności, czy dopasowanie zostało znalezione, elementy zasobu lokalnego są aktualizowane lub wstawiane. Element lokalny nigdy nie jest usuwany z właściwości zasobu lokalnego. When you send an update request, you can include the transaction ID in the HTTP request header. Identyfikator transakcji musi być unikalny w obrębie wszystkich aplikacji klienta. OSLC zapisuje status identyfikatora transakcji w bazie danych po zakończeniu zlecenia. Jeśli użytkownik prześle zlecenie z identyfikatorem transakcji, OSLC sprawdza, czy w bazie danych istnieje transakcja. Jeśli transakcja istnieje, zlecenie w OSLC nie zostaje uruchomione. Zwracany jest błąd, który wskazuje, że zlecenie nie zostało zakończone z powodu istnienia identyfikatora transakcji. Poniżej przedstawiono przykładowy nagłówek z określonym identyfikatorem transakcji: Accept: application/rdf-xml transactionid: 6001 Content-Type: application/json;charset=utf-8 Metoda HTTP PUT Operacja HTTP PUT służy do pełnego zastępowania zasobu OSLC. Metody PUT powoduje zaktualizowanie właściwości literałów i zasobów lokalnych oraz usuwa wszelkie właściwości zasobów lokalnych, które nie są uwzględnione w zleceniu. Podczas korzystania z metody PUT w celu zastępowania zasobów OSLCobowiązują następujące reguły: v Wszystkie właściwości literałów określone w dokumencie zlecenia podlegają aktualizacji. Wszystkie właściwości literałów nieokreślone jako części zlecenia nie są uwzględniane Rozdział 3. Praca z zasobami OSLC 19

bezpośrednio w tej operacji. Jednak mogą one zostać uwzględnione niejawnie przez logikę biznesową dołączoną do zasobu. Ta reguła działa analogicznie do użycia metody PATCH w celu wykonania aktualizacji zasobu. v All local resource properties are replaced by corresponding property values from the request. Jeśli właściwość zasobu nie jest uwzględniona w zleceniu, odpowiedni zasób jest usuwany. Jeżeli właściwość zasobu jest uwzględniona, jego wartość zastępuje wartość na serwerze. v Zasobów referencyjnych nie można zaktualizować jawnie. Można jednak zaktualizować właściwości odnoszące się do zasobów i będą one zgodne z modelem aktualizacji właściwości literałów. Ta reguła działa analogicznie do użycia metody PATCH w celu wykonania aktualizacji zasobu. W poniższych przykładach zasób zadania roboczego zawiera jedną właściwość literału taskname oraz jedną właściwość zasobu parts. Właściwość parts wskazuje części zasobu lokalnego i jest powiązana z dwoma rekordami części. Jeśli zlecenie PUT zawiera właściwość taskname bez właściwości parts, nazwa zadania jest aktualizowana, a dane części są usuwane. Przykład: aktualizacja właściwości literału Poniższa metoda zapewnia aktualizowanie właściwości literału taskname: PUT http://yourserver/oslc/so/worktask/123 { } "dcterms:taskname": "Check-out Leaking Modified for Test" Jeśli zlecenie zostanie przetworzone pomyślnie, to klient OSLC otrzyma następującą odpowiedź: 204 No Content ETag: 1376596202470 Nazwa zadania zostanie zmieniona na Zwróć przecieki modyfikacje dla testów. Dane parts nie zostały uwzględnione w metodzie, więc rekordy części są usuwane. Przykład: aktualizacja właściwości zasobu lokalnego Poniższa metoda zapewnia aktualizowanie właściwości zasobu lokalnego parts: PUT http://yourserver/oslc/so/worktask/123 { spi:parts : [ { spi:partsid": "0000000067", "spi:quantity": 5 } ] } Jeśli zlecenie zostanie przetworzone pomyślnie, to klient OSLC otrzyma następującą odpowiedź: 204 No Content ETag: 1376596202470 Wykonywane jest wyszukiwanie rekordów części o ID 0000000067. Jeśli taki rekord części istnieje, zostanie on zaktualizowany. Jeśli nie, nowy rekord części zostanie utworzony. Wszystkie pozostałe dane części dla tego zasobu zadania roboczego są usuwane. Właściwość 20 Copyright IBM Corp. 2014, 2015

taskname nie została uwzględniona w metodzie, więc nazwa zadania nie jest częścią zlecenia, a wartość nie ulega zmianie. Metoda HTTP PATCH Metoda PATCH służy do częściowego aktualizowania zasobu OSLC. Metoda PATCH nie usuwa żadnych właściwości zasobów lokalnych nieuwzględnionych w zleceniu. Zlecenie PATCH jest przesyłane przez metodę POST z nagłówkiem x-method-override, dla którego określono opcję PATCH. Podczas korzystania z metody PATCH w celu zastępowania zasobów OSLCobowiązują następujące reguły: v Wszystkie właściwości literałów określone w dokumencie zlecenia podlegają aktualizacji. Wszystkie właściwości literałów nieokreślone jako części zlecenia nie są uwzględniane bezpośrednio w tej operacji. Jednak mogą one zostać uwzględnione niejawnie przez logikę biznesową dołączoną do zasobu. Ta reguła działa analogicznie do użycia metody PUT w celu zastąpienia zasobu. v Wszystkie właściwości zasobów lokalnych są aktualizowane lub zastępowane przez odpowiednie wartości właściwości ze zlecenia. Jeśli właściwość zasobu nie jest uwzględniona w zleceniu, odpowiedni zasób lokalny nie podlega jawnym zmianom. Jeżeli właściwość zasobu jest uwzględniona, jego wartość zastępuje lub aktualizuje wartość na serwerze. Inne właściwości zasobów są usuwane przez metodę PATCH, a nie przez MERGE. v Zasobów referencyjnych nie można zaktualizować jawnie. Można jednak zaktualizować właściwości odnoszące się do zasobów i będą one zgodne z modelem aktualizacji właściwości literałów. Ta reguła działa analogicznie do użycia metody PUT w celu zastąpienia zasobu. Przykład: aktualizacja właściwości literału Poniższa metoda zapewnia aktualizowanie właściwości nazwy zadania w przypadku zadania roboczego: POST http://yourserver/oslc/so/worktask/123 x-method-override: PATCH { } "dcterms:taskname": "Check-out Leaking Modified for Test" W przeciwieństwie do metody PUT ta metoda PATCH nie aktualizuje innych właściwości zadania roboczego. Przykład: aktualizacja właściwości zasobu lokalnego Poniższa metoda zapewnia aktualizowanie określonych rekordów części i usuwanie innych danych: POST http://yourserver/oslc/so/worktask/123 x-method-override: PATCH { "dcterms:taskname": "Check-out Leaking Modified for Test", spi:parts : [ { spi:partsid": "0000000067", "spi:quantity": 5 } ] } Rozdział 3. Praca z zasobami OSLC 21

Ta metoda działa podobnie do metody PUT. W systemie wykonywane jest wyszukiwanie rekordu części o ID 0000000067. Jeśli taki rekord części istnieje, zostanie on zaktualizowany. Jeśli nie, nowy rekord części zostanie utworzony. Wszystkie pozostałe rekordy części dla tego zasobu zadania roboczego są usuwane. Przykład: aktualizacja i scalanie właściwości zasobu lokalnego Poniższa metoda zapewnia aktualizowanie zasobu, w przypadku którego dla nagłówka PATCHTYPE wybrano opcję MERGE: POST http://yourserver/oslc/so/worktask/123 x-method-override: PATCH PATCHTYPE: MERGE { "dcterms:taskname": "Check-out Leaking Modified for Test", spi:parts : [ { spi:partsid": "0000000067", "spi:quantity": 5 } ] } Wykonywane jest wyszukiwanie rekordów części o ID 0000000067. Jeśli taki rekord części istnieje, zostanie on zaktualizowany. Jeśli nie, nowy rekord części zostanie utworzony. Dla nagłówka PATCHTYPE określono opcję MERGE, więc inne rekordy części dla tego zasobu zadania roboczego nie ulegają zmianie. Przykład: wykonywanie aktualizacji warunkowej Poniższa metoda zapewnia aktualizowanie zasobu, jeśli wartością znacznika ETag jest 1376596202470: POST http://yourserver/oslc/so/worktask/123 x-method-override: PATCH if-match: 1376596202470 Jeśli wartością znacznika ETag jest 1376596202470, zasób zadania roboczego jest aktualizowany i przesyłany jest komunikat HTTP 204. Jeśli wartością znacznika ETag nie jest 1376596202470, odpowiedzią serwera jest HTTP 412 Precondition failed. Ten komunikat oznacza, że zasób został zaktualizowany przez inny proces i klient zlecający dysponuje starą kopią zasobów. Klient musi wykonać metodę GET w zasobie 123 w celu uzyskania nowej kopii zasobu. W poniższej tabeli przedstawiono zestawienie wyników metod aktualizacji w przypadku różnych typów zasobów. Metoda Właściwości literałów Zasoby lokalne Zasoby referencyjne PUT PATCH W przypadku pominięcia właściwości dana właściwość nie ulega zmianie. W przypadku pominięcia właściwości dana właściwość nie ulega zmianie. W przypadku pominięcia właściwości dana właściwość jest usuwana. W przypadku pominięcia właściwości dana właściwość nie ulega zmianie. W przypadku pominięcia właściwości dana właściwość nie ulega zmianie. W przypadku pominięcia właściwości dana właściwość nie ulega zmianie. 22 Copyright IBM Corp. 2014, 2015